docs: make technical prose concrete

docs/user/develop/basic/index.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/index.md
-index.md: efedb07c8d757ef1f90d99fe1bf503a35c0f1a37
-index.zh.md: 2293a6086dc80fa77c88ef734ae17576ea513a10
+index.md: 7fe66bb19ddb978a4b5a96768b62151b97bca0ec
+index.zh.md: 59f4e5b58b6cf1fbc15de8fafb5f4b0db2e220d6

docs/user/develop/basic/index.md

@@ -26,7 +26,7 @@ export function apply(ctx: Context) {
 }
 ```
 
-That is the complete shape.
+That is the complete configuration.
 
 ## Create the plugin file
 

docs/user/develop/basic/index.zh.md

@@ -26,7 +26,7 @@ export function apply(ctx: Context) {
 }
 ```
 
-这就是完整结构。
+这就是完整配置。
 
 ## 创建插件文件
 

docs/user/develop/basic/publish.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/publish.md
-publish.md: 1d1179a78c4d3a7e9e7055e3f5ee41381e28147e
-publish.zh.md: d683762b78920dc754b6871ed7bd0caf3ee9afd4
+publish.md: 7657654b1467c14b22e0eb6372c2bc4e77db2f38
+publish.zh.md: 7af2ae3a06cc74597d5cbd6fddd46fbab069e287

docs/user/develop/basic/publish.md

@@ -33,7 +33,7 @@ hello-plugin/
 }
 ```
 
-The patch file has the same shape as the `--patch` overlays you have been writing — a YAML array of patch entries — except plugin rows reference the package by name instead of a relative source path, so Node resolution finds the installed code:
+The patch file is a YAML array of patch entries, like the `--patch` overlays you have been writing, except plugin rows reference the package by name instead of a relative source path so Node resolution finds the installed code:
 
 ```yaml
 - insert:
@@ -41,7 +41,7 @@ The patch file has the same shape as the `--patch` overlays you have been writin
       name: dsh-hello-plugin
 ```
 
-A package without the `dsh.bundle` declaration still installs, but only as a plain dependency: `dsh plugin` prints a warning and activates no layer. That is the correct shape for a library that plugin packages import rather than a plugin users enable.
+A package without the `dsh.bundle` declaration still installs, but only as a plain dependency: `dsh plugin` prints a warning and activates no layer. Use that package format for a library that plugin packages import rather than a plugin users enable.
 
 ### The profile manifest
 

docs/user/develop/basic/publish.zh.md

@@ -33,7 +33,7 @@ hello-plugin/
 }
 ```
 
-patch 文件的形状与你一直在写的 `--patch` overlay 相同——一个 patch 条目的 YAML 数组——只是插件行按包名而不是相对源码路径引用这个包，这样 Node 的模块解析才能找到已安装的代码：
+patch 文件与一直在写的 `--patch` overlay 一样，是一个 patch 条目的 YAML 数组；区别是插件行按包名而不是相对源码路径引用这个包，这样 Node 的模块解析才能找到已安装的代码：
 
 ```yaml
 - insert:
@@ -41,7 +41,7 @@ patch 文件的形状与你一直在写的 `--patch` overlay 相同——一个
       name: dsh-hello-plugin
 ```
 
-没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。这正是「供插件包 import 的库」应有的形状，区别于「供用户启用的插件」。
+没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。如果一个库供插件包 import，而不是供用户启用，就使用这种包格式。
 
 ### profile manifest
 

docs/user/develop/practice/index.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/practice/index.md
-index.md: 6ae9fd152ca2e3b82bdb1ea9b3aa3d348ebfce66
-index.zh.md: 0056a81402761310fe5f0463b83762d98ed9745f
+index.md: 1eb33e17ab6c5d0a2b37ff97d5948dfbcba497ca
+index.zh.md: 31afa80407f81f571615b5ed68a9370775f5188f

docs/user/develop/practice/index.md

@@ -12,8 +12,8 @@ When a capability is general enough to need replaceable providers, such as Bash
 
 The Bash execution capability consists of:
 
-- **Service Definition** (`dsh-bash`) — defines the Cordis service and Bash request/result vocabulary
-- **Service provider** (`dsh-bash-local`) — supplies local command execution
+- **Service Definition** (`dsh-bash`) — defines the Cordis service and Bash request and result types
+- **Service provider** (`dsh-bash-local`) — executes commands on the local machine
 - **Consumer** (`dsh-tool-bash`) — exposes the capability as a model-callable tool
 
 ```
@@ -43,7 +43,7 @@ The Service Definition and tool remain unchanged while the provider changes.
 
 ### Evolve independently
 
-- The Service Definition changes rarely after its contract stabilizes.
+- The Service Definition changes rarely after callers depend on its contract.
 - Service providers can improve performance and security independently.
 - Consumers can change how they present the capability to the model.
 

docs/user/develop/practice/index.zh.md

@@ -12,8 +12,8 @@
 
 以 Bash 执行能力为例：
 
-- **Service Definition** (`dsh-bash`)：定义 Cordis 服务以及 Bash 请求／结果词汇
-- **Service provider** (`dsh-bash-local`)：提供本地命令执行
+- **Service Definition** (`dsh-bash`)：定义 Cordis 服务以及 Bash 请求和结果类型
+- **Service provider** (`dsh-bash-local`)：在本地计算机上执行命令
 - **Consumer** (`dsh-tool-bash`)：将该能力公开为模型可调用的工具
 
 ```
@@ -43,8 +43,8 @@
 
 ### 独立演进
 
-- Service Definition 的约定稳定后很少改动
-- Service provider 可以独立优化性能和安全性
+- 调用方开始依赖 Service Definition 的约定后，Service Definition 很少改动。
+- Service provider 可以独立优化性能和安全性。
 - Consumer 可以调整能力向模型呈现的方式。
 
 ### 依赖解耦