super-dsh 0.3.0-c → 0.3.0-e

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/lsp.md

@@ -1,202 +0,0 @@
-# LSP navigation
-
-English | [中文](lsp.zh.md)
-
-The LSP seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) exposing semantic code navigation on one `ctx.lsp` service, split across packages: Service Definition ([dsh-lsp](../../packages/lsp/lsp), `ctx.lsp` + the provider registry), a generic Service Provider ([dsh-lsp-stdio](../../packages/lsp/lsp-stdio), a configured stdio language-server host), and Consumer ([dsh-tool-lsp](../../packages/lsp/tool-lsp), the `lsp` tool schema). LSP is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A provider swap does not change how the model asks for navigation.
-
-Source: [`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
-
-## Operations and coordinates
-
-The seam and model expose exactly four semantic queries; the union is closed, so adding one is a compile-enforced change across the seam, providers, and the tool. Positions and ranges are zero-based UTF-16, matching the protocol; the model-facing tool owns the one-based cursor convention and converts on the way in and out.
-
-```ts type-equiv
-/**
- * The four semantic queries the seam and model expose. A closed union: adding an operation is a
- * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
- * not operations here; they need different schemas.
- */
-type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover'
-```
-
-```ts type-equiv
-/** A zero-based UTF-16 cursor coordinate, matching the LSP wire convention. */
-interface LspPosition {
-  /** Zero-based line. */
-  readonly line: number
-  /** Zero-based UTF-16 code-unit offset within the line. */
-  readonly character: number
-}
-```
-
-```ts type-equiv
-/** A zero-based UTF-16 half-open range `[start, end)`. */
-interface LspRange {
-  readonly start: LspPosition
-  readonly end: LspPosition
-}
-```
-
-## Request
-
-Every field is required: `workspaceRoot` is caller-supplied, `languageId` comes from the provider's registration (not the request), and consumers own timeouts and result limits — so no field needs implementation defaulting and there is no `resolve()` step. The provider receives the caller's request plus the derived `languageId`, which only synchronizes the transient document and never participates in selection.
-
-```ts type-equiv
-/**
- * A caller's normalized query. Every field is required: `workspaceRoot` is caller-supplied,
- * `languageId` comes from the provider registration (not here), and consumers own timeouts and
- * result limits — so no field needs implementation defaulting and there is no `resolve()` step.
- */
-interface LspQueryRequest {
-  /** Which semantic query to run. */
-  readonly operation: LspOperation
-  /** The source file to query (relative to `workspaceRoot` or absolute; the provider canonicalizes). */
-  readonly filePath: string
-  /** The zero-based UTF-16 cursor position to query at. */
-  readonly position: LspPosition
-  /** The workspace root the provider resolves against and indexes; required, never defaulted. */
-  readonly workspaceRoot: string
-}
-```
-
-```ts type-equiv
-/**
- * A request as a provider receives it: the caller's {@link LspQueryRequest} plus the `languageId`
- * the seam derived from the provider's extension mapping. The language id only synchronizes the
- * transient document; it does not participate in selection.
- */
-interface LspProviderQuery extends LspQueryRequest {
-  /** The LSP language id for `filePath`, from this provider's extension mapping. */
-  readonly languageId: string
-}
-```
-
-## Result
-
-A CLOSED discriminated union: navigation operations normalize to `locations`, `hover` to content or `null`. Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled. `findReferences` always includes declarations — the provider enforces this internally, so callers get no flag. The `locations` variant carries `resolvedWorkspaceUri`, the provider's canonical workspace `file:` URI. A caller relativizing location URIs uses that coordinate rather than applying host-platform path rules to the possibly-symlinked request root.
-
-```ts type-equiv
-/** One resolved location: a document URI and the range within it. */
-interface LspLocation {
-  /** The target document URI (`file:` or otherwise), verbatim from the server. */
-  readonly uri: string
-  /** The range within the target document. */
-  readonly range: LspRange
-}
-```
-
-```ts type-equiv
-/** Normalized hover content, or `null` for no hover at the position. */
-interface LspHover {
-  /** The normalized hover text (markdown or plaintext, provider-joined). */
-  readonly contents: string
-  /** The range the hover applies to, when the server supplied one. */
-  readonly range?: LspRange
-}
-```
-
-```ts type-equiv
-/**
- * The closed result union. Navigation operations (`goToDefinition`, `findReferences`,
- * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
- * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
- *
- * The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
- * the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
- * request's possibly symlinked process path with host-platform rules; the execution platform may
- * differ from the caller's.
- */
-type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceUri: string }
-  | { readonly kind: 'hover'; readonly hover: LspHover | null }
-```
-
-## Provider and service
-
-A provider owns a stable branded `id` and an exclusive lowercase leading-dot extension map. `registerProvider` reserves the id and every extension atomically — an invalid or conflicting registration publishes nothing — and its disposer releases all reservations. Selection is per query and order-independent; no match throws `LspError` `LSP_UNAVAILABLE`. The seam exposes no protocol types, process/document controls, or generic JSON-RPC escape hatch.
-
-```ts type-equiv
-/**
- * A language-server backend registered on `ctx.lsp`. Each provider owns a stable {@link
- * LspProviderId} and an extension-to-language-id map (lowercase, leading-dot keys).
- * `findReferences` always includes declarations — the provider enforces this internally; callers
- * get no flag.
- */
-interface LspProvider {
-  /** Stable provider identity, reserved atomically with the extension mappings. */
-  readonly id: LspProviderId
-  /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */
-  readonly extensionToLanguage: Readonly<Record<string, string>>
-  /**
-   * Run one query. The seam has already selected this provider and derived `languageId`.
-   * @param request - the resolved provider query (caller request + derived language id).
-   * @param signal - optional cancellation; the provider stops its own work when it aborts.
-   * @returns the normalized, closed-union result.
-   */
-  query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult>
-}
-```
-
-```ts type-equiv
-/**
- * The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query
- * execution; exposes exactly the four operations and no protocol escape hatch.
- */
-interface LspService {
-  /**
-   * Register a provider, atomically reserving its id and every normalized extension. Any conflict
-   * or invalid input publishes nothing and throws `LspError`; the returned disposer releases all
-   * reservations. Disposed with the calling fiber.
-   * @param provider - the backend to register.
-   * @returns a synchronous disposer releasing the id and all extension reservations.
-   */
-  registerProvider(provider: LspProvider): () => void
-  /**
-   * Select a provider by the file's extension and run one query. Selection is per-query and
-   * order-independent; no match throws `LspError` `LSP_UNAVAILABLE`.
-   * @param request - the normalized query.
-   * @param signal - optional cancellation forwarded to the selected provider.
-   * @returns the normalized, closed-union result.
-   */
-  query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>
-}
-```
-
-`LspProviderId` is the seam's branded id (`Branded<'LspProviderId'>` from [dsh-brand](../../packages/util/brand)); `LspError` extends `HarnessError` with stable codes such as `LSP_INVALID_PROVIDER`, `LSP_CONFLICT`, `LSP_UNAVAILABLE`, `LSP_DISPOSED`, `LSP_UNSUPPORTED_OPERATION`, and `LSP_MALFORMED_RESPONSE`, which callers route on instead of parsing `message`.
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxlsp--lspservice"></a>
-
-### `ctx.lsp` — `LspService`
-
-The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query execution; exposes exactly the four operations and no protocol escape hatch.
-
-```ts cordis-catalog
-/**
- * Register a provider, atomically reserving its id and every normalized extension. Any conflict
- * or invalid input publishes nothing and throws `LspError`; the returned disposer releases all
- * reservations. Disposed with the calling fiber.
- * @param provider - the backend to register.
- * @returns a synchronous disposer releasing the id and all extension reservations.
- */
-registerProvider(provider: LspProvider): () => void
-
-/**
- * Select a provider by the file's extension and run one query. Selection is per-query and
- * order-independent; no match throws `LspError` `LSP_UNAVAILABLE`.
- * @param request - the normalized query.
- * @param signal - optional cancellation forwarded to the selected provider.
- * @returns the normalized, closed-union result.
- */
-query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>
-```
-
-Source: [`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
-<!-- END GENERATED cordis-surface -->

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/lsp.zh.md

