super-dsh 0.3.0-a → 0.3.0-d

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch18-subsystems-web-ui.md

@@ -1,142 +0,0 @@
-# Chapter 18: Subsystems — Web Server, Client & UI Slots
-
-## Core Idea
-The Web surface is a layered pair: a dumb Host HTTP carrier (`ctx.webServer`) whose security comes entirely from the composition (Connection plugin: Host/Origin checks + browser-session auth on every `/api` route), and a browser-side Cordis application whose only sanctioned UI extension point is the typed Slots system (`ctx.slots.inject`/`register`) — never cross-plugin imports. Around this sit the interaction subsystems (settings, commands, user-questions, skills, feedback, webhook, schedule, terminals) that plugins consume via narrow registries.
-
-## Frameworks Introduced
-- **WebServer route registry**: named `exact`/`prefix` routes + one claimable fallback seat.
-  - When to use: serving plugin bundles, feature routes, webhook ingress on a second server.
-  - How: `ctx.webServer.register({kind, path, handler})` → disposer; duplicate `(kind, path)` throws. Match order: exact table → longest prefix → fallback. Fallback is one-owner (SPA dist server claims it).
-- **Index injection pipeline**: structured rows before raw HTML taps.
-  - When to use: putting anything into index.html (boot script, meta).
-  - How: answer `webserver/index-inject` emit with `IndexInjection[]` rows; `tapIndex(transform)` is the escape hatch, applied in registration order after structured rows.
-- **Browser boot (WebBootGraph)**: Host writes composed graph to `window.__DSH_BOOT__` + installs module-loader facade before parser-preloaded scripts.
-  - When to use: understanding plugin client-half load order.
-  - How: lazy CommonJS table; boot kernel prefetches `immediately` entries, mounts vendored Cordis Loader; Cordis service injection (not graph order) determines activation; final step is the sole `ctx.slots.renderSlot('root')`.
-- **Slots composition system**: typed React registry (`dsh-client-ui-slots`) + renderer (`dsh-client-ui-renderer`, only package using `useSyncExternalStore`/React contexts).
-  - When to use: any browser UI contribution from a plugin.
-  - How: declare via declaration-merge on `SlotMap` + `children` entry in the owning component; contribute via `ctx.slots.inject(key, callback)` → `ctx.slots.register({name, id, order}, Component)`.
-- **Settings namespaces**: one user document, per-plugin sections resolved as schema defaults → composition `base` → user layer.
-  - When to use: user-editable config distinct from `cordis.yml`.
-  - How: `ctx.settings.register(ns, schema, {base, applies, validate})` → `SettingsScope` (`get`/`watch`/`update`/`replace`).
-- **Layered provider registries** (skills): host + per-scope layers; nearest layer wins duplicate names outright; rank → provider order → local order within one layer.
-
-## Key Concepts
-- **Trusted hosts**: `dsh web` binds loopback by default and rejects `--host 0.0.0.0`; non-loopback exposure requires the composition to supply TLS/auth/Origin policy itself (carrier owns none).
-- **WebRouteKind**: `'exact' | 'prefix'`; paths absolute, no trailing slash; handlers own the full response lifecycle (may hold SSE open).
-- **Client models**: React-free mirrors of Host state (`ClientSessions → SessionManager → Session`, `ClientWorkspaceModel` → `ctx.workspaces`); UI packages never reproduce transport state in component stores.
-- **Cardinality axes**: `single` (one winner by priority) / `list` (id + order) / `keyed` (entryKey dispatch) / `chain` (first non-null `select(owner)` wins); scope: `root` / `session-maybe` / `session`.
-- **priority**: shadowing rank, lower renders first; reusing a shipped cell's id/key replaces its presentation — the sanctioned "override" mechanism (not import shadowing).
-- **SettingsDescriptor**: `{ns, schema, value, revision, base?, user?, applies, secrets?}`; `redactSecrets: true` mandatory on wire surfaces; writes use `expectedRevision` CAS and `SettingsPathOp` (`set`/`unset`) so redacted callers can't delete unseen secrets.
-- **TerminalSessionService**: exact-`Agent`-owned PTY sessions; one exclusive `TerminalSendOperation` per session; `TerminalWaitReason` (`stdin_read|inferred_idle|timeout|session_exit`) independent of session status.
-- **CommandResult**: `{kind:'success', text?, sourceEventSeq?}` or `{kind:'error', text}` — direct UI outcomes, not tool results; slash commands bypass the model entirely.
-- **SkillInvocationPolicy**: `modelInvocable`/`userInvocable` booleans from frontmatter keys `disable-model-invocation` and `user-invocable` (default true).
-- **Fire-and-forget webhook**: no queue, retry, dedup, or completion state; a `WebhookRule`'s `WebhookSessionRequest` creates an ordinary root Session whose first message is a user-role follow-up with `source.kind: "webhook"`.
-- **schedule/change**: version-1 Session event, the only durable Schedule authority; strict decoder rejects unknown versions/extra fields/reused ids.
-
-## Mental Models
-- Think of `ctx.webServer` as a dumb pipe: it knows no harness concepts; every feature route (including `/api`) is registered by another plugin. Security is a composition property, not a server property.
-- Use `ctx.slots.inject(key, cb)` when contributing to a slot you don't own; the callback re-runs for each owner declaration lifetime and is cleaned up when the owner collapses.
-- Think of settings layers as three-deep inheritance: schema defaults ⊂ composition `base` ⊂ user section; `replace({})` re-inherits everything (the reset path).
-- Treat a `single` or occupied keyed cell as a replacement point; use a fresh list `id` for additive extension.
-
-## Anti-patterns
-- **Runtime-importing another feature plugin's values**: hard boundary; only `import type` for declarations is allowed — cross-package UI goes through slots.
-- **Passing `ctx`, transport objects, or model services to slot components**: components get only derived props, hooks, store actions, inject faces; services stay in the `apply` closure.
-- **`replace()` from a redacted descriptor view**: silently deletes every secret the wire never returned; use path ops (`mutate`).
-- **Registering a second fallback handler or duplicate `(kind, path)` route**: throws — composition-level contract.
-- **Expecting webhook/schedule delivery guarantees**: webhook is at-most "repeated delivery may create repeated Sessions"; schedule is at-least-once (crash interval can duplicate reminder content); neither has receipts or completion state.
-- **`every` schedule catch-up enumeration**: only the latest due occurrence dispatches; missed intervals are never replayed.
-
-## Code Examples
-```ts
-// Slot injection (plugin client half)
-export const inject = ['slots']
-export function apply(ctx: Context): void {
-  ctx.slots.inject('conversation.session.header.actions', () =>
-    ctx.slots.register({
-      name: 'conversation.session.header.actions',
-      id: 'review', order: 100,
-    }, HeaderAction))
-}
-// Component props derive, never copy:
-type HeaderActionProps = PropsRuntime<'conversation.session.header.actions'>
-```
-```ts
-// Settings registration
-const scope = ctx.settings.register('my-plugin', MySchema, {
-  base: { feature: true },          // composition layer
-  applies: 'live',                  // or 'restart' (UI hint)
-  validate: v => { if (!v.ok) throw new Error('cross-field') },
-})
-scope.watch((next, prev) => ...)    // after commit, deep-equal-gated
-```
-```ts
-// WebServer route
-ctx.webServer.register({ kind: 'prefix', path: '/plugins', handler })
-// Index injection: answer 'webserver/index-inject' emit; or escape hatch:
-ctx.webServer.tapIndex(html => html.replace('</head>', snippet + '</head>'))
-```
-```ts
-// Webhook rule
-ctx.webhookRuntime.register({
-  id: 'nightly', kind: 'github',
-  run: async (delivery, signal) => ({
-    workspacePath, title, text, agentPreset, permissionPreset, model?,
-  }), // null = no session
-})
-```
-
-## Reference Tables
-| Slot (key extension surfaces) | Cardinality | Scope |
-|---|---|---|
-| `sidebar.brand.mark` / `sidebar.brand.name` / `sidebar.footer.action` | — | root |
-| `sidebar.workspaces` (+ `.directoryFlow`) | — | root |
-| `settings.general.item` | list | root |
-| `settings.models.provider-card` / `settings.models.footer` | list | root |
-| `settings.plugins.tab` (+ `settings.plugin.item`) | list | root |
-| `conversation.session.header.actions` | list | session-maybe |
-| `conversation.chat.node` (+ `assistant-actions`, `commandview`, `turnTail`) | — | session |
-| `tool.call.toolview` (+ `tool.call.images`, `tool.view.cordis`) | — | session |
-| `conversation.composer.bar` (+ `input.attachments/plan/model`) | list | session |
-| `conversation.input.left` / `.right` / `.overlay` / `.dock` | list | session |
-| `shell.overlay` | — | root |
-
-Live tree query: `cordis_inspect what:"client"`; catalog regenerated by `pnpm run gen-client-catalog`.
-
-| Skill discovery rank | Source | Root |
-|---|---|---|
-| 100 | project-dsh | `<projectRoot>/.dsh/skills` |
-| 200 | project-agents | `<projectRoot>/.agents/skills` |
-| 300 | custom | `Config.customSkillDirs` |
-| 400 | user-dsh | `<dshHome>/skills` |
-| 500 | user-agents | `<agentsHome>/skills` |
-| 600 | bundled | `Config.bundledSkillDir` |
-
-Project root = nearest `.git` ancestor, else cwd. Formats: `<name>/SKILL.md` bundle or flat `<name>.md`; no recursive `**/SKILL.md`.
-
-| WebServer config | Default | Notes |
-|---|---|---|
-| `host` | `127.0.0.1` | only `0.0.0.0` alternative; `dsh web` rejects it |
-| `port` | — | `0` = OS-assigned (read back via service `port`) |
-| `compression` | `'none'` | shipped Web bundle: gzip level 1 |
-| `compressionThresholdBytes` | 1024 | unknown-length streams always eligible |
-
-## Key Takeaways
-1. Add plugin UI exclusively through `ctx.slots.inject()` into shipped slot keys; check the generated client catalog (`cordis_inspect what:"client"`) for cardinality/scope/occupants before choosing an id.
-2. The HTTP carrier is deliberately dumb — any non-loopback deployment must supply auth/Origin/TLS at the composition layer; webhook ingress should mount a second isolated WebServer (GitHub review guide pattern).
-3. Never send a settings `replace` rebuilt from a redacted descriptor; wire surfaces always pass `redactSecrets: true` and edits travel as `SettingsPathOp`s with `expectedRevision`.
-4. Slot components receive no `ctx`; four injection channels are ranked: owner props (render-time values) → registration `inject` (entry-private callbacks/observables) → slot-level `inject` (owner-controlled capability, e.g. `useTurnData`) → declared store (shared mutable view state).
-5. Slash commands (`ctx.commands`) execute without creating model messages; lifecycle is logged as `command/run`/`command/done` direct appends with `sourceEventSeq` linking to richer domain events.
-6. Skills: nearest scope layer wins outright; body-only edits change later `skill` tool calls without emitting catalog messages (catalog carries only name + description, default 500 chars).
-7. Schedule is session-local: no external notification, no cold-session scheduling; dispatch waits for full Agent idleness and uses `followup()`, never `steer()`.
-
-## Connects To
-- **Ch 09**: the `/api` bridge, Connection generations, and Remote dispatch this server carries.
-- **Ch 07**: capability-seam pattern shared by web access, skills, and user-questions providers.
-- **Ch 02/03**: plugin packaging — client half registration and bundle serving via `/plugins/??<id>/client.js`.
-- **Ch 10**: config keys cited here (`customSkillDirs`, `bundledSkillDir`, `collectCacheMaxEntries`, `catalogDescriptionMaxLength`).
-- **Ch 13**: Session persistence barrier that schedule management and feedback sidecar writes wait on.
-- **Ch 16**: storage domains (`message_feedback`) and the persistence catalog indexing `schedule/change`.
-- **Ch 11**: tool contracts for `skill`, `schedule_*`, and `web_search`/`web_fetch` consumers.
-- **Ch 20**: `pnpm run gen-client-catalog` / `verify-cordis-catalog` in doc-sync.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch19-cookbook.md

