feat(dsh): add Guion-compatible managed presets

.scratch/dsh-managed-presets/implementation-report.md

@@ -0,0 +1,143 @@
+# DSH compatible presets implementation report
+
+## Scope
+
+- Repository: `guionai/web`
+- Branch: `dsh-managed-presets`
+- Fixed point: `1bb01fd` (`main`)
+- Final implementation commit: `3d7d4a1` (`refactor(dsh): simplify compatible preset sync`)
+- Delivery boundary: the complete `dsh-managed-presets` spec and tickets 01–04.
+
+## Outcome
+
+Guion's DSH bundle now owns the complete research surface:
+`web_search`, `web_fetch`, `web_links`, `web_docs`, and
+`web_source_search`. The official Web registry/provider integration and
+dependency are gone. The Guion implementations retain the selected search
+providers, namespaced credentials, fetch navigation/rendering options,
+cancellation, bounded output, and conditional Kepos tools.
+
+The bundle patch disables the official Web stack and hides shipped presets.
+It exposes only the user preset root, with `standard` as the default. The
+effective Guion schemas remain:
+
+- `web_search`: required `queries`
+- `web_fetch`: required `url`; optional `mode`, `section_id`, `render`, and
+  `waitMs`
+
+## Compatible preset workflow
+
+`web dsh sync` creates or refreshes `standard`, `ptc`, `cordis`, and `minimal`
+under the DSH user preset root. Each copy comes from the installed official
+`@deepseek-ai/dsh-agent-presets` package with the official `tool-web` entry
+removed structurally.
+
+There is no Guion marker file or persistent ownership metadata. For each
+same-ID directory, sync compares the complete tree with two snapshots:
+
+- an exact current compatible copy is safe to refresh;
+- an exact official copy is safe to convert;
+- any other content is treated as user-modified and requires interactive
+  confirmation, or `--yes` in automation.
+
+Non-interactive sync refuses modified same-ID directories unless `--yes` is
+present. Unrelated user presets are untouched. Replacement is staged per
+preset, with a local backup restored if installation fails; there is no global
+four-preset transaction or speculative race-hook machinery.
+
+`web dsh doctor` is read-only and reports each compatible preset as `ok`,
+`missing`, `stale` (an exact official copy), or `conflict` (any other content).
+
+## Documentation
+
+The workflow and the requirement to sync before selecting a compatible preset
+are documented in the root README and `packages/dsh-web/README.md`.
+`CONTEXT.md` defines the vocabulary, ADR 0004 records the ownership decision,
+and `AGENTS.md` records the test-state and real-Linux verification rules.
+
+## Verification
+
+Final local checks passed:
+
+- `pnpm test` — 20 files, 161 tests
+- `pnpm typecheck`
+- `pnpm build` — all four packages
+- `pnpm test:pack` — Web, Pi, and DSH package smoke checks
+- `pnpm format:check`
+- `pnpm test:release`
+- `git diff --check`
+
+The packed Web smoke no longer contains a fake DSH installation or a second
+sync/doctor test graph. Runtime discovery is covered by focused temporary
+filesystem tests, including a standard `node_modules/.bin/dsh` shim.
+
+The real integration check ran on `nuc-kep` from the existing checkout
+`/home/neil/code/projects/guionai/web`. `og pull` first fast-forwarded its
+current `main`; because `og pull` only fetches the current branch, the new
+remote feature ref was then fetched and checked out. The checkout was built
+with its installed pnpm, and the built Web CLI called the NUC's installed
+`dsh` executable. All mutable DSH state was isolated under:
+
+```text
+/tmp/guion-dsh-checkout.q3UxVE/dsh-home
+```
+
+The disposable profile linked the checkout's current `@guionai/dsh-web`
+package. No live yuki profile, credentials, preset root, or service was read or
+changed.
+
+Observed results:
+
+```text
+DSH compatible presets created all four presets from @deepseek-ai/dsh-agent-presets@0.1.2-rc.1.
+DSH doctor: OK
+- standard: ok
+- ptc: ok
+- cordis: ok
+- minimal: ok
+```
+
+The same run then exercised the overwrite policy:
+
+1. Replacing `standard` with the exact installed official preset was accepted
+   and converted without a prompt.
+2. Adding a user edit to `ptc` made non-interactive sync exit with status 1:
+   `refusing to overwrite modified same-id preset ptc; rerun interactively or pass --yes`.
+3. Re-running with `--yes` refreshed all four presets, after which doctor was
+   fully green again.
+
+The same disposable profile was then composed by the installed official Loader
+with a read-only probe bundle. The reconciled config contained
+`includeShippedRoot: false`, `includeUserRoot: true`, and `default: standard`;
+the installed `@guionai/dsh-web` link resolved exactly to the NUC checkout.
+The Loader booted successfully and was stopped immediately after the probe:
+
+```text
+standard user rows=26 broken=absent tool-web=0
+ptc user rows=27 broken=absent tool-web=0
+minimal user rows=8 broken=absent tool-web=0
+cordis user rows=27 broken=absent tool-web=0
+web_fetch properties=url,mode,section_id,render,waitMs required=url
+web_search properties=queries required=queries
+```
+
+The probe output is `/tmp/guion-dsh-checkout.q3UxVE/probe.json`. The disposable
+Loader process was confirmed stopped, and its token-bearing launch URL was not
+recorded.
+
+Vitest emits the existing non-failing missing source-map warning from the DSH
+primitives package.
+
+## Size
+
+Against `1bb01fd`, excluding the lockfile and this report, the final diff is
+2,144 additions and 521 deletions (2,665 changed lines). The simplified sync
+removed 901 lines and added 392 relative to the previously reviewed branch:
+the marker protocol, global transaction, injected rename hooks, shim-text
+parser, and packed fake-DSH smoke were deleted.
+
+## Acceptance result
+
+The whole spec is implemented and verified. The final workflow uses content
+comparison plus explicit confirmation, keeps upstream DSH unchanged, and uses
+the NUC's real CLI for Linux integration verification.

