@exagone313/dsh-podman 0.2.0-rc.4 → 0.2.0

package/docs/configuration.md

@@ -8,34 +8,56 @@ SPDX-License-Identifier: MIT
 
 Environment variables use the `DSH_PODMAN_` prefix and are listed under the
 component that reads them (a variable read by several components appears in each
-of their sections). The plugin also exposes a few **UI settings** in the dsh
-**Settings → Plugins** card, listed separately from env vars.
+of their sections). The plugin also exposes a few **UI settings** on its
+**dsh-podman** page (sidebar **Plugins** panel → **Installed**), listed
+separately from env vars.
 
 The plugin reads its configuration from, in order: the plugin `config` in
 cordis, then the environment variables below, then built-in defaults.
 
 ## Plugin (dsh client) — environment variables
 
-| Variable                        | Default                 | Description                                                                                      |
-| ------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
-| `DSH_PODMAN_IMAGE_PREFIX`       | `localhost/dsh-podman/` | Prefix prepended to workspace image references                                                   |
-| `DSH_PODMAN_ORCHESTRATOR_TOKEN` | —                       | Shared secret authenticating control-plane gRPC calls; see [Variable details](#variable-details) |
-| `DSH_PODMAN_PROJECTS_ROOT`      | `/projects`             | Project root used to resolve session working directories into a workspace                        |
-| `DSH_PODMAN_SOCKETS_ROOT`       | `/run/dsh-podman`       | Socket root the plugin derives the orchestrator control socket (`orchestrator.sock`) from        |
+| Variable                        | Default           | Description                                                                                      |
+| ------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------ |
+| `DSH_PODMAN_ORCHESTRATOR_TOKEN` | —                 | Shared secret authenticating control-plane gRPC calls; see [Variable details](#variable-details) |
+| `DSH_PODMAN_PROJECTS_ROOT`      | `/projects`       | Project root used to resolve session working directories into a workspace                        |
+| `DSH_PODMAN_SOCKETS_ROOT`       | `/run/dsh-podman` | Socket root the plugin derives the orchestrator control socket (`orchestrator.sock`) from        |
 
-`projectsRoot` and `imagePrefix` are env-only so they match the orchestrator;
+`projectsRoot` and `socketsRoot` are env-only so they match the orchestrator;
 `controlToken` comes from the plugin `config` or
 `DSH_PODMAN_ORCHESTRATOR_TOKEN`.
 
 ## Plugin (dsh client) — UI settings
 
-Editable in the card's **Settings → Plugins → Podman** panel (the Configuration
-section and the images' Set-default popup):
+Editable on the **dsh-podman** page (sidebar **Plugins** panel → **Installed**;
+the images' Set-default popup and the **Default environment** section):
 
-| Setting        | Default                   | Description                                                                                                |
-| -------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `defaultImage` | `archlinux`               | Image **short name** used for new workspaces; chosen from base and custom images via the Set-default popup |
-| `socketsRoot`  | `DSH_PODMAN_SOCKETS_ROOT` | Socket root the plugin uses to reach the orchestrator; falls back to the env var                           |
+| Setting        | Default     | Description                                                                                                                                                                     |
+| -------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defaultImage` | `archlinux` | Image **short name** used for new workspaces; chosen from base and custom images via the Set-default popup                                                                      |
+| `uiLocale`     | `""`        | Plugin-managed active locale, written by the browser client so the host can render approval text in the session language (see [Approval](usage.md#approval)); not user-editable |
+| `containerEnv` | `{}`        | Default environment seeded into a container when it is created; see [Default environment](#default-environment)                                                                 |
+
+### Default environment
+
+`containerEnv` is one map of variables seeded into a container when it is
+created: the default container of a new workspace and every named container. A
+container's own `env` wins per key, and a recreate stores exactly the
+environment it is given, so removing a value from a container's environment and
+recreating it removes that value for good.
+
+The Podman page's **Default environment** section edits it with the same
+key/value rows a container uses: add or remove variables, then **Save** (or
+**Discard**). **Git identity** fills `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`,
+`GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` from one name and one email, and
+**Apply default environment variables** adds the missing values to the running
+containers that lack them, recreating only those and never overwriting an
+existing value; stopped containers are left for their next start. Every
+workspace row offers the same action for its own containers. Reserved
+`DSH_PODMAN*` keys are ignored, and the values are not secret — use `secretEnv`
+for secrets (see [Secrets](usage.md#secrets)).
+
+## Orchestrator (`dsh-podman-orchestrator`)
 
 | Variable                                       | Default                       | Description                                                                                                                                                                                                        |
 | ---------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -49,10 +71,10 @@ section and the images' Set-default popup):
 | `DSH_PODMAN_HOST_GUEST_AGENT_BIN`              | —                             | Host-side guest agent binary path; bind-mounted when set; see [Variable details](#variable-details)                                                                                                                |
 | `DSH_PODMAN_HOST_PACMAN_CACHE`                 | —                             | Host-absolute directory mounted at `/var/cache/pacman/pkg` to persist downloaded packages across pacman builds; unset disables caching                                                                             |
 | `DSH_PODMAN_HOST_PROJECTS_ROOT`                | `DSH_PODMAN_PROJECTS_ROOT`    | Host-side projects root used as the source of bind mounts                                                                                                                                                          |
-| `DSH_PODMAN_HOST_SOCKETS_ROOT`                 | `DSH_PODMAN_SOCKETS_ROOT`     | Host-side sockets root for guest socket bind mounts                                                                                                                                                                |
+| `DSH_PODMAN_HOST_SOCKETS_ROOT`                 | required                      | Host-side sockets root for guest socket bind mounts; see [Variable details](#variable-details)                                                                                                                     |
 | `DSH_PODMAN_IMAGE_PREFIX`                      | `localhost/dsh-podman/`       | Prefix prepended to built workspace image references                                                                                                                                                               |
 | `DSH_PODMAN_ORCHESTRATOR_PODMAN_SOCKET`        | required                      | Podman API socket, e.g. `unix:///run/podman/podman.sock`                                                                                                                                                           |
-| `DSH_PODMAN_ORCHESTRATOR_STATE`                | `/var/lib/dsh-orchestrator`   | Persisted state directory                                                                                                                                                                                          |
+| `DSH_PODMAN_ORCHESTRATOR_STATE`                | required                      | Persisted state directory; see [Variable details](#variable-details)                                                                                                                                               |
 | `DSH_PODMAN_ORCHESTRATOR_TOKEN`                | —                             | Shared secret authenticating control-plane gRPC calls; see [Variable details](#variable-details)                                                                                                                   |
 | `DSH_PODMAN_PROJECTS_ROOT`                     | `/projects`                   | Project root inside every guest container                                                                                                                                                                          |
 | `DSH_PODMAN_SECRET_PREFIX`                     | `dsh-podman-`                 | Prefix applied to managed podman secrets (see [Usage](usage.md#secrets))                                                                                                                                           |
@@ -94,8 +116,7 @@ binary. Setting it bind-mounts that binary read-only to the same in-container
 path instead of mounting the guest-agent image; it is an optional development
 fallback and takes precedence over the image mount. It is unset by default.
 
-If neither variable is configured, the guest container has no guest agent to
-run, and creating a workspace container fails.
+If neither variable is configured, the orchestrator refuses to start.
 
 ### `DSH_PODMAN_GUEST_AGENT_IMAGE`, `DSH_PODMAN_GUEST_AGENT_IMAGE_AGENT_BIN`, `DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT` and `DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG`
 
@@ -118,6 +139,12 @@ orchestrator uses its own git version as the image tag instead of the one in
 digest reference cannot be overridden, the orchestrator fails to start when that
 variable is set alongside a digest-style `DSH_PODMAN_GUEST_AGENT_IMAGE`.
 
+A container whose agent was created from a different guest-agent image than the
+one currently configured is recreated the next time it is used, so upgrading the
+orchestrator takes effect without recreating containers by hand. The image is
+pulled only when it is absent, so a locally built development image is never
+pulled over.
+
 ### `DSH_PODMAN_GUEST_TOKEN`
 
 Shared secret required on every guest-agent gRPC call, carried as the gRPC
@@ -137,12 +164,26 @@ orchestrator has no token set, it accepts unauthenticated control-plane calls
 (relying on the socket's file permissions instead); when a token is set,
 requests without the matching header are rejected with `Unauthenticated`.
 
+### `DSH_PODMAN_ORCHESTRATOR_STATE`
+
+The directory the orchestrator persists its state in (workspaces, containers,
+and image records). It is required, and must be an absolute path to a directory
+bind-mounted into the orchestrator so the state survives a container restart:
+only the deployment knows where that is. The shipped Quadlet mounts
+`%h/.dsh/dsh-podman/state`. The orchestrator creates the directory if needed and
+refuses to start without the variable.
+
 ### `DSH_PODMAN_SOCKETS_ROOT` and `DSH_PODMAN_HOST_SOCKETS_ROOT`
 
 `DSH_PODMAN_SOCKETS_ROOT` is the socket root directory shared by the
 orchestrator and the guest containers. It holds the orchestrator control socket
 (`orchestrator.sock`) and one subdirectory per workspace, where each guest agent
-creates its `guest.sock`.
+creates its `guest.sock`. It keeps its `/run/dsh-podman` default.
+
+`DSH_PODMAN_HOST_SOCKETS_ROOT` is required: it is the same directory as it
+appears on the host, and it cannot be derived from the container path — the
+shipped Quadlet mounts `%t/dsh-podman` at `/run/dsh-podman`. The orchestrator
+refuses to start without it.
 
 The directory needs to be bind-mounted in the orchestrator container. Its mode
 must be `0700`: the orchestrator refuses to start when the socket root is group-

package/docs/configuration.zh.md

@@ -8,32 +8,50 @@ SPDX-License-Identifier: MIT
 
 环境变量使用 `DSH_PODMAN_`
 前缀，并按读取它们的组件分组列出（被多个组件读取的变量会出现在每个组件的对应章节中）。插件还在
-dsh 的 **设置 → 插件** 卡片中暴露了一些 **UI 设置**，与环境变量分开列出。
+侧边栏 **插件** 面板 → **已安装** 中的 **dsh-podman** 页面中暴露了一些 **UI
+设置**，与环境变量分开列出。
 
 插件按以下顺序读取其配置：先是 cordis 中的插件
 `config`，然后是下方列出的环境变量，最后是内置默认值。
 
 ## 插件（dsh 客户端）— 环境变量
 
-| 变量                            | 默认值                  | 说明                                                                      |
-| ------------------------------- | ----------------------- | ------------------------------------------------------------------------- |
-| `DSH_PODMAN_IMAGE_PREFIX`       | `localhost/dsh-podman/` | 前置到工作区镜像引用上的前缀                                              |
-| `DSH_PODMAN_ORCHESTRATOR_TOKEN` | —                       | 用于认证控制平面 gRPC 调用的共享机密；见[变量详解](#变量详解)             |
-| `DSH_PODMAN_PROJECTS_ROOT`      | `/projects`             | 用于将会话工作目录解析为工作区的项目根目录                                |
-| `DSH_PODMAN_SOCKETS_ROOT`       | `/run/dsh-podman`       | 插件据此推导 orchestrator 控制套接字（`orchestrator.sock`）的套接字根目录 |
+| 变量                            | 默认值            | 说明                                                                      |
+| ------------------------------- | ----------------- | ------------------------------------------------------------------------- |
+| `DSH_PODMAN_ORCHESTRATOR_TOKEN` | —                 | 用于认证控制平面 gRPC 调用的共享机密；见[变量详解](#变量详解)             |
+| `DSH_PODMAN_PROJECTS_ROOT`      | `/projects`       | 用于将会话工作目录解析为工作区的项目根目录                                |
+| `DSH_PODMAN_SOCKETS_ROOT`       | `/run/dsh-podman` | 插件据此推导 orchestrator 控制套接字（`orchestrator.sock`）的套接字根目录 |
 
-`projectsRoot` 和 `imagePrefix` 仅来自环境变量，以确保与 orchestrator
+`projectsRoot` 与 `socketsRoot` 仅来自环境变量，以确保与 orchestrator
 一致；`controlToken` 来自插件 `config` 或 `DSH_PODMAN_ORCHESTRATOR_TOKEN`。
 
 ## 插件（dsh 客户端）— UI 设置
 
-可在卡片中的 **设置 → 插件 → Podman** 面板内编辑（配置部分和镜像的 Set-default
-弹窗）：
+可在侧边栏 **插件** 面板 → **已安装** 的 **dsh-podman** 页面内编辑（镜像的
+Set-default 弹窗和**默认环境变量**区块）：
 
-| 设置           | 默认值                    | 说明                                                                              |
-| -------------- | ------------------------- | --------------------------------------------------------------------------------- |
-| `defaultImage` | `archlinux`               | 用于新工作区的镜像**短名称**；可通过 Set-default 弹窗从基础镜像和自定义镜像中选择 |
-| `socketsRoot`  | `DSH_PODMAN_SOCKETS_ROOT` | 插件用于连接 orchestrator 的套接字根目录；回退到环境变量                          |
+| 设置           | 默认值      | 说明                                                                                                                 |
+| -------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
+| `defaultImage` | `archlinux` | 用于新工作区的镜像**短名称**；可通过 Set-default 弹窗从基础镜像和自定义镜像中选择                                    |
+| `uiLocale`     | `""`        | 插件管理的当前语言，由浏览器客户端写入，以便主机以会话语言呈现审批文本（见[审批](usage.zh.md#审批)）；不可由用户编辑 |
+| `containerEnv` | `{}`        | 容器创建时注入的默认环境变量；见[默认环境变量](#默认环境变量)                                                        |
+
+### 默认环境变量
+
+`containerEnv`
+是一个在容器创建时注入的环境变量映射：新工作区的默认容器与每个命名容器都会收到它。容器自身的
+`env`
+按变量逐个优先，而重建容器时会完全采用传入的环境变量，因此在容器的环境变量里删除某一项并重建该容器，即可彻底移除它。
+
+Podman
+页面中的**默认环境变量**区块使用与容器相同的键/值行进行编辑：增删变量后点击**保存**（或**放弃**）。**Git
+身份**用一份姓名与邮箱填入
+`GIT_AUTHOR_NAME`、`GIT_AUTHOR_EMAIL`、`GIT_COMMITTER_NAME` 与
+`GIT_COMMITTER_EMAIL`；**应用默认环境变量**会把缺少的变量补给尚未具备它们的运行中容器，只重建这些容器，且绝不覆盖已有值；已停止的容器留待下次启动。每个工作区行也提供同样的操作，只作用于该工作区。保留的
+`DSH_PODMAN*` 键会被忽略，且这些值并非机密——机密请使用
+`secretEnv`（见[机密](usage.zh.md#机密)）。
+
+## Orchestrator（`dsh-podman-orchestrator`）
 
 | 变量                                           | 默认值                        | 说明                                                                                                                                                                |
 | ---------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -47,10 +65,10 @@ dsh 的 **设置 → 插件** 卡片中暴露了一些 **UI 设置**，与环境
 | `DSH_PODMAN_HOST_GUEST_AGENT_BIN`              | —                             | 主机侧的 guest agent 二进制路径；设置后会绑定挂载；见[变量详解](#变量详解)                                                                                          |
 | `DSH_PODMAN_HOST_PACMAN_CACHE`                 | —                             | 挂载在 `/var/cache/pacman/pkg` 的主机绝对路径目录，用于在 pacman 构建之间持久化已下载的软件包；未设置时禁用缓存                                                     |
 | `DSH_PODMAN_HOST_PROJECTS_ROOT`                | `DSH_PODMAN_PROJECTS_ROOT`    | 用作绑定挂载源的主机侧项目根目录                                                                                                                                    |
-| `DSH_PODMAN_HOST_SOCKETS_ROOT`                 | `DSH_PODMAN_SOCKETS_ROOT`     | 用于 guest 套接字绑定挂载的主机侧套接字根目录                                                                                                                       |
+| `DSH_PODMAN_HOST_SOCKETS_ROOT`                 | required                      | 用于 guest 套接字绑定挂载的主机侧套接字根目录；见[变量详解](#变量详解)                                                                                              |
 | `DSH_PODMAN_IMAGE_PREFIX`                      | `localhost/dsh-podman/`       | 前置到已构建的工作区镜像引用上的前缀                                                                                                                                |
 | `DSH_PODMAN_ORCHESTRATOR_PODMAN_SOCKET`        | required                      | Podman API 套接字，例如 `unix:///run/podman/podman.sock`                                                                                                            |
-| `DSH_PODMAN_ORCHESTRATOR_STATE`                | `/var/lib/dsh-orchestrator`   | 持久化状态目录                                                                                                                                                      |
+| `DSH_PODMAN_ORCHESTRATOR_STATE`                | required                      | 持久化状态目录；见[变量详解](#变量详解)                                                                                                                             |
 | `DSH_PODMAN_ORCHESTRATOR_TOKEN`                | —                             | 用于认证控制平面 gRPC 调用的共享机密；见[变量详解](#变量详解)                                                                                                       |
 | `DSH_PODMAN_PROJECTS_ROOT`                     | `/projects`                   | 每个 guest 容器内的项目根目录                                                                                                                                       |
 | `DSH_PODMAN_SECRET_PREFIX`                     | `dsh-podman-`                 | 应用于受管 podman 机密的前缀（见[使用](usage.zh.md#机密)）                                                                                                          |
@@ -89,8 +107,7 @@ orchestrator
 二进制在_主机上_的路径。设置它会将该二进制以只读方式绑定挂载到容器内相同路径，而不是挂载
 guest-agent 镜像；这是一个可选的开发回退方案，优先于镜像挂载。默认情况下未设置。
 
-如果两个变量都未配置，guest 容器将没有可运行的 guest
-agent，创建工作区容器将会失败。
+如果两个变量都未配置，orchestrator 将拒绝启动。
 
 ### `DSH_PODMAN_GUEST_AGENT_IMAGE`, `DSH_PODMAN_GUEST_AGENT_IMAGE_AGENT_BIN`, `DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT` and `DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG`
 
@@ -111,6 +128,10 @@ guest-agent 镜像在容器创建时提供 agent：orchestrator 使用 podman
 中的标签（该标签可以完全省略）。由于摘要引用无法被覆盖，当该变量与摘要式的
 `DSH_PODMAN_GUEST_AGENT_IMAGE` 一起设置时，orchestrator 将无法启动。
 
+如果容器的 agent 来自与当前配置不同的 guest-agent
+镜像，该容器会在下次被使用时被重新创建，因此升级 orchestrator
+后无需手动重建容器即可生效。只有在镜像不存在时才会拉取，因此本地构建的开发镜像绝不会被拉取覆盖。
+
 ### `DSH_PODMAN_GUEST_TOKEN`
 
 每次 guest-agent gRPC 调用所需的共享机密，以 gRPC 元数据头
@@ -126,12 +147,25 @@ orchestrator 和插件必须约定的任意共享机密字符串；每个控制
 未设置令牌时，它接受未经认证的控制平面调用（转而依赖套接字的文件权限）；当设置了令牌时，不带匹配头的请求会被以
 `Unauthenticated` 拒绝。
 
+### `DSH_PODMAN_ORCHESTRATOR_STATE`
+
+orchestrator
+持久化其状态（工作区、容器和镜像记录）的目录。该变量为必填，且必须是绑定挂载到
+orchestrator
+的目录的绝对路径，以便状态在容器重启后仍然保留——只有部署方知道该路径。随附的
+Quadlet 会挂载 `%h/.dsh/dsh-podman/state`。orchestrator
+会在需要时创建该目录，缺少该变量时拒绝启动。
+
 ### `DSH_PODMAN_SOCKETS_ROOT` and `DSH_PODMAN_HOST_SOCKETS_ROOT`
 
 `DSH_PODMAN_SOCKETS_ROOT` 是 orchestrator 与 guest
 容器共享的套接字根目录。它包含 orchestrator
 控制套接字（`orchestrator.sock`）和每个工作区的一个子目录，每个 guest agent
-在其中创建自己的 `guest.sock`。
+在其中创建自己的 `guest.sock`。它保留 `/run/dsh-podman` 默认值。
+
+`DSH_PODMAN_HOST_SOCKETS_ROOT`
+为必填：它是同一目录在主机上的路径，无法从容器路径推导——随附的 Quadlet 将
+`%t/dsh-podman` 挂载到 `/run/dsh-podman`。缺少该变量时 orchestrator 拒绝启动。
 
 该目录需要绑定挂载到 orchestrator 容器中。其权限模式必须是
 `0700`：当套接字根目录对组或其他用户可访问时，orchestrator

package/docs/development-prompt.md

@@ -0,0 +1,72 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# Development container setup prompt
+
+This page carries the prompt that builds a development image, creates the
+toolchain volume and wires the workspace container to it, as described in
+[Development](development.md#development-container-toolchain). Nothing it needs
+exists beforehand.
+
+Paste the block below into a dsh session attached to the workspace. It is safe
+to run again: it inspects the workspace first and only creates, mounts or
+changes what is missing or different. Recreating a container stops its daemons
+and clears its tmpfs, so expect that whenever a change is needed.
+
+Two steps stay manual on the host, and the prompt asks for them instead of
+attempting them:
+
+- rebuilding the dsh, orchestrator and guest-agent images (`make image`), which
+  needs the repository checkout and podman on the host;
+- installing or editing the Quadlet units under `~/.config/containers/systemd/`,
+  then `systemctl --user daemon-reload` and a restart (see
+  [Install development builds](development.md#install-development-builds)).
+
+```text
+Set up a development environment for this dsh-podman workspace. It must be safe
+to run again: inspect the current state first, and only create, mount or change
+what is missing or different, keeping whatever is already configured. Use the
+container tools; never run `make` or edit files on the host.
+
+1. Image: build a custom image named `dsh-podman-tooling` from the `archlinux`
+   base with packages `go`, `nodejs-lts-jod`, `npm`, `deno`, `reuse` and
+   `python-chardet`, unless an image of that name already exists in this
+   workspace. It is a local image, not a published one; leave an existing one
+   alone.
+2. Volume: create the workspace volume `dsh-podman-toolchain` unless it already
+   exists.
+3. Container: inspect the default container's image, mounts, PATH additions and
+   environment. Recreate it once, only if something below is missing or
+   different, passing the complete merged sets so nothing existing is dropped:
+   - image `dsh-podman-tooling`;
+   - `dsh-podman-toolchain` mounted at `/opt/toolchain`, read-write, plus the
+     workspace project mount and every mount already there;
+   - PATH additions `/opt/toolchain/gopath/bin`,
+     `/opt/toolchain/npm-global/bin` and `/opt/toolchain/pnpm-home`, in
+     addition to the ones already there;
+   - environment `GOCACHE=/opt/toolchain/gocache`,
+     `GOMODCACHE=/opt/toolchain/gomodcache`, `GOPATH=/opt/toolchain/gopath`,
+     `npm_config_cache=/opt/toolchain/npm-cache`,
+     `npm_config_prefix=/opt/toolchain/npm-global`,
+     `PNPM_HOME=/opt/toolchain/pnpm-home`,
+     `DENO_DIR=/opt/toolchain/deno-dir` and
+     `GOENV=/opt/toolchain/home/.config/go/env`, merged with the variables
+     already on the container.
+4. pnpm: the volume, not the image, carries pnpm. If `pnpm --version` does not
+   report the version `package.json` pins in `packageManager`, install it with
+   `npm install -g pnpm@<that version>` and check again.
+5. Git identity: do not write a `~/.gitconfig`. If no Git identity is
+   configured, tell me to set it once on the Podman page (sidebar **Plugins**
+   panel → **Installed** → **dsh-podman**): **Default
+   environment → Git identity**.
+6. Verify from inside the container, without sourcing anything: `make build`,
+   `make vet` and `pnpm test` must succeed in the repository.
+7. Report what you created or changed, or that everything was already in place.
+   If a step needs the host — rebuilding the dsh, orchestrator or guest-agent
+   images (`make image`), or editing the Quadlet units under
+   `~/.config/containers/systemd/` and reloading systemd — stop and ask me
+   instead of trying it.
+```

package/docs/development-prompt.zh.md

@@ -0,0 +1,69 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# 开发容器设置提示词
+
+本页给出用于构建开发镜像、创建工具链卷并把工作区容器接好的提示词，参见[开发](development.zh.md#开发容器工具链)。其中没有任何东西是现成的。
+
+把下面的文本块粘贴到已接入该工作区的 dsh
+会话中。它可以反复运行：先检查工作区现状，只创建、挂载或修改缺失或不同的部分。重建容器会终止其守护进程并清空
+tmpfs，因此在需要变更时请预期这一点。
+
+以下步骤仍需在宿主机上手动完成，提示词只会请求它们，而不会自行尝试：
+
+- 重建 dsh、orchestrator 和 guest-agent
+  镜像（`make image`），这需要宿主机上的仓库检出与 podman；
+- 安装或编辑 `~/.config/containers/systemd/` 下的 Quadlet 单元，随后执行
+  `systemctl --user daemon-reload`
+  并重启（见[安装开发构建](development.zh.md#安装开发构建)）。
+
+下面的提示词与英文页保持一致，原样粘贴即可。
+
+```text
+Set up a development environment for this dsh-podman workspace. It must be safe
+to run again: inspect the current state first, and only create, mount or change
+what is missing or different, keeping whatever is already configured. Use the
+container tools; never run `make` or edit files on the host.
+
+1. Image: build a custom image named `dsh-podman-tooling` from the `archlinux`
+   base with packages `go`, `nodejs-lts-jod`, `npm`, `deno`, `reuse` and
+   `python-chardet`, unless an image of that name already exists in this
+   workspace. It is a local image, not a published one; leave an existing one
+   alone.
+2. Volume: create the workspace volume `dsh-podman-toolchain` unless it already
+   exists.
+3. Container: inspect the default container's image, mounts, PATH additions and
+   environment. Recreate it once, only if something below is missing or
+   different, passing the complete merged sets so nothing existing is dropped:
+   - image `dsh-podman-tooling`;
+   - `dsh-podman-toolchain` mounted at `/opt/toolchain`, read-write, plus the
+     workspace project mount and every mount already there;
+   - PATH additions `/opt/toolchain/gopath/bin`,
+     `/opt/toolchain/npm-global/bin` and `/opt/toolchain/pnpm-home`, in
+     addition to the ones already there;
+   - environment `GOCACHE=/opt/toolchain/gocache`,
+     `GOMODCACHE=/opt/toolchain/gomodcache`, `GOPATH=/opt/toolchain/gopath`,
+     `npm_config_cache=/opt/toolchain/npm-cache`,
+     `npm_config_prefix=/opt/toolchain/npm-global`,
+     `PNPM_HOME=/opt/toolchain/pnpm-home`,
+     `DENO_DIR=/opt/toolchain/deno-dir` and
+     `GOENV=/opt/toolchain/home/.config/go/env`, merged with the variables
+     already on the container.
+4. pnpm: the volume, not the image, carries pnpm. If `pnpm --version` does not
+   report the version `package.json` pins in `packageManager`, install it with
+   `npm install -g pnpm@<that version>` and check again.
+5. Git identity: do not write a `~/.gitconfig`. If no Git identity is
+   configured, tell me to set it once on the Podman page (sidebar **Plugins**
+   panel → **Installed** → **dsh-podman**): **Default
+   environment → Git identity**.
+6. Verify from inside the container, without sourcing anything: `make build`,
+   `make vet` and `pnpm test` must succeed in the repository.
+7. Report what you created or changed, or that everything was already in place.
+   If a step needs the host — rebuilding the dsh, orchestrator or guest-agent
+   images (`make image`), or editing the Quadlet units under
+   `~/.config/containers/systemd/` and reloading systemd — stop and ask me
+   instead of trying it.
+```

package/docs/development.md

@@ -20,8 +20,8 @@ This page is for **contributors** building the plugin from this repository.
 
 ## Building
 
-Prerequisites: Go 1.27, Node ≥ 22, pnpm 12, and (for the browser half) the
-`@deepseek-ai/dsh-client-*` packages published on npm.
+Prerequisites: Go 1.27, Node ≥ 22, pnpm 12, Deno ≥ 2.9 (formatting), and (for
+the browser half) the `@deepseek-ai/dsh-client-*` packages published on npm.
 
 ```sh
 pnpm install
@@ -36,20 +36,22 @@ The `Makefile` wraps the common workflows:
 ```sh
 make build-go       # build both Go binaries into bin/<os>-<arch>/
 make build          # build-go + pnpm-build
-make vet            # go vet with the build tags
+make vet            # gofmt -s check + go vet with the build tags
 make test-go        # go test with the build tags
 make test           # test-go + pnpm test (JS tests, which run against dist/)
-make download-licenses  # generate LICENSE.pkg from the project and third-party Go licenses
-make image          # build the orchestrator and guest-agent container images
+make fmt            # gofmt -s + deno fmt (TypeScript and Markdown)
+make fmt-check      # verify the formatting without rewriting anything
+make download-licenses  # generate third-party-licenses.pkg from the project and third-party Go licenses
+make image          # build the orchestrator, guest-agent and dsh container images
 ```
 
-`make image` depends on `LICENSE.pkg`: the `download-licenses` target runs the
-Go collector in `scripts/download-licenses`, which shells out to
+`make image` depends on `third-party-licenses.pkg`: the `download-licenses`
+target runs the Go collector in `scripts/download-licenses`, which shells out to
 `go-licenses save` and gathers the project's MIT license plus every third-party
-Go license and Apache `NOTICE` into `LICENSE.pkg`. That file is gitignored
-(never committed) and is baked into the orchestrator and guest-agent images at
-`/usr/share/licenses/dsh-podman/LICENSE`; because workspace containers mount the
-guest-agent image, it also rides along into every workspace container.
+Go license and Apache `NOTICE` into `third-party-licenses.pkg`. That file is
+gitignored (never committed) and is baked into the orchestrator and guest-agent
+images at `/usr/share/licenses/dsh-podman/LICENSE`; because workspace containers
+mount the guest-agent image, it also rides along into every workspace container.
 
 `pnpm test` runs `node --test dist/*.test.js`, so it requires `pnpm build` to
 have run first (the `test` target handles this).
@@ -66,6 +68,19 @@ The JS side loads the raw `.proto` files at runtime via `@grpc/proto-loader`
 (copied to `dist/grpc/proto/` at build time); no TypeScript bindings are
 generated. Optionally validate the schema with `buf lint` and `buf breaking`.
 
+## Naming
+
+Proto field names are `lower_snake_case` (Buf's `BASIC` lint enforces it), and
+the JS side reads them through proto-loader's camelCase projection, so
+`secret_env` becomes `secretEnv` and `image_id` becomes `imageId`. Never spell a
+proto field in its snake_case form in TypeScript: proto-loader ignores an
+unknown property, so the value would be silently dropped.
+
+Tool parameters are camelCase, except the ones that deliberately mirror the
+harness's built-in tools (`file_path`, `old_string`, `new_string`,
+`replace_all`). Settings are camelCase; the persisted TOML state uses snake_case
+tags.
+
 ## Install development builds
 
 ### Build
@@ -75,17 +90,121 @@ make  # builds plugin and go binaries
 make image  # build images
 ```
 
-### Recreate containers
+### Run the local images (Quadlet)
+
+The shipped units pull the release images. Point them at the images built by
+`make image` to run a local build as the real services; comment the original
+line out so switching back is a one-line edit.
+
+In `~/.config/containers/systemd/dsh.container`:
+
+```ini
+#Image=ghcr.io/exagone313/dsh-podman/dsh:1
+Image=localhost/dsh-podman-dsh:latest
+Environment=DSH_PODMAN_PLUGIN_SOURCE=%h/project/dsh-podman
+```
+
+The unit already mounts `%h/project` read-only, so a repository checked out
+under `~/project` needs no extra `Volume=`. `npm pack` leaves the archive the
+entrypoint installs next to `package.json` (see
+[Install a local plugin build](#install-a-local-plugin-build)).
+
+In `~/.config/containers/systemd/dsh-podman-orchestrator.container`:
+
+```ini
+#Image=ghcr.io/exagone313/dsh-podman/orchestrator:1
+Image=localhost/dsh-podman-orchestrator:latest
+#Environment=DSH_PODMAN_GUEST_AGENT_IMAGE=ghcr.io/exagone313/dsh-podman/guest-agent
+#Environment=DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG=true
+Environment=DSH_PODMAN_GUEST_AGENT_IMAGE=localhost/dsh-podman-guest-agent:latest
+```
+
+The release reference is version-tagged, so every release gets a distinct image
+reference. The local build reuses a single `:latest` tag instead; the
+orchestrator then cannot tell that the agent was rebuilt, which is what
+[Update workspace containers](#update-workspace-containers) is about.
+
+Reload systemd after editing the units:
 
 ```bash
+systemctl --user daemon-reload
+```
+
+### Deploy a change
+
+```bash
+make            # Go binaries + the plugin bundle
+make image      # orchestrator, guest-agent and dsh images
+npm pack        # the plugin archive the dsh entrypoint installs
 systemctl --user restart dsh dsh-podman-orchestrator
 ```
 
+The dsh image installs the plugin at container start, so restarting dsh is what
+reinstalls the freshly packed archive; restarting the orchestrator picks up the
+new orchestrator and guest-agent images.
+
+### Update workspace containers
+
+The guest-agent image is mounted into each container when it is created, so a
+running container keeps the agent it started with. The orchestrator recreates a
+container by itself only when its guest-agent image reference differs from the
+configured one — which happens with the version-tagged release reference, but
+not with the local `:latest` tag. After rebuilding the guest agent, recreate the
+containers yourself:
+
+- from the Podman page (sidebar **Plugins** panel → **Installed** →
+  **dsh-podman**), per container: **Recreate** (same image) or **Recreate with
+  image**;
+- with `container_recreate`, for a named container or the default one.
+
+To rebuild a whole workspace instead, use **Remove pod** on its row (or
+`RemoveWorkspace`): the pod and all its containers are removed, and the next
+attach creates the pod and its default container again. Restarting the two
+services never touches workspace containers, and neither action removes volumes,
+secrets, or project data.
+
+A container that still runs an agent from an older image makes dsh log
+`rejected by server because of excess pings` for its guest socket. The message
+is harmless (grpc-js backs off and reconnects) and disappears once the container
+is recreated; the same message for `orchestrator.sock` means the orchestrator
+service is still running the previous image.
+
+### Development container toolchain
+
+A workspace container's root filesystem is read-only and disposable, so the
+toolchain a contributor builds with needs a workspace volume. No development
+image is distributed: build a custom one — the
+[setup prompt](development-prompt.md) builds `dsh-podman-tooling` from the
+`archlinux` base with `go`, `nodejs-lts-jod`, `npm`, `deno`, `reuse` and
+`python-chardet` — and create a workspace volume for the state an image cannot
+keep: the Go and npm caches, `gopath` with the `go install`ed tools, and pnpm,
+which `package.json` pins to a version the Arch repositories do not carry.
+
+The prompt mounts that volume as `dsh-podman-toolchain` at `/opt/toolchain`
+(read-write) and points the container's caches at it, so commands work without
+sourcing anything:
+
+| Container setting | Value                                                                                                                                                                                                                                                                                                                      |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PATH additions    | `/opt/toolchain/gopath/bin`, `/opt/toolchain/npm-global/bin`, `/opt/toolchain/pnpm-home`                                                                                                                                                                                                                                   |
+| Environment       | `GOCACHE=/opt/toolchain/gocache`, `GOMODCACHE=/opt/toolchain/gomodcache`, `GOPATH=/opt/toolchain/gopath`, `npm_config_cache=/opt/toolchain/npm-cache`, `npm_config_prefix=/opt/toolchain/npm-global`, `PNPM_HOME=/opt/toolchain/pnpm-home`, `DENO_DIR=/opt/toolchain/deno-dir`, `GOENV=/opt/toolchain/home/.config/go/env` |
+
+Set the commit identity once on the Podman page (sidebar **Plugins** panel →
+**Installed** → **dsh-podman**) under
+[Default environment](configuration.md#default-environment) → **Git identity**,
+so containers get `GIT_AUTHOR_*`/`GIT_COMMITTER_*` without a `~/.gitconfig`.
+
+The prompt applies all of this from inside dsh and can be pasted again to repair
+a workspace. Podman stores managed volumes with `DSH_PODMAN_VOLUME_PREFIX`
+prepended, so it lists the volume as `dsh-podman-dsh-podman-toolchain`.
+
 ### Install a local plugin build
 
 The dsh image installs the plugin itself at container start, so a development
-build is served by pointing that install at a bind-mounted package. Build the
-plugin and pack it:
+build is served by pointing that install at a bind-mounted package. The Quadlet
+setup above is the first form below, with the repository directory itself
+(`%h/project/dsh-podman`) already visible through the unit's read-only
+`%h/project` mount. Build the plugin and pack it:
 
 ```bash
 pnpm build
@@ -102,7 +221,7 @@ Environment=DSH_PODMAN_PLUGIN_SOURCE=/mnt/dsh-podman
 
 ```
 # or the archive itself
-Volume=/path/to/exagone313-dsh-podman-0.2.0-rc.3.tgz:/mnt/dsh-podman.tgz:ro
+Volume=/path/to/exagone313-dsh-podman-x.y.z.tgz:/mnt/dsh-podman.tgz:ro
 Environment=DSH_PODMAN_PLUGIN_SOURCE=/mnt/dsh-podman.tgz
 ```
 
@@ -123,10 +242,11 @@ push runs only `release.yml`, which repeats the build, vet and tests itself:
 
 - **actions-lint** — zizmor scans the workflows for insecure practices.
 - **reuse** — REUSE license compliance.
-- **go** — build, vet, tests, and govulncheck (Go vulnerabilities). Unfixed
-  findings don't fail the job; fixable ones do.
-- **js** — install, typecheck, build, tests, and `pnpm audit`.
-- **docs** — `deno fmt --check` on the Markdown.
+- **go** — build, `gofmt -s` check, vet, tests, and govulncheck (Go
+  vulnerabilities). Unfixed findings don't fail the job; fixable ones do.
+- **js** — TypeScript formatting check, install, typecheck, build, tests, and
+  `pnpm audit`.
+- **docs** — Markdown formatting check (`deno fmt` via `make fmt-check-md`).
 - **images** — builds the orchestrator and guest-agent images (runs only after
   the test jobs pass); **dsh image** builds `Containerfile.dsh`.
 - **trivy** — filesystem vulnerability scan (unfixed ignored) and container
@@ -157,8 +277,8 @@ The tag must match `package.json`'s version — the workflow fails otherwise —
 bump both with the version script:
 
 ```sh
-pnpm bump-version 0.1.1            # add --dry-run to validate only
-git push origin master 0.1.1
+pnpm bump-version x.y.z            # add --dry-run to validate only
+git push origin master x.y.z
 ```
 
 `scripts/bump-version.mjs` checks that the version is a semver release or