@@ -1,149 +0,0 @@
-# Chapter 19: Extension Cookbook
-
-## Core Idea
-Every dsh product feature is a listener on a documented Cordis extension point — the microkernel claim, made checkable. The cookbook gives the exact files, code shapes, and verify commands for each extension recipe; no row modifies the agent loop.
-
-## Frameworks Introduced
-- **defineTool (typed tool contract)**: `ctx.tools.register(defineTool({ name, description, parameters, output: { schema, render }, execute(args, exec) }))`. Raw JSON-Schema `ToolDefinition`s are also accepted (that is how MCP tools arrive); `defineTool` is the typed first-party helper.
-  - When to use: any first-party model-facing tool.
-  - How: registration is `ctx.effect`-based (dispose unregisters; HMR-safe); schemas auto-flow into the system-prompt assembly.
-- **Tool execution policy waterfall**: `tools/pre-execute` (extensible allow/deny/ask) → `ctx.tools.guard()` (monotonic final deny) → `tools/execute` (wrap dispatch: deadline/retry/metrics) → `tools/post-execute` (transform result) → `tools/result` (observe immutable outcome).
-- **LlmAdapter**: `class MyAdapter extends LlmAdapter { async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> }`, registered via `ctx.llm.registerAdapter(['my-provider'], new MyAdapter())`. One adapter per route; duplicates throw; multi-route registration is all-or-nothing.
-- **TypertRemoteService / @Remote**: remote-API owner extends `TypertRemoteService`, marks methods `@Remote('list')`; failures are one `RemoteError` class + a `RemoteErrorDetailsMap` code table.
-- **dsh.client packaging**: a plugin's browser half ships via `dsh.client` in package.json + `exports["./client"]`, served by the client module system — appears on page with no web-app rebuild.
-
-## Key Concepts
-- **Waterfall**: reorderable middleware chain on a Cordis interception point; `next()` continues, a returned value short-circuits.
-- **Canonical value**: the single lossless-JSON value `execute` returns; snapshotted, validated, frozen, passed to `output.render(args, value)`.
-- **exec identity**: `callId`, `name`, `arguments`, `agent`, `token`, `signal`, optional `parent` are immutable through dispatch; only an around-dispatch wrapper may replace `exec.signal` (to impose a deadline), never remove it.
-- **presentationMeta**: `output.presentationMeta(args, value)` derives replayable JSON; core persists it on `tool/result` for cards.
-- **Render-intent union**: `presentCall`/`presentResult` return a `card`-tagged view (`generic`/`terminal`/`diff`/`read`/`search`/`web`); pure functions of args (+result) — run on replay, so NO I/O/state/clock.
-- **RemoteResult<T>**: client-remote call result; branch `if (!result.ok)`, discriminate by `code` (narrows `details`), never `instanceof`.
-- **Vendoring**: pinned source under `vendor/<dir>/` (not an npm dep); publishable release member (no `private`, `publishConfig.access: public`).
-- **Role suffix**: `Controller`/`Store`/`Directory`/`Presenter`/`Registry`/`Runtime`/`Resolver`/`Binder`/`Engine`/`Policy`/`Executor`/`Gateway`/`Provider`/`Backend`/`Handle`/`Config`/`Service` — name the stable current responsibility, not the first implementation.
-- **settingsScope**: browser-side `ctx.settingsScope.bind({ namespace })` fences each write with the revision it read; `set(field,value)`/`unset(field)`.
-- **stackEntry**: GitHub's authoritative stacked-PR object — `PullRequest.stack` + `stackEntry.position` prove recognition; base branches establish order.
-
-## Mental Models
-- **Think of a permission gate as the reorderable policy layer**: hook plugins return a typed decision from `tools/pre-execute`; sandbox, permission, and plan-mode plugins reuse the same point. A "native hook" is an ordinary Cordis plugin — no external protocol.
-- **Use `tools/result` for observation, `tools/post-execute` only to transform**: observing the immutable final outcome vs. replacing value/content/attaching context.
-- **Think of the namespace as the join key**: the Host serves a settings namespace; the Plugins tab keys its card on that namespace; both halves register the same string → auto-paired, no repo change.
-- **Think of a Remote call as non-throwing**: it returns `RemoteResult<T>`, never rejects; an assembly mistake should crash, not a defensive catch.
-
-## Anti-patterns
-- **Parsing prose for ids**: PTC mode / background branches must never recover a `jobId` from human prose — return `{ kind: 'background', jobId }` as the canonical handle.
-- **UI formatting in the model result**: fenced `console` blocks, diffs, relativized paths belong in `presentationMeta` + card presenters, not `output.render`/canonical value.
-- **Ad-hoc key files in adapters**: secrets are cordis-native (schemastery Config with env fallback, `!!js process.env.MY_KEY`); never read key files in code.
-- **Silently dropping unsupported options**: throw `LlmError(..., 'UNSUPPORTED_OPTION')` rather than ignore a `GenerateOptions` field the provider can't honor.
-- **`--force` on a rewritten stack push**: must be lease-protected, abort rather than overwrite a concurrently advanced remote head.
-- **Copying the `api/remotes` split**: new packages never copy its repo-specific Host/Client phase split; an ordinary package joins exactly one aggregate.
-- **Deep-comparing Remote errors**: assert `code` + details via `remoteErrorOf(...).toMatchObject`, never `toEqual` or `instanceof`.
-
-## Code Examples
-
-```ts
-// Tool — minimal shape (typed args, canonical value, signal)
-export const name = 'my-tool'; export const inject = ['tools']
-export function apply(ctx: Context) {
-  ctx.tools.register(defineTool({
-    name: 'read_file', description: 'Read a file from disk.',
-    parameters: { path: { type: 'string', required: true, description: 'Absolute path' } },
-    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
-    async execute(args, exec) {
-      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
-    },
-  }))
-}
-```
-
-```ts
-// Hook (permission gate)
-export function apply(ctx: Context) {
-  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
-    if (!(await isAllowed(exec))) return { kind: 'deny', reason: 'Denied by policy.' }
-    return next()
-  })
-}
-```
-
-```ts
-// Remote API owner + failure table
-export class NotesController extends TypertRemoteService {
-  constructor(ctx: Context) { super(ctx, 'notesController', { namespace: 'notes' }) }
-  @Remote('list')
-  async remoteExportList(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> { return this.list(agent, signal) }
-}
-declare module '@deepseek-ai/dsh-typert-protocol' {
-  interface RemoteErrorDetailsMap {
-    'note/not-found': { readonly noteId: string }
-  }
-}
-throw new RemoteError('note/not-found', `no note "${noteId}"`, { noteId })
-```
-
-```ts
-// Client remote consume
-export const inject = ['remote', 'remote.notes']
-const result = await ctx.remote.notes.list()
-if (!result.ok) { if (result.error.code === 'note/not-found') return []; throw result.error }
-```
-
-```jsonc
-// Browser-half packaging
-{
-  "exports": {
-    ".": { "types": "./lib/types/index.d.ts", "default": "./lib/index.js" },
-    "./client": { "types": "./lib/types/client/index.d.ts", "default": "./lib/client.js" }
-  },
-  "dsh": { "client": { "platform": "web", "inject": ["@deepseek-ai/dsh-client-ui-settings-plugins"] } }
-}
-```
-
-## Reference Tables
-
-### Recipe skeleton (goal → files → key shape → verify)
-
-| Recipe | Files touched | Key shape | Verify |
-|---|---|---|---|
-| **New workspace package** | `packages/<group>/<pkg>/{package.json,tsconfig.json,src/index.ts,README.md}` + `tsconfig.{host,client}.json` references | `private:true`, cordis in peer+dev, schemastery in `dependencies`, `files` = `lib/index.js` + `lib/types/**/*.d.ts`; `.ts` import specifiers | `pnpm install` → `pnpm run doc-sync` → `pnpm run constraints && pnpm run typecheck && pnpm run lint` → `pnpm run build && pnpm run hygiene` |
-| **Vendored package** | `vendor/<dir>/{package.json,tsconfig.json,src/,README.md}` + `tsconfig.base.json` paths + `tsconfig.host.json` ref (before `packages/*`) + `vendor/README.md` manifest row | rescope name, keep exports/type, `publishConfig.access:public` (no `private`), `outDir: lib/types`, strictness relaxations | `pnpm install` → `pnpm run typecheck` → `pnpm run build && pnpm run constraints`; stage manifest alongside source (`scripts/check-vendor-manifest.sh`) |
-| **Add a tool** | one `src/index.ts` plugin; card methods `presentCall`/`presentResult` | `defineTool` + `execute(args, exec)` returning one canonical value | repository testing policy + owning package test docs |
-| **Settings card** | Host `src/` + browser `src/client/` in one package, `dsh.client` export | Host `settingsCtx.settings.installSection(ctx, NS, Config, config, {validate, setSource, onChange})`; browser `ctx.slots.inject('settings.plugin.item', …)` | no repo change; appears when `cordis.yml` mounts it |
-| **LLM adapter** | `packages/llm/llm-<name>/` | `extends LlmAdapter` + `stream()` generator + `registerAdapter` | repository testing policy (real-provider checks) |
-| **Remote API** | Host controller (`packages/api/`) + client consumer | `TypertRemoteService` + `@Remote` + `RemoteErrorDetailsMap`; client `inject ['remote','remote.<ns>']` | `pnpm run build:lib` (after signature/code-table/namespace change) → `pnpm run typecheck` → `npx vitest run <owner> <client>` |
-
-### LLM adapter protocol obligations
-| Obligation | Rule |
-|---|---|
-| Ordering | Emit `usage` BEFORE `finish`; emit NOTHING after `finish` |
-| Tool args | RAW JSON strings end-to-end; stream as `argumentsDelta`; re-stringify at `block-end` |
-| Block index | Allocate in first-seen stream order; reuse for every delta |
-| Errors | THROW (`LlmError` + stable code) OR `finish {kind:'error'|'aborted'}` — pick per class, document |
-| Unsupported | `LlmError(..., 'UNSUPPORTED_OPTION')` for unhonoable `GenerateOptions` |
-| Replay | `finish.replayState` = minimal lossless-JSON projection; validate when rebuilding history |
-
-### Remote failure code placement
-| Situation | Declare where |
-|---|---|
-| One producer | In the producing package, next to the throw |
-| Several producers | Lowest domain package both depend on |
-| Carrier codes `gateway/bad-request|cancelled|internal` | In protocol/gateway — use, never copy |
-| Never crosses wire | Out of the code table; caller's own type |
-
-## Key Takeaways
-1. Every extension is a listener on a documented point; `ctx.effect`-based registration means vendored HMR "just works".
-2. A tool's `execute` returns one canonical value; keep human prose in `output.render` and replayable UI state in `presentationMeta` + card presenters — they are pure (replay-safe).
-3. Gate long work through `ctx.jobs.start({ kind, label, owner: exec.agent, run })`; a successful background branch returns `{ kind: 'background', jobId }`, never prose.
-4. Register a new package by copying `packages/core/tools` and joining exactly one aggregate (`tsconfig.host.json` OR `tsconfig.client.json`); `pnpm run constraints` enforces the package.json invariants.
-5. Vendor upstream Cordis packages as pinned `vendor/` source, not npm deps; stage the manifest alongside source or the pre-commit hook fails.
-6. Remote failures are one `RemoteError` + code table, consumed as `RemoteResult<T>`; discriminate by `code`, not `instanceof`.
-7. On a stacked-PR chain, fix the introducing PR then propagate up-stack (`gh stack rebase`/`gh stack push`), one worktree per PR, distinct commit per fix, never raw `--force`.
-
-## Connects To
-- **Ch 02**: `defineTool`/`ctx.tools.register` is the plugin-basics authoring path.
-- **Ch 05**: `ctx.on`/`ctx.effect`/waterfall semantics are the Cordis API these recipes build on.
-- **Ch 06**: the architecture doc owns the system + extension-point map that the feature→mechanism table summarizes.
-- **Ch 09**: decorator semantics, lookup resolution, and the `/api` route (Remote mechanism) live in the API Gateway reference.
-- **Ch 11**: `defineTool` soft-validation, `output.render`, and the card union feed the tool catalog.
-- **Ch 15**: `tools/pre-execute`/`execute`/`post-execute`/`result` and the background-job runtime are the tool-execution subsystem.
-- **Ch 20**: repository testing policy owns coverage/real-provider checks each recipe defers to.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch20-development-testing.md