AGENTS.md

@@ -6,4 +6,17 @@ Repository CI and local tests target Linux. Treat Windows behavior as best-effor
 
 ## DSH rc.1 Loader validation
 
-For profile-local packaged plugins on DSH `0.1.2-rc.1` with Node 24, install the official rc.1 CLI into a test-owned disposable directory and validate its real installed graph through the Node entrypoint with internals enabled: `node --expose-internals <disposable-install>/node_modules/@deepseek-ai/dsh/lib/bin.js ...`. Keep `DSH_HOME` test-owned and disposable, do not use a deployed runtime or live credentials, and do not add custom runtime overrides or compatibility layers.
+For profile-local packaged plugins on DSH `0.1.2-rc.1` with Node 24, validate on the NUC through its installed official `dsh` CLI and real Loader. Keep `DSH_HOME` and every generated profile test-owned and disposable; the installed CLI and preset package are read-only inputs. Never use live profiles, presets, credentials, overrides, or services, and do not add custom runtime overrides or compatibility layers.
+
+## Managed DSH presets
+
+The supported preset workflow is explicit: run `web dsh sync` before installing
+or activating `@guionai/dsh-web`, then run `web dsh doctor` and require a zero
+exit status. Sync compares `standard`, `ptc`, `cordis`, and `minimal` with the
+official and compatible trees; modified same-id content requires interactive
+confirmation or `--yes`. It must not mutate shipped presets, unrelated user
+presets, credentials, or sessions. Tests use fixture source trees and
+disposable `DSH_HOME` directories. End-to-end validation runs from the existing
+NUC checkout, built on the NUC, using its installed official DSH CLI and a
+disposable `DSH_HOME`. Do not transfer or validate a Web CLI packed on macOS.
+Record the paths and results in the implementation report.

CONTEXT.md

@@ -71,3 +71,42 @@ The `/api/v1/web` versioned path namespace for the HTTP Service's research
 operations when exposed through FlickNote Gateway. It identifies Guion Web as
 the owning service without changing its operation contracts.
 _Avoid_: Bare `/v1` API, generic web route
