better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/pi/usage.md

@@ -0,0 +1,315 @@
+<!--
+source: https://pi.dev/docs/latest/usage
+fetched: 2026-09-06
+-->
+
+# Using Pi
+
+This page collects day-to-day usage details that do not fit on the quickstart page.
+
+## Interactive Mode
+
+![Interactive Mode](/docs/latest/images/interactive-mode.png)
+
+The interface has four main areas:
+
+- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and extensions
+- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
+- **Editor** - where you type; border color indicates the current thinking level
+- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model. Totals include assistant responses, usage reported by tools, and summary generation.
+
+The editor can be replaced temporarily by built-in UI such as `/settings` or by custom extension UI.
+
+### Editor Features
+
+| Feature | How |
+| --- | --- |
+| File reference | Type `@` to fuzzy-search project files |
+| Path completion | Press Tab to complete paths |
+| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
+| Copy response | Ctrl+X copies the selected message in `/tree`; otherwise it copies the last assistant message, or the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled |
+| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
+| Shell command | `!command` runs and sends output to the model |
+| Hidden shell command | `!!command` runs without sending output to the model |
+| External editor | Ctrl+G opens `externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere |
+
+See [Keybindings](/docs/latest/keybindings) for all shortcuts and customization.
+
+## Slash Commands
+
+Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
+
+| Command | Description |
+| --- | --- |
+| `/login`, `/logout` | Manage OAuth or API-key credentials |
+| [`/llama`](/docs/latest/llama-cpp) | Download, load, and unload llama.cpp router models |
+| `/model` | Switch models; Ctrl+S in the picker saves the startup default |
+| `/thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
+| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
+| `/settings` | Theme, message delivery, transport, and other preferences |
+| `/resume` | Pick from previous sessions |
+| `/new` | Start a new session |
+| `/name <name>` | Set session display name |
+| `/session` | Show session file, ID, messages, tokens, and cost |
+| `/tree` | Jump to any point in the session and continue from there |
+| `/trust` | Save project trust decision for future sessions |
+| `/fork` | Create a new session from a previous user message |
+| `/clone` | Duplicate the current active branch into a new session |
+| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
+| `/copy` | Copy last assistant message to clipboard |
+| `/export [file]` | Export session to HTML or JSONL |
+| `/import <file>` | Import and resume a session from a JSONL file |
+| `/share` | Upload as private GitHub gist with shareable HTML link |
+| `/reload` | Reload keybindings, extensions, skills, prompts, themes, and context files |
+| `/hotkeys` | Show all keyboard shortcuts |
+| `/changelog` | Display version history |
+| `/quit` | Quit pi |
+
+## Message Queue
+
+You can submit messages while the agent is still working:
+
+- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
+- **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work.
+- **Escape** aborts and restores queued messages to the editor.
+- **Alt+Up** retrieves queued messages back to the editor.
+
+On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](/docs/latest/terminal-setup) if you want pi to receive the shortcut.
+
+Configure delivery in [Settings](/docs/latest/settings) with `steeringMode` and `followUpMode`.
+
+## Sessions
+
+Sessions are saved automatically to `~/.pi/agent/sessions/`, organized by working directory.
+
+```
+pi -c                  # Continue most recent session
+pi -r                  # Browse and select a session
+pi --no-session        # Ephemeral mode; do not save
+pi --name "my task"    # Set session display name at startup
+pi --session <path|id> # Use a specific session file or session ID
+pi --fork <path|id>    # Fork a session into a new session file
+```
+
+Useful session commands:
+
+- `/session` shows the current session file and ID.
+- `/tree` navigates the in-file session tree and can summarize abandoned branches.
+- `/fork` creates a new session from an earlier user message.
+- `/clone` duplicates the current active branch into a new session file.
+- `/compact` summarizes older messages to free context.
+
+See [Sessions](/docs/latest/sessions) and [Compaction](/docs/latest/compaction) for details.
+
+## Context Files
+
+Pi loads `AGENTS.md` or `CLAUDE.md` at startup from:
+
+- `~/.pi/agent/AGENTS.md` for global instructions
+- parent directories, walking up from the current working directory
+- the current directory
+
+If a directory contains `AGENTS.override.md`, Pi loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory. Context files from other directories still layer normally.
+
+Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
+
+### System Prompt Files
+
+Replace the default system prompt with:
+
+- `.pi/SYSTEM.md` for a project
+- `~/.pi/agent/SYSTEM.md` globally
+
+Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
+
+### Project Trust
+
+On interactive startup, pi asks before trusting a project folder that contains project-local settings, resources, or project `.agents/skills` and has no saved decision for the folder or a parent folder in `~/.pi/agent/trust.json`. Trusting a project allows pi to load `.pi/settings.json` and `.pi` resources, install missing project packages, and execute project extensions.
+
+Before the trust decision, pi loads only context files, user/global extensions, and CLI `-e` extensions so they can handle the `project_trust` event. Project-local extensions, project package-managed extensions, and project settings are loaded only after the project is trusted. This split also applies when switching to a session from a different cwd whose trust has not been resolved in the current process.
+
+Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore those project resources, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
+
+If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.pi/agent/settings.json`, or change it with `/settings`.
+
+`pi config` and package commands use the same project trust flow, except `pi update` never prompts. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them.
+
+Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.pi/agent/trust.json` only; the current session is not reloaded, so restart pi for changes to take effect.
+
+## Exporting and Sharing Sessions
+
+Use `/export [file]` to write a session to HTML.
+
+Use `/share` to upload a private GitHub gist with a shareable HTML link.
+
+If you use pi for open source work and want to publish sessions for model, prompt, tool, and evaluation research, see [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). It publishes sessions to Hugging Face datasets.
+
+## CLI Reference
+
+```
+pi [options] [--] [@files...] [messages...]
+```
+
+### Package Commands
+
+```
+pi install <source> [-l]     # Install package, -l for project-local
+pi remove <source> [-l]      # Remove package
+pi uninstall <source> [-l]   # Alias for remove
+pi update [source|self|pi]   # Update pi only, or one package source
+pi update --all              # Update pi and packages; reconcile pinned git refs
+pi update --extensions       # Update packages only; reconcile pinned git refs
+pi update --models           # Refresh model catalogs only
+pi update --self             # Update pi only
+pi update --extension <src>  # Update one package
+pi list                      # List installed packages
+pi config                    # Enable/disable package resources
+```
+
+These commands manage pi packages and `pi update` can update the pi CLI installation. To uninstall pi itself, see [Quickstart](/docs/latest/quickstart#uninstall). `pi config` and project package commands accept `--approve`/`--no-approve` to trust or ignore project-local settings for one command. `pi update` never prompts for project trust.
+
+See [Pi Packages](/docs/latest/packages) for package sources and security notes.
+
+### Modes
+
+| Flag | Description |
+| --- | --- |
+| default | Interactive mode |
+| `-p`, `--print` | Print response and exit |
+| `--mode json` | Output all events as JSON lines; see [JSON mode](/docs/latest/json) |
+| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](/docs/latest/rpc) |
+| `--export <in> [out]` | Export a session to HTML |
+
+In print mode, pi also reads piped stdin and merges it into the initial prompt:
+
+```
+cat README.md | pi -p "Summarize this text"
+```
+
+### Model Options
+
+| Option | Description |
+| --- | --- |
+| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
+| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
+| `--api-key <key>` | API key, overriding environment variables |
+| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
+| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
+| `--list-models [search]` | List available models |
+
+### Session Options
+
+| Option | Description |
+| --- | --- |
+| `-c`, `--continue` | Continue the most recent session |
+| `-r`, `--resume` | Browse and select a session |
+| `--session <path|id>` | Use a specific session file or partial UUID |
+| `--fork <path|id>` | Fork a session file or partial UUID into a new session |
+| `--session-dir <dir>` | Custom session storage directory |
+| `--no-session` | Ephemeral mode; do not save |
+| `--name <name>`, `-n <name>` | Set session display name at startup |
+
+### Tool Options
+
+| Option | Description |
+| --- | --- |
+| `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools |
+| `--exclude-tools <list>`, `-xt <list>` | Disable specific built-in, extension, and custom tools |
+| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
+| `--no-tools`, `-nt` | Disable all tools |
+
+Built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`.
+
+### Resource Options
+
+| Option | Description |
+| --- | --- |
+| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
+| `--no-extensions` | Disable extension discovery |
+| `--skill <path>` | Load a skill; repeatable |
+| `--no-skills` | Disable skill discovery |
+| `--prompt-template <path>` | Load a prompt template; repeatable |
+| `--no-prompt-templates` | Disable prompt template discovery |
+| `--theme <path>` | Load a theme; repeatable |
+| `--no-themes` | Disable theme discovery |
+| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
+
+Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
+
+```
+pi --no-extensions -e ./my-extension.ts
+```
+
+### Other Options
+
+| Option | Description |
+| --- | --- |
+| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
+| `--append-system-prompt <text>` | Append to system prompt |
+| `--tui-mode <mode>` | TUI mode: `regular` (default) or experimental `fullscreen` |
+| `--use-theme <name[/name]>` | Set the initial interactive theme for this run without changing settings |
+| `--verbose` | Force verbose startup |
+| `-a`, `--approve` | Trust project-local files for this run |
+| `-na`, `--no-approve` | Ignore project-local files for this run |
+| `--` | Stop option parsing; remaining arguments are prompts or `@file` inputs |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show version |
+
+In `fullscreen` mode, the transcript scrolls inside the terminal viewport while queued messages, working status, extension widgets, editor, and footer remain fixed at the bottom. Mouse/trackpad input scrolls the region under the pointer; keyboard viewport actions always remain available. Inline images work in terminals that support the Kitty graphics protocol, including Kitty and Ghostty. In iTerm2 they render as text placeholders because its inline-image protocol cannot delete or crop placements during application-owned scrolling. In `regular` mode, pi uses the main screen and terminal-owned scrollback, and iTerm2 inline images continue to render normally. See [Terminal setup](/docs/latest/terminal-setup) for terminal-specific settings and workarounds.
+
+Set **TUI mode** in `/settings` to switch between `regular` and `fullscreen` immediately and choose the default for future sessions. **Fullscreen exit output** controls whether exiting fullscreen prints the final transcript or restores the previous screen and prints only the session resume hint.
+
+### File Arguments
+
+Prefix files with `@` to include them in the message:
+
+```
+pi @prompt.md "Answer this"
+pi -p @screenshot.png "What's in this image?"
+pi @code.ts @test.ts "Review these files"
+```
+
+### Examples
+
+```
+# Interactive with initial prompt
+pi "List all .ts files in src/"
+
+# Non-interactive
+pi -p "Summarize this codebase"
+
+# Prompt beginning with a dash
+pi -p -- "- Summarize these points"
+
+# Non-interactive with piped stdin
+cat README.md | pi -p "Summarize this text"
+
+# Named one-shot session
+pi --name "release audit" -p "Audit this repository"
+
+# Different model
+pi --provider openai --model gpt-4o "Help me refactor"
+
+# Model with provider prefix
+pi --model openai/gpt-4o "Help me refactor"
+
+# Model with thinking level shorthand
+pi --model sonnet:high "Solve this complex problem"
+
+# Limit model cycling
+pi --models "claude-*,gpt-4o"
+
+# Read-only mode
+pi --tools read,grep,find,ls -p "Review the code"
+
+# Disable one extension or built-in tool while keeping the rest available
+pi --exclude-tools ask_question
+```
+
+## Design Principles
+
+Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
+
+It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
+
+For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/pi/windows.md