@@ -1,87 +0,0 @@
-# Chapter 20: Development & Testing Workflow
-
-## Core Idea
-dsh development runs on a two-aggregate TypeScript build (Host/Client), a tiered test policy whose highest-value tier is the keyless real-entry-path smoke, and a doc-standard (AGENTS.md) that enforces "one home per fact" through mechanical gates.
-
-## Frameworks Introduced
-- **Two-aggregate tsconfig solution**: `tsconfig.json` (solution root) → `tsconfig.host.json` + `tsconfig.client.json` programs sharing `tsconfig.base.json` as a paths facade.
-  - When to use: any new package registration, build-script, or program-seeding work.
-  - How: register a package in exactly one aggregate; seed `ts.Program` scripts with the aggregate, never the root (flattening both collides the cordis `Context` declaration merges).
-- **Face-phased build (`DSH_BUILD_FACE`)**: `tsc -b tsconfig.host.json` → `tsdown --env.DSH_BUILD_FACE host` → `tsc -b tsconfig.client.json` → `tsdown --env.DSH_BUILD_FACE client` → `pnpm run build:web`.
-  - When to use: complete builds; `pnpm run build` wraps it and embeds version + 7-char commit + dirty marker, writing a build record that release packing and web tests validate.
-  - How: `pnpm run build`; Typert (Host reflection + Remote projection) runs only in the host tsdown pass.
-- **Testing tiers**: unit → coverage gate → real-API e2e → expected-output → session snapshot → web browser snapshot.
-- **Doc tier taxonomy**: root AGENTS.md / architecture / subsystems / Agent Notes / postmortems / cookbook / user / package README / generated references / skills — each fact has exactly one home.
-- **Type-equivalence fences**: ` ```ts type-equiv ` / ` ```ts public-api ` registered in `scripts/type-equiv.manifest.json`.
-  - When to use: pasting source declarations into docs.
-  - How: `{doc, symbol, source}` (+`"projection": "public-api"`); `pnpm run verify-type-equiv` (in doc-sync) fails on drift.
-
-## Key Concepts
-- **Host/Client aggregates**: one program per side because both declaration-merge cordis `Context` under the same keys; collision exists only inside a `ts.Program`, never in module resolution.
-- **Shared leaves**: `host/webserver`, `compaction/compaction`, `typert/registry` registered in both aggregates so each side type-checks the same source.
-- **Split packages**: six packages (e.g. `api/remotes`, `session-log-export`) carry separate Host/Client leaf tsconfigs; the workspace `constraints` gate auto-discovers them via presence of both leaf configs.
-- **Source plane**: vitest resolves workspace imports via `tsconfig.base.json` paths to `src`, never through package `exports` to built `lib/` (avoids duplicate module singletons).
-- **Coverage gate**: per-file 100% on `packages/*/*/src`; an uncovered line is usually dead code to delete, not a missing test.
-- **With-key policy**: "we are DeepSeek — do not ration real-API tests"; suites self-skip without keys so keyless CI stays green.
-- **Snapshot fixture naming**: `session[.vN].jsonl` parents, `session.<ordinal>[.vN].jsonl` children; v0 suffixless, versions lowercase `.vN`; `snapshot.yml` declares profile/composition/policy.
-- **TODO markers**: `FIXME` (release blocker) > `TODO` (soon) > `XXX` (someday).
-- **Lefthook hooks**: pre-commit (staged pairing records, Oxlint staged profile, THIRD_PARTY_NOTICES, whitespace, vendor manifest guard), pre-merge-commit, pre-push (`pnpm run typecheck`). Hooks deliberately do not run tests/builds — CI owns exhaustive coverage.
-
-## Mental Models
-- Think of the repo as two type worlds sharing one paths facade: resolution may cross faces freely, but programs may not.
-- Use a smoke test (boot shipped profile, one prompt, check the world) when you need to catch "green unit tests, broken product"; it needs no key when the operation doesn't call the model.
-- Treat snapshot refresh as fixture production, not correctness review: semantic assertions must exist independently of expected outputs.
-- Treat doc budgets as guardrails, not reduction targets: at/below target keep ≥5% headroom; above target freeze the ceiling until relocation/condensation.
-
-## Anti-patterns
-- **Hand-mounting plugins in tests** (`ctx.plugin({...})`): bypasses the Loader; cannot validate how the plugin actually loads.
-- **Verifying the agent's self-report**: assert by re-running the command or re-reading the file externally; keyword probes let a cheating agent pass.
-- **Adding `include`/`files` to `tsconfig.base.json`**: leaks into every extending package and narrows the match-all facade.
-- **Restating catalogs/JSDoc/status in prose**: hand-restated inventories rot; link or generate.
-- **Narrating change history in durable prose** ("previously", "now", PR numbers): document the live mechanism; put stories in commits/Agent Notes/postmortems.
-
-## Code Examples
-```sh
-pnpm install            # also installs worktree-local Lefthook + pairing merge driver
-pnpm run typecheck      # setup complete when this exits 0
-pnpm run build          # tsc host → tsdown host → tsc client → tsdown client → build:web
-pnpm run check:all      # opt-in comprehensive local gate set
-pnpm dsh --profile headless "summarize this workspace"   # needs DEEPSEEK_API_KEY
-```
-```ts
-// namespace plugin form — never add `export default apply`
-export const name = 'acp'
-export const inject = ['agents', 'sessions', 'sessionPersistence']
-export function apply(ctx: Context, config: AcpConfig): void { /* … */ }
-```
-
-## Reference Tables
-| Tier | Command | Key rule |
-|---|---|---|
-| Unit | `pnpm run test` | vitest, tests beside code; every registry gets an HMR-safety dispose test |
-| Coverage | `pnpm run test:coverage` | per-file 100% on `packages/*/*/src` |
-| Real-API e2e | `pnpm run test:e2e` | self-skips per missing key (`DEEPSEEK_API_KEY`, `EXA_API_KEY`, …) |
-| Expected output | `pnpm run test:expected` | keyless assembled CLI/process expectations |
-| Snapshot | `pnpm run test:snapshot[:record|:refresh]` | review every diff |
-| Web snapshot | `pnpm run test:web` | Linux PR gate; CI forces read-only replay |
-
-| Env var | Purpose |
-|---|---|
-| `DEEPSEEK_API_KEY` | real-API e2e + demos |
-| `DEEPSEEK_BASE_URL` | optional, defaults to public API |
-| `DSH_BUILD_FACE` | host/client phase selector for tsdown configs |
-| `DSH_SNAPSHOT=replay` | CI-forced read-only web snapshot mode |
-
-## Key Takeaways
-1. Register new packages in exactly one tsconfig aggregate; seed repo-wide programs from an aggregate, never the solution root.
-2. Preselect the smallest checks covering your changed surface; `pnpm run check:all` is opt-in, not an agent instruction.
-3. Tests resolve source, not builds: built artifacts are consumed only via explicit `lib`-mode subprocesses and built smokes; run profile subprocesses through the shared dual-mode launcher, never hand-written `--import tsx`.
-4. Every non-trivial model/protocol/UI change adds a keyless recorded-session scenario in the same PR; snapshot evidence is not replaced by package or mock-only tests.
-5. Docs: one home per fact, one physical line per paragraph, fenced `ts` must compile, pairs update together; classify tutorial vs reference before writing.
-6. When the doc-budget gate goes red: relocate → condense → only then raise the ceiling with a justified manifest diff.
-
-## Connects To
-- **Ch 06**: architecture.md's place in the doc tier taxonomy.
-- **Ch 13–18**: subsystems pages own the type definitions that type-equiv fences mirror.
-- **Ch 21**: postmortems are the failure lessons behind many testing rules codified here.
-- **Ch 22**: the bilingual pairing contract is part of doc-sync gates contributors run.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch21-postmortems.md