@@ -1,202 +0,0 @@
-# LSP 导航
-
-[English](lsp.md) | 中文
-
-LSP seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md)：它在单一 `ctx.lsp` 服务上公开语义代码导航，并拆分到多个包：Service Definition（[dsh-lsp](../../packages/lsp/lsp)，`ctx.lsp` + 提供方注册表）、通用 Service Provider（[dsh-lsp-stdio](../../packages/lsp/lsp-stdio)，经过配置的 stdio 语言服务器宿主）和 Consumer（[dsh-tool-lsp](../../packages/lsp/tool-lsp)，即 `lsp` 工具 schema）。LSP 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.zh.md) 中。更换提供方不会改变模型请求导航的方式。
-
-源文件：[`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
-
-## 操作与坐标
-
-seam 与模型恰好公开 4 项语义查询；该联合是闭合的，因此新增一项查询会通过编译强制要求同步修改 seam、提供方和工具。位置与范围采用从零开始的 UTF-16 坐标，与协议一致；面向模型的工具采用从 1 开始的光标约定，并在输入和输出时进行转换。
-
-```ts type-equiv
-/**
- * The four semantic queries the seam and model expose. A closed union: adding an operation is a
- * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
- * not operations here; they need different schemas.
- */
-type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover'
-```
-
-```ts type-equiv
-/** A zero-based UTF-16 cursor coordinate, matching the LSP wire convention. */
-interface LspPosition {
-  /** Zero-based line. */
-  readonly line: number
-  /** Zero-based UTF-16 code-unit offset within the line. */
-  readonly character: number
-}
-```
-
-```ts type-equiv
-/** A zero-based UTF-16 half-open range `[start, end)`. */
-interface LspRange {
-  readonly start: LspPosition
-  readonly end: LspPosition
-}
-```
-
-## 请求
-
-每个字段都是必填项：`workspaceRoot` 由调用方提供，`languageId` 来自提供方注册而非请求，超时与结果上限由消费方决定。因此没有字段需要由实现提供默认值，也不存在 `resolve()` 步骤。提供方收到调用方请求和派生的 `languageId`；后者只用于同步瞬态文档，从不参与选择。
-
-```ts type-equiv
-/**
- * A caller's normalized query. Every field is required: `workspaceRoot` is caller-supplied,
- * `languageId` comes from the provider registration (not here), and consumers own timeouts and
- * result limits — so no field needs implementation defaulting and there is no `resolve()` step.
- */
-interface LspQueryRequest {
-  /** Which semantic query to run. */
-  readonly operation: LspOperation
-  /** The source file to query (relative to `workspaceRoot` or absolute; the provider canonicalizes). */
-  readonly filePath: string
-  /** The zero-based UTF-16 cursor position to query at. */
-  readonly position: LspPosition
-  /** The workspace root the provider resolves against and indexes; required, never defaulted. */
-  readonly workspaceRoot: string
-}
-```
-
-```ts type-equiv
-/**
- * A request as a provider receives it: the caller's {@link LspQueryRequest} plus the `languageId`
- * the seam derived from the provider's extension mapping. The language id only synchronizes the
- * transient document; it does not participate in selection.
- */
-interface LspProviderQuery extends LspQueryRequest {
-  /** The LSP language id for `filePath`, from this provider's extension mapping. */
-  readonly languageId: string
-}
-```
-
-## 结果
-
-这是一个闭合的可辨识联合：导航操作规范化为 `locations`，`hover` 规范化为内容或 `null`。消费方使用 `switch` 对 `kind` 做穷尽处理，因此新增分支会使编译失败，直到完成处理。`findReferences` 始终包含声明；提供方在内部强制保证这一点，因此调用方没有对应 flag。`locations` 变体携带 `resolvedWorkspaceUri`，即提供方的规范工作区 `file:` URI。调用方相对化位置 URI 时应使用这一坐标，而不是对可能经过符号链接的请求根目录应用宿主平台路径规则。
-
-```ts type-equiv
-/** One resolved location: a document URI and the range within it. */
-interface LspLocation {
-  /** The target document URI (`file:` or otherwise), verbatim from the server. */
-  readonly uri: string
-  /** The range within the target document. */
-  readonly range: LspRange
-}
-```
-
-```ts type-equiv
-/** Normalized hover content, or `null` for no hover at the position. */
-interface LspHover {
-  /** The normalized hover text (markdown or plaintext, provider-joined). */
-  readonly contents: string
-  /** The range the hover applies to, when the server supplied one. */
-  readonly range?: LspRange
-}
-```
-
-```ts type-equiv
-/**
- * The closed result union. Navigation operations (`goToDefinition`, `findReferences`,
- * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
- * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
- *
- * The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
- * the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
- * request's possibly symlinked process path with host-platform rules; the execution platform may
- * differ from the caller's.
- */
-type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceUri: string }
-  | { readonly kind: 'hover'; readonly hover: LspHover | null }
-```
-
-## 提供方与服务
-
-每个提供方拥有一个稳定的品牌化 `id`，以及一份互斥的、小写且以点开头的扩展名映射。`registerProvider` 会原子预留 id 和每个扩展名：注册无效或冲突时不发布任何内容；其 disposer 会释放所有保留项。每次查询独立选择提供方，且选择与顺序无关；没有匹配项时抛出 `LspError` `LSP_UNAVAILABLE`。该 seam 不公开协议类型、进程或文档控制，也不提供通用 JSON-RPC 逃生口。
-
-```ts type-equiv
-/**
- * A language-server backend registered on `ctx.lsp`. Each provider owns a stable {@link
- * LspProviderId} and an extension-to-language-id map (lowercase, leading-dot keys).
- * `findReferences` always includes declarations — the provider enforces this internally; callers
- * get no flag.
- */
-interface LspProvider {
-  /** Stable provider identity, reserved atomically with the extension mappings. */
-  readonly id: LspProviderId
-  /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */
-  readonly extensionToLanguage: Readonly<Record<string, string>>
-  /**
-   * Run one query. The seam has already selected this provider and derived `languageId`.
-   * @param request - the resolved provider query (caller request + derived language id).
-   * @param signal - optional cancellation; the provider stops its own work when it aborts.
-   * @returns the normalized, closed-union result.
-   */
-  query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult>
-}
-```
-
-```ts type-equiv
-/**
- * The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query
- * execution; exposes exactly the four operations and no protocol escape hatch.
- */
-interface LspService {
-  /**
-   * Register a provider, atomically reserving its id and every normalized extension. Any conflict
-   * or invalid input publishes nothing and throws `LspError`; the returned disposer releases all
-   * reservations. Disposed with the calling fiber.
-   * @param provider - the backend to register.
-   * @returns a synchronous disposer releasing the id and all extension reservations.
-   */
-  registerProvider(provider: LspProvider): () => void
-  /**
-   * Select a provider by the file's extension and run one query. Selection is per-query and
-   * order-independent; no match throws `LspError` `LSP_UNAVAILABLE`.
-   * @param request - the normalized query.
-   * @param signal - optional cancellation forwarded to the selected provider.
-   * @returns the normalized, closed-union result.
-   */
-  query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>
-}
-```
-
-`LspProviderId` 是该 seam 的品牌化 id（来自 [dsh-brand](../../packages/util/brand) 的 `Branded<'LspProviderId'>`）；`LspError` 扩展 `HarnessError`，提供 `LSP_INVALID_PROVIDER`、`LSP_CONFLICT`、`LSP_UNAVAILABLE`、`LSP_DISPOSED`、`LSP_UNSUPPORTED_OPERATION` 和 `LSP_MALFORMED_RESPONSE` 等稳定错误码，调用方应按错误码路由，而不是解析 `message`。
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxlsp--lspservice"></a>
-
-### `ctx.lsp` — `LspService`
-
-The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query execution; exposes exactly the four operations and no protocol escape hatch.
-
-```ts cordis-catalog
-/**
- * Register a provider, atomically reserving its id and every normalized extension. Any conflict
- * or invalid input publishes nothing and throws `LspError`; the returned disposer releases all
- * reservations. Disposed with the calling fiber.
- * @param provider - the backend to register.
- * @returns a synchronous disposer releasing the id and all extension reservations.
- */
-registerProvider(provider: LspProvider): () => void
-
-/**
- * Select a provider by the file's extension and run one query. Selection is per-query and
- * order-independent; no match throws `LspError` `LSP_UNAVAILABLE`.
- * @param request - the normalized query.
- * @param signal - optional cancellation forwarded to the selected provider.
- * @returns the normalized, closed-union result.
- */
-query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>
-```
-
-Source: [`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
-<!-- END GENERATED cordis-surface -->

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/permission-presets.md