+
+**DSH Research Surface**:
+The Guion-owned model-facing DSH tool suite: `web_search`, `web_fetch`,
+`web_links`, `web_docs`, and `web_source_search`, plus `web_weather`,
+`web_sports`, `web_finance`, and `web_time` while Kepos Bridge is selected.
+It is registered globally by `@guionai/dsh-web`; native and PTC presentation
+modes consume the same registrations.
+_Avoid_: Official Web suite, scoped Web row
+
+**Compatible DSH Preset**:
+A DSH preset that omits its entire scoped `tool-web` row and therefore inherits
+the global DSH Research Surface from Guion. The `web dsh sync` command creates
+four generated compatible copies with the same ids as the official shipped
+`standard`, `ptc`, `cordis`, and `minimal` presets. The DSH bundle hides the
+shipped root while retaining the user root, so these copies become active and
+ordinary user presets such as Yuki remain visible.
+_Avoid_: Unmanaged copied preset, partially compatible preset
+
+**Official Shipped DSH Preset**:
+A preset installed by `@deepseek-ai/dsh-agent-presets` beside the DSH runtime.
+It is deployment-owned, may include the scoped official `tool-web` row, and is
+never edited by Guion. The bundle sets `includeShippedRoot: false` because DSH
+shipped entries win same-id duplicates.
+_Avoid_: Managed preset, user preset
+
+**Guion-Compatible DSH Preset**:
+A full snapshot under `${DSH_HOME:-$HOME/.dsh}/.agent-presets` generated by
+`web dsh sync` from the installed official rc.1 package. Sync recognizes it by
+comparing its complete contents with the expected transformed official tree;
+no ownership marker is stored. A different same-id directory requires explicit
+interactive confirmation or `--yes`. `web dsh doctor` verifies that all four
+snapshots are current, complete, and free of scoped `tool-web` rows.
+_Avoid_: Hand-edited output, shipped preset
+
+**Ordinary DSH User Preset**:
+A user-created directory in the DSH user preset root. It remains visible when
+the bundle hides the shipped root. A same-id preset is overwritten only after
+interactive confirmation or an explicit `web dsh sync --yes`.
+_Avoid_: Generated compatible preset, shipped preset

README.md

@@ -8,6 +8,11 @@ HTTP service, Pi extension, and DeepSeek Harness (DSH) integration: HTTP
 HTML-to-Markdown extraction and explicit browser rendering for client-rendered
 pages on supported hosts.
 
+> **DSH setup note:** Run `web dsh sync` before installing the DSH bundle and
+> `web dsh doctor` afterward. The workflow creates compatible copies of the
+> familiar stock preset ids and hides their official shipped duplicates while
+> preserving ordinary user presets.
+
 ## Install and configure
 
 Node.js 20 or later is required. `@guionai/web` exposes its `web` executable,
@@ -202,21 +207,45 @@ the presence of its key alone.
 
 ## DSH
 
-Install the DSH bundle in the existing Web profile:
+The bundle uses the familiar stock preset ids, but its compatible copies are
+owned by Guion in the DSH user preset root. Synchronize those copies before
+installing or activating the profile bundle:
 
 ```bash
+web dsh sync
 dsh plugin --profile web add @guionai/dsh-web
+web dsh doctor
 ```
 
-The included profile patch routes stock PTC web search through the selected Exa,
-Brave, DeepSeek, or Kepos Bridge provider. Its settings UI stores provider selection and
-the complete non-secret Kepos Bridge route (default
-`http://codex-bridge.localhost:17480/codex/web-search`) and manages namespaced write-only
-credentials, including a write-only DeepSeek API key. DeepSeek uses the same
-provider picker/key workflow and exposes no DeepSeek endpoint field. Selecting Kepos Bridge additionally exposes `web_weather`,
-`web_sports`, `web_finance`, and `web_time`; these tools are removed when another
-provider is selected. Fetch, link discovery, documentation, and Sourcegraph tools
-also run in-process. The host DSH packages and React are peers supplied by DSH.
+`web dsh sync` reads the installed official
+`@deepseek-ai/dsh-agent-presets@0.1.2-rc.1` package and creates compatible
+`standard`, `ptc`, `cordis`, and `minimal` copies. It removes only
+the top-level official `tool-web` row from the first three; Minimal is copied
+unchanged because it already omits that row. The command is idempotent and
+compares existing same-id directories with both the official and compatible
+trees. Exact matches are refreshed automatically. Modified same-id presets
+require interactive confirmation; use `web dsh sync --yes` for an intentional
+non-interactive overwrite. Run sync again after upgrading the supported DSH
+runtime. The read-only doctor command reports missing, stale, and conflicting
+copies and exits nonzero when the roster is not ready.
+
+The bundle's preset roster sets `includeShippedRoot: false`,
+`includeUserRoot: true`, and `default: standard`. This hides all official
+shipped duplicates while preserving Yuki and every other ordinary user
+preset. Existing sessions, credentials, and deployed profiles are not
+migrated automatically; activate or deploy the bundle separately after a
+successful sync and doctor run.
+
+The profile patch disables the official DSH Web registry, search/fetch providers,
+and `tool-web`, then registers Guion's complete DSH Research Surface directly.
+Its settings UI stores provider selection and the complete non-secret Kepos
+Bridge route (default `http://codex-bridge.localhost:17480/codex/web-search`)
+and manages namespaced write-only credentials, including a write-only DeepSeek
+API key. DeepSeek uses the same provider picker/key workflow and exposes no
+DeepSeek endpoint field. Selecting Kepos Bridge additionally exposes
+`web_weather`, `web_sports`, `web_finance`, and `web_time`; these tools are
+removed when another provider is selected. The host DSH target is
+`0.1.2-rc.1`; its packages and React are peers supplied by DSH.
 `web_fetch` uses HTTP rendering by default and can explicitly use
 `render: "browser"` with an integer `waitMs` on a host that supplies the
 optional executable.