@@ -1,82 +0,0 @@
-# Chapter 21: Postmortems (Failure Lessons)
-
-## Core Idea
-dsh postmortems record process failures — why every safety net missed a shipped bug — and each one motivates durable guardrails; the lessons are reusable rules for plugin exports, config interpolation, agent acceptance loops, and process attribution.
-
-## Frameworks Introduced
-- **Postmortem format**: Executive summary (30-second paragraph) → Summary / Timeline / Root cause / Guardrails.
-  - When to use: a bug is subtle (non-obvious mechanism), systemic (gap in tests/tooling/conventions), and costly to rediscover — and it reached a real user, merged PR, or release.
-  - How: chronology records evidence, not teaching sequence; link the guardrails (tests, AGENTS.md rules) the postmortem motivated.
-- **Namespace-plugin/export invariant** (0001): cordis `Loader.unwrapExports` prefers `exports.default ?? exports`.
-- **`!!js` interpolation scope** (0002): JS expressions evaluate only in plugin `config`; entry metadata like `disabled` stays literal.
-- **Acceptance-target identity** (0003): an agent's verification must name one exact origin and observe the change there externally.
-- **Conjunction-of-evidence classification** (0004): `RunnerFailureRule` = allowed exit codes + per-line fatal signatures + exact informational exclusions.
-
-## Key Concepts
-- **Agent Note vs postmortem**: an Agent Note records a deliberate decision and rejected alternatives (forward-looking); a postmortem records a failure (backward-looking).
-- **`unwrapExports` trap**: a default export resolves to the bare function, discarding sibling `name`/`inject`/`Config`; the plugin fiber is built with empty `inject`.
-- **Ancestor-only fiber walk**: the `reflect.ts` `get` handler walks only ancestors; a sibling-branch service read via `ctx.<name>` through a foreign shadow throws at root. `ctx.get(name)` uses the topology-independent global isolate-keyed store.
-- **Top-level bypass**: from test code (`ctx.fiber.runtime === null`), property reads bypass the fiber walk entirely — masking shadow-path failures.
-- **Expression-object truthiness**: a parsed `!!js` value in `disabled` is a truthy object → always disabled; no load-time diagnostic because the YAML tag is valid.
-- **`window.__DSH_BOOT__`**: injected only by the full `dsh web` host; bare Vite HTTP 200 is transport readiness, not application readiness.
-- **Launcher contract (Landlock)**: exit 125 + fatal `landlock-run:` line = launcher failure; exact notice `landlock-run: partial enforcement (older Landlock ABI)` = informational before a normal child run.
-- **In-band stderr**: a confined child can deliberately reproduce a runner's fatal line and exit status; a shared prefix is not a protocol.
-
-## Mental Models
-- Use a keyless real-Loader e2e when the headline operation doesn't call the model — it belongs in CI, not behind a key gate.
-- Think of snapshot refresh as recording whatever the system now does; semantic impossibilities (e.g. `UNKNOWN_TOOL`) need assertions independent of expected outputs.
-- Think of every verification fact (source edit, build, HTTP 200, boot manifest, user's page) as separate; acceptance = the exact origin + external observation.
-- Use overlays (`fs.cordis.yml`) when you need conditional composition; runtime permission presets cannot mount/unmount plugin fibers.
-
-## Anti-patterns
-- **`export default apply` in a namespace plugin**: Loader unwraps to the bare function and drops `inject` → `cannot get property "x" without inject` at load time.
-- **`ctx.<optionalService>` for services not in `static inject`**: ancestor-only shadow walk throws; use `ctx.get(name)` (inactive backend reads as `undefined`).
-- **`disabled: !!js ...` on a Loader entry**: never evaluated; entry stays permanently disabled.
-- **Launching a replacement server to verify a change**: a second service proves only itself; the existing page may have already picked up rebuilt artifacts.
-- **Classifying failure by stderr substring + nonzero exit**: joins unrelated facts from different processes; ordinary child exits (ripgrep's 1 = no matches) get mislabeled `SANDBOX_UNAVAILABLE`.
-- **Trusting an elegant theory over the trace**: instrument the actual mechanism (fiber walk, real subprocess) before reasoning.
-
-## Code Examples
-```ts
-// 0001 fix — delete the stray line:
-// export default apply            // ← Loader unwraps .default, drops inject
-
-// 0001 fix #2 — optional service read:
-// this.ctx.sessionPersistence     // throws through foreign shadow
-this.ctx.get('sessionPersistence') // topology-independent lookup
-```
-```ts
-// unwrapExports (vendor/loader): prefers .default
-exports = exports.default ?? exports
-if (!exports.__esModule) return exports
-return exports.default ?? exports
-```
-```ts
-// RunnerFailureRule (0004 guardrail):
-{ allowedExitCodes?: number[],      // Landlock: [125]
-  fatalSignatures: string[],        // per-line, case-insensitive
-  informationalExclusions: string[] } // exact lines, e.g. the partial-enforcement notice
-```
-
-## Reference Tables
-| # | Incident | Root cause | Durable lesson |
-|---|---|---|---|
-| 0001 | ACP crashed on connect (`session/new`, `session/load`) | `export default apply` dropped `inject`; shadow-walk read of sibling service | Namespace exports and default export are mutually exclusive; optional services via `ctx.get()`; test the real Loader path |
-| 0002 | Filesystem snapshot tools always disabled | `!!js` only interpolates `config`, not `disabled`; truthy expression object; snapshot refresh accepted `UNKNOWN_TOOL` | Verify which fields are interpolated; snapshot ≠ correctness review; conditional composition via overlays |
-| 0003 | Web agent validated a replacement server, not the GUI | No model-visible identity for current GUI/URL/mode; bare Vite 200 treated as success | `DSH_WEB_URL` + `app:web-surface` prompt; reject standalone Vite before listen; acceptance names the exact origin |
-| 0004 | Landlock notice misclassified child failures as `SANDBOX_UNAVAILABLE` | one substring signature + any nonzero exit; bash search replaced structured errors with `SEARCH_FAILED` | Conjunction of independent evidence; exact informational exclusions; preserve structured seam failures |
-
-## Key Takeaways
-1. 100% line coverage proves lines ran, not that the feature works as shipped — hand-mounted tests bypass both the Loader and fiber topology.
-2. A no-key test of the real entry path (boot the profile through Loader, assert the first RPC) catches load-shape bugs unit tests structurally cannot.
-3. `TSX_TSCONFIG_PATH` in subprocess spawns makes source resolution cwd-independent — otherwise imports silently fall back to stale built `lib/`.
-4. Permission controls describe only the capabilities they govern; bash sandbox presets cannot retroactively confine in-process filesystem providers.
-5. A regression test must be able to fail for the reported mechanism: process timeout ≠ fail-fast; post-exit port availability ≠ never bound.
-6. Platform-dependent behavior (Landlock ABI) needs a deterministic fake at the native boundary plus one assembled product-path snapshot; a self-skipping real-kernel test cannot carry the regression.
-
-## Connects To
-- **Ch 04/05**: cordis fibers, shadows, `ctx.get` semantics behind 0001.
-- **Ch 10**: `!!js` interpolation scope in cordis config entries (0002).
-- **Ch 15**: tool execution and `UNKNOWN_TOOL` guardrail.
-- **Ch 18**: Web GUI runtime modes, HMR, `__DSH_BOOT__` (0003).
-- **Ch 20**: testing rules ("test the real entry path", "verify the world") codified from these incidents.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch22-i18n.md

@@ -1,86 +0,0 @@
-# Chapter 22: i18n & Translation
-
-## Core Idea
-Every in-scope dsh document is maintained as an equal-authority English/Simplified-Chinese pair of three sibling files (`foo.md`, `foo.zh.md`, `foo.i18n.yaml`), mechanically gated by blob-hash consistency records plus structural-signature checks, with terminology.md as the single source of truth for term rendering.
-
-## Frameworks Introduced
-- **Pairing contract**: both languages carry equal authority; a PR never lands one side without the other two files.
-  - When to use: any edit to an in-scope document.
-  - How: update the counterpart directly in one terminology-guided pass, then `pnpm run verify-translation-pairing --write <pair>` re-records both blob hashes; that yaml diff is the reviewable confirmation act.
-- **Consistency record (`foo.i18n.yaml`)**: full git blob hash (`git hash-object`) of each side at last confirmation — content comparison, computable within one PR; recovers exact last-confirmed text for minimal patch-style resync (never re-translate whole files).
-- **Structural signature**: heading depths/order, fenced code blocks (byte-identical incl. comments), table row/column counts, list kinds/starts/item counts, semantic link targets with exact query/fragment suffixes — must match 1:1 across the pair.
-- **Translation rules (RFC 2119 levels)**: MUST/MUST NOT gate-blocking, SHOULD needs stated deviation reason, MAY discretionary; register calibrated by style-samples gold pairs (sample wins over prose voice rules on conflict).
-- **Translation prompt pipeline**: `scripts/translation-prompt.ts` renders the committed template with only `{{source_lang}}`, `{{target_lang}}`, `{{terminology}}` placeholders; output is three XML sections (`<translation>` / `<review>` / `<final>`), pipeline takes `<final>`; 5 human-reviewed whole-document gold pairs injected as few-shot example conversations.
-
-## Key Concepts
-- **Language switcher**: Chinese file links back right after H1: `[English](foo.md) | 中文`; authored English files reciprocate; generated English sources omit it (stay byte-identical to generator output).
-- **Exclusions** (never paired): `cordis-api/inherited.md`, AGENTS.md/CLAUDE.md instruction files, `terminology.md` + `style-samples.md` (bilingual by construction), `translation-prompt.md` (machine-consumed verbatim), `.agents/notes/archived/` (frozen, sealed).
-- **Term classes**: 缩写类 (ACP, LLM, SSE — abbreviations in both languages); 英文类 (agent, seam, slot, fiber — keep English in Chinese prose); 双语类 (adapter→适配器, session→会话 — translate, with 不要译作 prohibitions).
-- **First-occurrence annotation**: write the 首次出现 value on first prose occurrence (e.g. `agent（智能体）`), bare form afterward; a term already glossed inside a compound needs no re-gloss.
-- **Pending terms**: unlisted terms without established major-OSS precedent (K8s/Vue/MDN/微软) stay English and go under 待定术语; no inline invention.
-- **Protected tokens**: inline code spans — commands, flags, paths, identifiers, API/event names, config keys, versions — verbatim, never translated; fenced code blocks byte-identical including comments.
-- **Chinese typography**: half-width space between Chinese and Latin/numerals; full-width punctuation `，。：；？！（）「」`; 顿号 for parallel lists; no full-width digits; 你 not 您; RFC 2119 → 必须/禁止/应当/可以 preserving emphasis strength.
-- **Merge driver**: `dsh-translation-pairing` composes records when both owner blobs merge cleanly; fails closed otherwise; `pnpm run resolve-translation-pairing-conflicts` for stopped merges.
-
-## Mental Models
-- Think of the gate as proof of confirmation, not soundness: green = hashes and structure match; whether the two sides truly say the same thing is the reviewer's half.
-- Use the lightweight path (translate directly, one pass, load terminology first) for routine agent work; the `dsh-translate-docs` skill workflow only on explicit user invocation.
-- Treat out-of-sync resync as patching: diff the edited side against its last-confirmed hash, apply the minimal counterpart patch — never re-translate the file.
-- Think of authority order in the prompt: source meaning/structure > terminology table > gold pairs > prompt guidance; gold pairs calibrate voice, they are not a translation memory.
-
-## Anti-patterns
-- **Editing one side of a pair without the other**: CI goes red; a scoped green (`verify-translation-pairing <pair>`) never substitutes for the corpus-wide run at PR level.
-- **Translating code identifiers or fence contents**: byte-identical requirement; ` ```ts ` fences also compile under doc-typecheck.
-- **Using a 不要译作 rendering** (e.g. 接缝 for seam, 智能体笔记 for Agent Note, 金丝雀测试 for canary): strictly forbidden.
-- **Conflating term pairs**: capability→能力 vs feature→功能; inference vs reasoning (gloss only when disambiguation needed); stale→陈旧 vs expired→过期.
-- **Copying the language switcher unchanged when translating**: flip it; if the source has none, don't invent a filename — the pipeline inserts the canonical switcher post-parse.
-
-## Code Examples
-```yaml
-# foo.i18n.yaml — consistency record (blob hashes)
-foo.md: 3f786850e387550fdab836ed7e6dc881de23001b
-foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b
-```
-```sh
-pnpm run verify-translation-pairing --list <pair>   # state: missing/out-of-sync/ok
-pnpm run verify-translation-pairing --write <pair>  # re-record after syncing
-pnpm run gen-translation-brief <pair>               # extended workflow only
-```
-```markdown
-<!-- Chinese file top: --> [English](foo.md) | 中文
-<!-- Authored English file top: --> English | [中文](foo.zh.md)
-```
-
-## Reference Tables
-| Key term | 中文 | Never render as |
-|---|---|---|
-| agent | agent (gloss 智能体 first use) | — |
-| seam | seam | 接缝 |
-| slot | slot | 坑位、孔位 |
-| postmortem | 事故复盘 | 事后分析、事故记录 |
-| Agent Note | Agent Note | 智能体注记/笔记 |
-| capability / feature | 能力 / 功能 | crossed: 能力↔功能 |
-| expected output | 预期输出 | 金标 |
-| source of truth | 真源 | 事实来源 |
-| counterpart | 对侧文件 | 对应物 |
-| canary test | canary 测试 | 金丝雀测试 |
-
-| Scope item | Rule |
-|---|---|
-| Docs in scope | root CONTRIBUTING/BRAND/SAFETY, non-vendor READMEs, `.agents/notes/**`, `docs/**`, `python/**` |
-| Pair granularity | three sibling files, same directory; no locale dirs |
-| Gate | part of `doc-sync`; run corpus-wide at PR level |
-| Generated sources | pair only when reviewed counterpart exists; English generator stays source of truth |
-
-## Key Takeaways
-1. A PR editing either side updates the counterpart and re-records the pair in the same change — the yaml hash diff is the reviewable act of confirming consistency.
-2. Load terminology.md before translating; every listed term follows its row, its 首次出现 annotation, and its 不要译作 prohibitions, in both directions.
-3. Structure mirrors one-to-one: headings, list shape, table dimensions, code fences, and link targets (with locale-swapped `.md`/`.zh.md` paths inside the corpus) must match.
-4. The prompt pipeline recognizes only three placeholders and whole-document translation; output framing escapes lines that look like wrapper tags with one extra backslash.
-5. Routine work never delegates translation to a subagent or runs a separate review pass — one direct terminology-guided pass, then the gate.
-6. Chinese register = institutional technical Chinese with explicit actors (系统/门禁/评审人) replacing vague passives; established engineering idiom (误报/漏检) over calques.
-
-## Connects To
-- **Ch 20**: doc-sync gates include pairing verification; Markdown rules apply to `.zh.md` unchanged.
-- **Ch 06/11/12**: generated references (architecture regions, tool/config/persistence catalogs) pair only with reviewed counterparts.
-- **Ch 21**: postmortem title terms (Executive summary→摘要, Summary→概述) come from the glossary.