@@ -1,131 +0,0 @@
-# Permission Presets
-
-English | [中文](permission-presets.zh.md)
-
-The permission-preset layer of [dsh-permission-presets](../../packages/interaction/permission-presets) (`ctx.permissionPresets`, `PermissionPresetService`) bundles the two independent enforcement knobs — [sandbox mode](sandbox.md) (`sandbox/mode`) and [approval policy](approval.md) (`approval/policy`) — into named presets a client offers as one Permissions selector. It is one optional capability, not part of the agent-loop spine, and it owns no enforcement: execution, prompt narration, and replay keep reading their knob folds, and a preset switch only records intent and writes through each knob's canonical setter. The [package README](../../packages/interaction/permission-presets/README.md) owns composition status and limitations; the [sandbox switching design](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns the rationale.
-
-Source: [`packages/interaction/permission-presets/src/index.ts`](../../packages/interaction/permission-presets/src/index.ts)
-
-## The preset table
-
-A preset is a table key mapping to one sandbox/approval bundle plus optional client presentation; the default table ships `workspace-write` (`workspace-write` + `ask`) and `danger-full-access` (`danger-full-access` + `never`).
-
-```ts type-equiv
-/** One preset's sandbox/approval bundle and optional client presentation. */
-interface PresetSpec {
-  /** The `sandbox/mode` value the preset writes through. */
-  sandbox: SandboxMode
-  /** The `approval/policy` value the preset writes through. */
-  approval: ApprovalPolicy
-  /** The display label a client shows for this preset; the raw table key when omitted. */
-  name?: string
-  /** One user-facing sentence on what the preset means; omitted when not configured. */
-  description?: string
-}
-```
-
-```ts type-equiv
-/** The {@link PermissionPresetService} config: preset table and composition default. */
-interface Config {
-  /**
-   * The preset table: name → knob bundle. Defaults to `workspace-write`
-   * (workspace-write + ask) and `danger-full-access` (danger-full-access +
-   * never). The name `custom` is reserved for the derived not-a-preset state.
-   */
-  presets?: Record<string, PresetSpec>
-  /**
-   * Default for new sessions. When omitted, the preset matching the composed
-   * sandbox and approval defaults is used.
-   */
-  defaultPreset?: string
-}
-```
-
-The service requires a confining `ctx.shell` executor and `ctx.approval`, and misconfiguration fails at plugin load: a table entry named `custom` throws (the name is reserved for the derived not-a-preset state), and composing over a bash executor that does not confine (no `sandboxMode` capability fact) throws, because presets bundle a sandbox mode.
-
-## Current preset and the derived `custom`
-
-`current(session)` derives the effective preset from the optionally registered `permissions` projection. The unit folds the session's sandbox mode, approval policy, and recorded selection; values absent within that state fall back to the executor's configured mode and the approval service config, then `ask`. A missing registry or projection key fails explicitly. The service prefers a still-matching selection, then the first matching table entry in declaration order, and otherwise returns `CUSTOM_PRESET` (`'custom'`). `custom` is derived-only: clients may display it as the current value, but it is never a switch target or an event payload.
-
-`names` lists the switchable presets in table declaration order; `optionOf(name)` builds the option a client renders for a table key (label falls back to the key) or for `custom`, and throws for any other name.
-
-```ts type-equiv
-/** The select-option shape a presentation layer advertises for one preset (or for the derived `custom` state). */
-interface PresetOption {
-  /** Stable option value: the table key, or `custom`. */
-  value: string
-  /** The display label. */
-  name: string
-  /** One user-facing sentence on what the value means; omitted when not configured. */
-  description?: string
-}
-```
-
-## Switching and the `permission/preset` event
-
-`set(session, name)` resolves the preset (unknown names throw), appends a log-only `permission/preset` event unless `name` is already the effective preset, then writes each knob through its own setter — `setSandboxMode` from [dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) and `setApprovalPolicy` from [dsh-user-approval](../../packages/interaction/user-approval) — only when that knob's effective value changes. The selection event precedes the knob events in the same turn, and re-selecting the effective preset appends nothing.
-
-`permission/preset` is durable, log-only user intent: it stays out of the model transcript (the knob events own the model-visible consequences through their consumers), and it exists so `current()` can preserve WHICH preset the user chose when two presets share a bundle. The `permissions` projection folds that selection with both knob events and retains the `session/end-seed` boundary used to distinguish a restored empty seed from a fresh session; replay needs no catch-up state or raw-log rescan. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md); the method signatures are in the generated [service catalog](#ctxpermissionpresets--permissionpresetservice).
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxpermissionpresets--permissionpresetservice"></a>
-
-### `ctx.permissionPresets` — `PermissionPresetService`
-
-Owns the deployment's permission presets and their write path. Requires a confining `ctx.shell` executor and `ctx.approval`; unmatched knob values are reported as CUSTOM_PRESET, not an error.
-
-```ts cordis-catalog
-/**
- * Resolve the preset matching the effective knob values. A still-matching
- * last selection wins shared-bundle ties; otherwise the first table match
- * wins, or {@link CUSTOM_PRESET} when no entry matches.
- * @param session - the session whose knob state is read.
- * @returns the effective preset name, or `custom` when nothing matches.
- */
-current(session: Session): string
-
-/**
- * Build the whole select value for one folded knob state: every table
- * option in declaration order, `custom` appended exactly while derived.
- * @param state - the folded knob overrides.
- * @returns the `permissions` projection payload.
- */
-selectFor(state: KnobState): PermissionSelect
-
-/**
- * Resolve a preset's knob bundle.
- * @param name - the preset name to resolve.
- * @returns the configured bundle.
- * @throws when `name` is not in the table.
- */
-resolve(name: string): PresetSpec
-
-/**
- * Build the client option for a table entry or {@link CUSTOM_PRESET}. A
- * missing label falls back to the table key.
- * @param name - a table key, or `custom`.
- * @returns the option a client renders.
- * @throws when `name` is neither a table key nor `custom`.
- */
-optionOf(name: string): PresetOption
-
-/**
- * Record a changed preset, then update each changed knob through its own
- * setter. Selecting the effective preset again appends nothing.
- * @param session - the session the switch belongs to.
- * @param name - the preset to switch to; unknown names throw.
- */
-set(session: Session, name: string): void
-```
-
-Types: [Session](session.md)
-
-Source: [`packages/interaction/permission-presets/src/index.ts`](../../packages/interaction/permission-presets/src/index.ts)
-<!-- END GENERATED cordis-surface -->