@@ -0,0 +1,44 @@
+<!--
+source: https://pi.dev/docs/latest/windows
+fetched: 2026-09-06
+-->
+
+# Windows Setup
+
+Pi uses Git Bash by default on Windows. Checked locations (in order):
+
+1. Custom path from `~/.pi/agent/settings.json`
+2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
+3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
+
+For most users, [Git for Windows](https://git-scm.com/download/win) is sufficient.
+
+## PowerShell Tool
+
+The optional `powershell` tool runs commands through `pwsh.exe` when available, otherwise Windows PowerShell. It starts PowerShell with `-NoProfile -NonInteractive -ExecutionPolicy Bypass`. Administrator-enforced execution policies can still take precedence.
+
+Use `defaultTools` to replace the model-facing `bash` tool:
+
+```
+{
+  "defaultTools": ["read", "powershell", "edit", "write"]
+}
+```
+
+Or enable both while comparing behavior:
+
+```
+{
+  "defaultTools": ["read", "bash", "powershell", "edit", "write"]
+}
+```
+
+The `!` and `!!` editor commands still use Bash.
+
+## Custom Bash Path
+
+```
+{
+  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
+}
+```

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: dsh-dev-skill
+description: "Reference knowledge base distilled from the official DeepSeek Harness (dsh) developer documentation. Use when developing, extending, or debugging dsh plugins, Cordis services/events, LLM adapters, tools, sandbox/approval policy, web UI slots, session/persistence internals, or the Typert API gateway."
+---
+
+# DeepSeek Harness (dsh) — Official Docs, Distilled
+
+**Source**: official `deepseek-ai/deepseek-harness` master `docs/` (123 English files, fetched 2026-09-06 into `../src/docs/`) | **Chapters**: 22 | **Generated**: 2026-09-06 | **Depth**: reference (decision-ready lookup)
+
+## How to Use This Skill
+
+- **Without arguments** — load the core mental models below before touching dsh code
+- **With a topic** — ask about `compaction`, `slots`, `sandbox`, `fibers`; I read the matching chapter file first
+- **With a chapter** — ask for `ch15` to load that chapter only
+- **Browse** — ask "what chapters do you have?" for the full index
+
+Chapters are on-demand: only the one you load counts against context.
+
+---
+
+## Core Mental Models
+
+**1. Everything is a Cordis plugin; layers compose the app.**
+A running dsh is a plugin tree composed at boot from ordered layers — bundles (listed order) → profile patch → home patch → `--patch` argv — with no privileged core. A patch row targets a plugin id and **replaces its whole config value** (no deep merge): restate every key or lose fields. Ordering between plugins comes from `inject` dependencies, never YAML position. Prefer mounting a plugin or patching a row over forking core, because registrations are reversible effects.
+
+**2. The session log is the single source of truth; history is derived.**
+Every model-visible fact is an append-only `SessionEvent` (`{type, seq, time, data}`). Message history is folded from it (`deriveMessages()`), never stored. Only three surface types produce transcript messages: `user/message`, `assistant/message`, `tool/result` — everything else is audit/state. "Model-visible means logged" is a runtime invariant. State-carrying events carry **whole values, not deltas**. When you need derived per-session state, register a `ProjectionDefinition` — the registry drives, backfolds, and checkpoints it for you.
+
+**3. Capabilities are three-role seams.**
+A swappable capability = abstract Service Definition (`ctx.fs`, `ctx.llm`, `ctx.subagents`) + Provider + thin provider-neutral Consumer tools. Filesystem/subprocess/sandbox form one "execution world" — swap them together. Build a seam only when ≥2 implementations are plausible. Remote controllers project seams onto the wire and own redaction/refusal. Never depend on `ctx.agentLoop`; extension packages use `dsh-agent` events/services.
+
+**4. Tool calls cross a fixed policy pipeline.**
+`tools/pre-execute` (allow/deny/ask decision) → approval (fail-closed: absent asker = deny) → monotonic guards (deny-or-abstain, can never force-allow) → execute → `tools/post-execute` (transform) → `finalizeContent` → snapshotted result (throws become `isError`). Sandbox mode and approval policy are two independent, per-call-resolved knobs. No usable sandbox backend ⇒ `SANDBOX_UNAVAILABLE`, never silent passthrough; escalation is one-shot, strictly wider.
+
+**5. Packages share instances via peer dependencies.**
+The module graph is a peer-dependency graph of shared service instances: an edge means "consume the host's instance" — bundling your own copy breaks identity. Use `ctx.get(name)` for undeclared optional services; `ctx.<name>` throws through foreign fibers. Service visibility is ancestor/isolate only; `provide` throws on duplicates within a scope — sibling shadowing does not exist.
+
+**6. Events have contracts; waterfalls have discipline.**
+Dispatch mode (emit / serial / parallel / bail / waterfall) is part of each event's public contract — call the matching method. In waterfalls, observers must call `next()`; omitting it is a deliberate veto. Policy that must not be reordered belongs in monotonic guards, not pre-execute listeners (which other listeners can reshape).
+
+**7. LLM adapters are thin and provider-neutral at the wire.**
+`LlmAdapter.stream()` emits the closed `StreamChunk` union; the shared `BlockAssembler` reassembles blocks (never per-adapter). One adapter call = one attempt; retries live at agent level (`ResolvedRetryPolicy`). Usage arrives at provider end-of-stream. Credentials are `CredentialRef`s resolved per operation (rotation without restart). Can't honor a `GenerateOptions` field ⇒ throw `LlmError('UNSUPPORTED_OPTION')`.
+
+**8. The web surface is a dumb carrier plus typed slots.**
+`ctx.webServer` owns no TLS/auth/Origin policy — trust is supplied at composition (or a second isolated server for webhooks). The browser app boots from `WebBootGraph` (`window.__DSH_BOOT__`). The only sanctioned UI extension is `ctx.slots.inject` with a fresh list id; single/keyed cells are replacement points. Settings writes are CAS (`SettingsPathOp` + expectedRevision, `redactSecrets` on wire) — never `replace()` from a redacted view. Remote (Typert) methods are strictly unary; streamed responses use Connection Fetch routes; client calls return non-throwing `RemoteResult<T>`.
+
+---
+
+## Chapter Index
+
+| # | Title | Key contents |
+|---|---|---|
+| [ch01](chapters/ch01-user-guide.md) | User Guide | providers, credentials, compat blocks, MCP memory, proxy, Python SDK, schedules |
+| [ch02](chapters/ch02-plugin-basics.md) | Plugin Dev Basics | plugin anatomy, Config schema, defineTool, bundles/profiles, layer order, publishing |
+| [ch03](chapters/ch03-plugin-framework-practice.md) | Framework & Practice | fibers, events, service isolation, capability split, LlmAdapter, dynamic Cordis |
+| [ch04](chapters/ch04-cordis-fundamentals.md) | Cordis Fundamentals | plugin shapes, inject, PENDING, dispatch modes, waterfall veto, HMR, `!!js` |
+| [ch05](chapters/ch05-cordis-api.md) | Cordis API | Context scoping (extend/isolate/intercept), fiber API, service store symbols |
+| [ch06](chapters/ch06-architecture.md) | Architecture & Lifecycle | boot layers, profiles, turn/step model, session generations, rescope |
+| [ch07](chapters/ch07-capability-seams.md) | Capability Seams | seam taxonomy, execution world, event-gate companions, selection table |
+| [ch08](chapters/ch08-internals-pipelines.md) | Internals & Pipelines | module graph, event producer–consumer matrix, tool pipeline, defensive patterns |
+| [ch09](chapters/ch09-api-gateway.md) | API Gateway | Typert `@Remote`, `/api` routes, trust fence, DeepSeek wire extensions |
+| [ch10](chapters/ch10-config-catalog.md) | Config Catalog | `config:` blocks, `Requires:` lines, package classes, runtime-only seams |
+| [ch11](chapters/ch11-tool-catalog.md) | Tool Catalog | boot-and-read registry, capability seams, `run_code` transport, aliases |
+| [ch12](chapters/ch12-persistence-catalog.md) | Persistence Catalog | `SessionEventMap`, surface vs log-only, compaction shadow price, migrations |
+| [ch13](chapters/ch13-subsystems-core-session.md) | Subsystems: Core & Session | core spine, event log, inbox, system-prompt assembly, invariants |
+| [ch14](chapters/ch14-subsystems-agent-loop.md) | Subsystems: Agent Loop | subagents, teams, workflows, goals, plan mode, compaction, spill |
+| [ch15](chapters/ch15-subsystems-tool-execution.md) | Subsystems: Tool Execution | ToolRuntime, shell/fs/subprocess, sandbox backends, approval, presets |
+| [ch16](chapters/ch16-subsystems-session-data.md) | Subsystems: Session Data | projections, session-query, storage domains, attachments, jobs |
+| [ch17](chapters/ch17-subsystems-llm-streaming.md) | Subsystems: LLM Streaming | StreamChunk, BlockAssembler, token meter, typert, credentials, client-modules |
+| [ch18](chapters/ch18-subsystems-web-ui.md) | Subsystems: Web & UI | webServer, slots, settings, commands, skills, terminals, webhooks, schedule |
+| [ch19](chapters/ch19-cookbook.md) | Extension Cookbook | recipes: packages, vendoring, tools, settings cards, adapters, PR stacks |
+| [ch20](chapters/ch20-development-testing.md) | Dev & Testing | build faces, test tiers, coverage gates, doc budgets, type-equiv fences |
+| [ch21](chapters/ch21-postmortems.md) | Postmortems | export-default trap, `!!js` scope, GUI feedback loop, Landlock classification |
+| [ch22](chapters/ch22-i18n.md) | i18n & Translation | zh pairing contract, terminology, protected tokens, translation pipeline |
+
+## Topic Index
+
+- **adapters (LLM)** → ch03, ch17, ch19
+- **agent lifecycle / turn model** → ch06, ch13
+- **agent-team** → ch14
+- **approval / escalation** → ch07, ch15
+- **architecture / boot** → ch06, ch08
+- **attachments** → ch16
+- **background jobs** → ch16, ch19
+- **build / DSH_BUILD_FACE** → ch09, ch20
+- **bundles / profiles / layers** → ch02, ch06
+- **client modules / WebBootGraph** → ch17, ch18
+- **compaction** → ch12, ch14
+- **config (cordis.yml, catalog)** → ch02, ch10
+- **cookbook recipes** → ch19
+- **credentials** → ch01, ch17
+- **Cordis (framework, API)** → ch04, ch05
+- **defensive patterns** → ch08
+- **defineTool / tool authoring** → ch02, ch11, ch19
+- **dispatch modes / waterfalls** → ch03, ch04, ch08
+- **dynamic Cordis** → ch03, ch13
+- **events (Cordis vs session)** → ch03, ch12
+- **fibers / registry** → ch04, ch05
+- **filesystem / observation policy** → ch11, ch15
+- **goals** → ch14
+- **HMR** → ch03, ch04
+- **hooks (lefthook)** → ch20
+- **inbox / steering** → ch13
+- **invariants** → ch13
+- **i18n** → ch22
+- **isolate / intercept** → ch05
+- **jobs** → ch16
+- **LlmError / retries** → ch03, ch17
+- **MCP** → ch01
+- **module graph** → ch08
+- **persistence / session log** → ch12, ch16
+- **plan mode** → ch14
+- **postmortems** → ch21
+- **projections** → ch16
+- **providers (user config)** → ch01
+- **Python SDK** → ch01
+- **Remote / Typert gateway** → ch09, ch19
+- **sandbox (modes, backends)** → ch10, ch15
+- **schedules** → ch01, ch18
+- **session-query / title / telemetry** → ch16
+- **settings cards / CAS** → ch18, ch19
+- **skills subsystem** → ch18
+- **slots / UI injection** → ch18
+- **spill** → ch14
+- **StreamChunk / streaming** → ch17
+- **subagents** → ch14
+- **system prompt** → ch13
+- **testing tiers / coverage** → ch20
+- **tools registry / pipeline** → ch08, ch11, ch15
+- **typert (typing)** → ch17
+- **vendoring / packages** → ch19
+- **web server / client / trust** → ch18
+- **webhooks** → ch18
+- **workflows** → ch14
+- **workspace** → ch16
+
+## Supporting Files
+
+- [glossary.md](glossary.md) — ~55 key terms with exact definitions
+- [patterns.md](patterns.md) — 17 techniques: when / how / trade-offs
+- [cheatsheet.md](cheatsheet.md) — seam-selection table, hard rules, defaults, smells
+
+---
+
+## Scope & Limits
+
+Distilled exclusively from the **official** `deepseek-ai/deepseek-harness` master docs (English) fetched 2026-09-06; the raw source is preserved at `../src/docs/` (241 files incl. zh pairs) with URL mapping in `../src/site-pages-map.txt` for verbatim lookups. No local research, forks, or third-party analysis was folded in. Generated catalogs (config/tool/module-graph) are summarized, not reproduced — consult the source files for exhaustive per-entry detail. Docs describe the harness at the fetched master revision; verify against your deployed version when behavior matters.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch01-user-guide.md

@@ -0,0 +1,123 @@
+# Chapter 1: User Guide — Providers, MCP Memory, Proxy, SDK, Schedules
+
+## Core Idea
+Every user-facing surface — the Models page, MCP overlays, proxy env vars, the Python SDK, Schedule and GitHub-review overlays — reads or writes the same file-backed composition (`$DSH_HOME/settings.yaml` + Cordis patch layers); model and provider changes take effect on the next request with no server restart.
+
+## Frameworks Introduced
+- **Models page (`Settings → Models`)**: minimal provider form — API key, display name, base URL, API protocol, per-model id/name/context-window/max-output-tokens. Everything else lives in `settings.yaml`.
+  - When to use: DeepSeek, a built-in provider (`anthropic`, `openai`, `moonshotai`/Kimi, `zai`/GLM), or a custom gateway. OAuth providers (Codex) unsupported.
+  - How: enter key → save. Keys are write-only (page receives a redacted descriptor); the secret lands in `$DSH_HOME/.credentials.yaml`, settings keep only a credential reference.
+- **Custom provider form**: lowercase permanent Provider ID + base URL + one API protocol (`openai-completions` | `openai-responses` | `anthropic-messages`) + credential + ≥1 model. One protocol per provider; a dual-protocol gateway needs two providers.
+- **`@deepseek-ai/dsh-mcp-client` row**: generic MCP connector; discovered tools surface as `mcp__<serverName>__<tool>`. Default-off reference configs: Memorix `1.3.0`, MCP Reference Memory `2026.7.4`, Engram `v1.20.0` (all stdio).
+  - When to use: third-party memory or any MCP server.
+  - How: `dsh web --patch <overlay>.cordis.yml`; persist by merging the `insert` row into `$DSH_HOME/profiles/<name>/cordis.patch.yml` (one profile) or `$DSH_HOME/cordis.patch.yml` (all profiles). Never overwrite an existing patch file.
+- **Python SDK (`deepseek-harness-sdk`)**: pip wheel bundling a native runtime + the `dsh` CLI (no system Node); a context manager lazily starts `dsh --profile sdk-minimal` and reuses it until exit.
+- **Schedule overlay**: session-local reminders via `schedule_create` / `schedule_list` / `schedule_delete` (positive `after_seconds`, absolute `at`, or `every_seconds` ≥ 300).
+- **GitHub review overlay**: signed webhook endpoint creating read-only review Sessions on PR `ready_for_review`.
+
+## Key Concepts
+- **Provider ID**: permanent lowercase id — requests, saved sessions, model defaults, and credential references use it; rename = add new + delete old.
+- **`compat` route block**: request-shape corrections pi-ai cannot infer from the URL (`supportsDeveloperRole`, `maxTokensField`, `thinkingFormat`); full switch list = `PiAiCompatProfile` in the generated `dsh-llm-pi-ai` config reference.
+- **`reasoningEfforts`**: per-model map of menu level → wire spelling of `reasoning_effort`; only `off` may be empty (param absence); `compat.thinkingFormat: deepseek` makes `off` send `thinking: {type: disabled}` and other levels `thinking: {type: enabled}` beside the effort.
+- **`input` / `defaultInput` / `modelOverrides`**: modality claims (`text`, `image`) at model level, route fallback (default `[text]`, never strips a catalog model's images), and per-model overrides on built-in providers; unknown modality refused everywhere.
+- **`--patch` overlay**: one-file config layer passed at launch; argv order matters (layer order in Ch 2).
+- **stdio env scrubbing**: the MCP bridge removes credential-named ambient vars and all `DSH_*` vars before spawning a child; per-row `config.env` is the sanctioned secret channel.
+- **Proxy env vars**: `HTTPS_PROXY`/`HTTP_PROXY` read at launch; `NO_PROXY` matches host + subdomains (leading `.`/`*.` equivalent, `*` bypasses all, CIDR never works); loopback always direct; SOCKS reported and skipped; `ALL_PROXY` fallback; `NODE_EXTRA_CA_CERTS` for TLS-intercepting proxies.
+- **`sdk-minimal` profile**: `dsh-sdk-app` JSON-RPC row over an empty root (no `dsh-base`); pins `danger-full-access`; uncompressed JSONL sessions; no compaction, telemetry, or web tools.
+- **Session-local reminder**: owned by the session log; delivered as a queued follow-up turn when the root Agent is fully idle; reopening a cold session restores overdue reminders; forks don't inherit.
+
+## Mental Models
+- Think of the Models page as a deliberate thin editor over `settings.yaml` — same document, re-read per request by the adapters.
+- Treat MCP as a ferry, not a supervisor: DSH parses the overlay, launches/monitors stdio children, re-syncs tools on reconnect — it never installs servers, migrates data, or manages models/embeddings.
+- Proxy reachability is three unrelated mechanisms (OS settings, env vars, TUN mode); CLI tools see only env vars — export them or use TUN.
+- Schedule delivery is "the session talks to itself later": no browser/OS/email channel, just a follow-up turn in the original conversation.
+
+## Anti-patterns
+- **Renaming a Provider ID in place**: every reference (sessions, defaults, credentials) uses it; add a new provider and delete the old one.
+- **Proxy vars in a project `.env`**: DSH refuses to start — a repository must not decide where traffic goes; use a shell profile or `$DSH_HOME/.env` (exported vars win).
+- **CIDR entries in `NO_PROXY`**: no effect; use hostnames/domain suffixes.
+- **Trusting built-in provider discovery against a gateway**: the installed catalog always answers; fetch through a custom provider to see what the gateway really serves.
+- **Reading webhook `202` as "session created"**: it means only signature + JSON accepted and rule calls scheduled in memory.
+- **Expecting notifications from Schedule**: no external notification exists; delivery is only the queued follow-up.
+
+## Code Examples
+Custom provider with the two most common compat fixes:
+```yaml
+llm-pi-ai:
+  providers:
+    my-gateway:
+      apiKeyEnv: GATEWAY_API_KEY
+      api: openai-completions
+      baseURL: https://gateway.example/v1
+      compat:
+        supportsDeveloperRole: false   # gateway rejects role: "developer"
+        maxTokensField: max_tokens     # gateway refuses max_completion_tokens
+      models:
+        - id: vision-preview
+          input: [text, image]
+        - id: my-reasoner
+          reasoningEfforts: { off: , high: high, max: max }
+```
+Generic MCP row (stdio):
+```yaml
+- insert:
+    - id: memory-my-server
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: my-memory
+        transport: stdio        # remote: streamable-http + url + headers
+        command: my-memory-mcp
+        args: []
+        env: {}
+        cwd: !!js process.cwd()
+```
+SDK entry point:
+```python
+from deepseek_harness import DeepSeekHarness
+with DeepSeekHarness(provider="deepseek-official", model="deepseek-v4-flash",
+                     max_tokens=49_152, cwd=str(ws), dsh_home=str(home),
+                     profile="sdk-minimal") as harness:
+    result = harness.run("Inspect the repository.", session_id="example-001")
+print(result.final_response)
+```
+Proxy:
+```sh
+export HTTPS_PROXY=http://user:pass@proxy.example:8080  # creds in URL, never printed back
+export NO_PROXY=internal.example.com,.corp.example.com
+export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem    # export before process start
+```
+
+## Reference Tables
+| Surface | Activation | Persistence |
+|---|---|---|
+| Custom provider / compat | Models page or `settings.yaml` | `settings.yaml` (re-read per request) |
+| MCP memory server | `--patch examples/mcp-memory/<x>.cordis.yml` | merge row into `cordis.patch.yml` |
+| Schedule | `--patch examples/schedule/cordis.yml` | overlay only (per-process opt-in) |
+| GitHub review | `--patch` + `DSH_GITHUB_WEBHOOK_SECRET` | rows appended to profile patch; `github-ready-review-rule.mjs` beside it |
+| SDK plugins | `dsh plugin --profile sdk-minimal add file:/path` | `$DSH_HOME/profiles/sdk-minimal/cordis.patch.yml` |
+
+| Symptom | Fix |
+|---|---|
+| `MISSING_CREDENTIAL` | store key via Models page or set the referenced env var |
+| `UNKNOWN_MODEL` | select a configured model or add it to the custom provider |
+| model fetch → 401 | bad key; discovery calls `GET /models` — enter models by hand if absent |
+| only reasoning models fail | `compat.supportsDeveloperRole: false` |
+| `off` doesn't stop DeepSeek thinking | `compat.thinkingFormat: deepseek` on model or route |
+| image refused before sending | add `input: [text, image]`; after removing a wrong claim, start a new session (log replays the attachment) |
+
+Schedule `at`: strict RFC 3339 with `Z` or numeric offset, or `{date, time, time_zone}` with explicit `UTC`/IANA Area/Location; DST gaps rejected, overlaps pick the first instant, records keep UTC only. Overdue `every` records: latest occurrence only, same-idle batches combined (one-shots first), no backlog; cron/calendar unsupported.
+
+## Key Takeaways
+1. Model config is two-tier: the form covers what a route needs to exist; reasoning, modality, compat, headers, timeouts, retries live under `llm-pi-ai.providers.<id>` in `settings.yaml` (DeepSeek's own route: `llm-deepseek.reasoningEffort`, e.g. `max`).
+2. Compat switches and modality lists state claims, not checks — they never probe the endpoint; an empty compat key is refused, not ignored.
+3. A crashed MCP child reconnects with backoff and tool re-sync; after the reconnect budget is exhausted, tools unregister until reload/restart. Initial discovery is async — wait for `mcp__...` tools before validating.
+4. Model-authored workflow/code-runtime workers never receive proxy settings; OTLP telemetry is always direct (`DSH_TELEMETRY_MODE=DISABLED` to disable); `web_fetch` to literal private addresses is refused.
+5. The SDK never silently reads `~/.dsh` — pass an explicit `dsh_home`; `web` is a separate CLI application and cannot serve a Python SDK client.
+6. Webhook `run()` is trusted JS: policy-service gates and repo→path maps are ordinary code returning `null` to skip; the secret authenticates inbound data only, granting no outbound GitHub access.
+
+## Connects To
+- **Ch 2**: `--patch` overlays here are the same rows bundles ship; layer order defined there.
+- **Ch 10**: generated config catalog owns every `llm-pi-ai` field incl. `PiAiCompatProfile`.
+- **Ch 17**: compat/reasoning switches map onto the LLM streaming adapter contract.
+- **Ch 7**: MCP rows and provider config are capability seams in the composition.
+- **Ch 18**: Models page, reminder catalog, and sidebar alarms are Web UI surfaces.