@@ -227,6 +256,15 @@ other adapters: input mode is `auto|full|tree` (default `auto`), and omitted or
 `web_links` uses the same explicit rendering contract and lists HTTP(S) anchors
 from the original page DOM.
 
+Guion owns `web_search`, `web_fetch`, `web_links`, `web_docs`, and
+`web_source_search` in both native and PTC presentation modes. `web_search`
+accepts one to four trimmed queries, runs them concurrently, deterministically
+merges partial successes, and reports total failure clearly. `web_fetch`
+accepts `mode: "auto" | "full" | "tree"`, optional `section_id` with omitted
+or `auto` mode, `render: "http" | "browser"`, and browser `waitMs` from 0
+through 30,000. `web_links` has the same rendering and wait contract. The
+complete schemas are inherited by every compatible stock-equivalent preset.
+
 ## Page-rendering modes
 
 `web fetch` has two renderers. `http` (the default) uses Node `fetch`, `linkedom`,

docs/adr/0004-dsh-research-surface-owner.md

@@ -0,0 +1,56 @@
+# Make Guion the single owner of the DSH Research Surface
+
+## Status
+
+Accepted
+
+## Context
+
+Guion's DSH integration previously selected a Guion provider through the
+official DSH Web registry while the official `tool-web` plugin supplied the
+model-facing `web_search` and `web_fetch` surface. A scoped official row in a
+preset could therefore change the effective tools between native and PTC
+modes, and the profile carried duplicate provider and Web-suite ownership.
+
+## Decision
+
+This decision targets DeepSeek Harness `0.1.2-rc.1`.
+
+`@guionai/dsh-web` directly registers the complete DSH Research Surface:
+`web_search`, `web_fetch`, `web_links`, `web_docs`, and `web_source_search`,
+with the Kepos-only `web_weather`, `web_sports`, `web_finance`, and `web_time`
+registrations enabled only while Kepos Bridge is selected. Search reads the
+live Guion provider and namespaced credential for every execution. The plugin
+does not register with or depend on the official DSH Web provider registry.
+
+The profile patch disables `dsh-web`, `web-search-deepseek`, `web-fetch-http`,
+and `tool-web`, then mounts only the Guion host plugin with its credential,
+settings, and tools services. The bundle also patches the official
+`agent-presets` row with `includeShippedRoot: false`, `includeUserRoot: true`,
+and `default: standard`. DSH prepends shipped presets and lets them win
+same-id duplicates, so the shipped root must be hidden for compatible copies
+to take effect.
+
+`web dsh sync` reads the installed official
+`@deepseek-ai/dsh-agent-presets@0.1.2-rc.1` tree and writes full snapshots of
+`standard`, `ptc`, `cordis`, and `minimal` under the user preset root. It
+removes only the expected top-level official `tool-web` row from the first
+three. Sync compares existing directories with the official and compatible
+trees, refreshes exact matches automatically, and requires interactive
+confirmation or `--yes` before replacing modified same-id content. It never
+edits the shipped package. `web dsh doctor` performs the corresponding
+read-only checks.
+
+## Consequences
+
+Provider selection and credentials remain one live Guion settings surface, and
+native and PTC calls receive the same registered tools. Official shipped
+presets remain deployment-owned and untouched; their same-id compatible copies
+are the supported path because the bundle hides the shipped root while
+retaining Yuki and other ordinary user presets. Existing sessions, credentials,
+and deployed profiles are not migrated automatically. Runtime upgrades require
+an explicit sync, and deployment remains a separate operator action.
+
+The root and package READMEs, `CONTEXT.md`, and `AGENTS.md` are the only project
+documents that describe this operator and agent workflow; no other project
+documentation exposes a DSH preset contract that needs updating.