docs(peer): 更新多连接用户手册与交互型 Peer 推荐

10-prd/behavior/capabilities.md

@@ -49,3 +49,19 @@
 
 - related claim(s): organize information in one reusable info-base
 - non-goal: one runtime does not become the only valid participant in the shared system
+
+### Peer 本地连接管理（推荐）
+
+推荐 Peer 支持保存多个命名连接并切换当前连接，让用户在个人、工作或测试信息库之间切换时，
+不必反复覆盖地址和凭据。通常需要这一能力的是直接与用户交互的 Peer，例如 Web、桌面应用和
+浏览器扩展。固定部署、持续服务于一个信息库的进程可以只使用部署配置；`impl-py` 的服务器是
+这一例外，不要求提供连接列表或交互式切换。是否需要此能力取决于运行形态，而非实现语言；
+同一仓库交付的 CLI 仍可提供本机命名连接。
+
+提供多连接的界面应保存列表与当前选择，重新打开后恢复；保留已有单连接，并在切回已保存连接时
+复用其身份。连接名称用于本机辨认，不改变共享 Peer 名称。连接列表和凭据属于各自的本地配置，
+不因参与同一信息库而自动同步。不同入口仍使用各自支持的协议和凭据，不能互换地址。
+
+切换只改变后续交互的当前目标，不迁移或合并信息库，也不把已经绑定目标的待办或持续收入任务
+改投新库。前台内容须与当前连接一致，不能把旧连接的结果显示为新库内容。后台任务是否继续执行
+由对应能力的生命周期约定决定；切换不能被当作取消旧任务的操作。

website/.vitepress/config.mts

@@ -99,6 +99,7 @@ export default defineConfig({
               link: '/guide/daily-use',
               items: [
                 { text: 'Browse and Use Your Information', link: '/guide/daily-use' },
+                { text: 'Manage Connections', link: '/guide/connections' },
                 { text: 'CLI / Agent Connection', link: '/guide/connect-cli' },
                 { text: 'ChatGPT via MCP', link: '/guide/sinks/chatgpt' },
               ],

website/content/en/developer/architecture.md

@@ -66,6 +66,15 @@ Client-web demonstrates this topology: database operations use PostgREST, while
 capabilities may use native HTTP surfaces advertised by an online Peer. The durable boundary is the
 admitted protocol and capability contract, not a permanent frontend/backend hierarchy.
 
+Peers that people interact with directly should normally support local named connections and a
+current selection. Fixed service processes, including an `impl-py` server deployed for one
+info-base, can use a single deployment-configured connection. This recommendation follows the
+runtime's use rather than its language or repository: the CLI shipped by `impl-py` has a separate
+local connection list. Switching changes the foreground target without moving information or
+retargeting work already bound to an instance. The canonical
+[Peer connection guidance](https://github.com/InKCre/docs/blob/main/10-prd/behavior/capabilities.md#peer-本地连接管理推荐)
+owns the scope; [Manage Connections](/guide/connections) describes the user procedures.
+
 Read the canonical
 [unit topology](https://github.com/InKCre/docs/blob/main/20-product-tdd/unit-topology.md) and
 [state authority](https://github.com/InKCre/docs/blob/main/20-product-tdd/system-state-and-authority.md)

website/content/en/guide/connect-cli.md

@@ -60,4 +60,8 @@ The [CLI reference](https://github.com/InKCre/impl-py/blob/main/cli/README.md) o
 `--help` explains a command; `--schema` on input-taking commands shows the configuration accepted by
 your running instance.
 
+For another instance, save a different name instead of overwriting `personal`. See
+[Manage Connections](/guide/connections) for switching the default or selecting a connection for one
+command.
+
 Next: [Choose your first source](/guide/first-source).

website/content/en/guide/connect.md

@@ -19,28 +19,24 @@ the site.
 1. Retain your deployment's **PostgREST URL**, private **JWT secret**, and Core URL.
 2. Open [Web app Settings](https://app.inkcre.dev/settings). Only enter your secret into a Web app
    you trust: it grants full deployment authority, not a limited app session.
-3. Enter the PostgREST base URL in **PostgreSQL REST URL**, and the secret in **JWT Secret**. Do not
-   substitute the Core URL for PostgREST.
-4. Select **Save** in **Connection**. Language changes take effect separately, without saving the
-   connection again.
+3. Enter a **Connection name**, the PostgREST base URL in **PostgREST URL**, and the secret in **JWT
+   signing secret**. Do not substitute the Core URL for PostgREST.
+4. Select **Save and use connection** in **Connection**. Language changes take effect separately,
+   without saving the connection again.
 5. Open **Peers**. Confirm that **This browser** and Core appear with their application versions.
    Use **Refresh** after Core starts if its state has not updated yet.
 6. To use the public Extension Registry, select **Edit Config** on **This browser**, set
    `extension_registry_url` to `https://registry.inkcre.dev`, and save.
 
-![Client-web Settings showing connection and local preferences](/images/client-web/settings-overview.png)
-
-_Settings stores this browser's connection and language. Peer-specific configuration lives under
-Peers._
-
 ![Client-web Peers showing the current browser and Core with their versions and states](/images/client-web/peers-overview.png)
 
 _Peers shows the runtimes connected to this deployment. Edit a Peer when configuration belongs to
 that runtime._
 
-The connection belongs to this browser origin. To restore it in another browser, use **Export** and
-**Import** under **Backup and restore**. Keep the file private: it includes your JWT secret. This
-restores browser settings, not a backup of your collected information.
+The connection belongs to this browser origin. To add another instance, switch between saved
+connections, or move the complete list to another browser, follow
+[Manage Connections](/guide/connections). Keep exported settings private: they include the saved JWT
+secrets and do not back up collected information.
 
 **Checkpoint:** Settings saves successfully and you can open **Sources**. An empty list is normal
 for a new instance; a connection error is not an empty list.

website/content/en/guide/connections.md

@@ -0,0 +1,118 @@
+---
+title: Manage Connections
+description: Save named connections, switch instances, and keep each interface's target clear.
+---
+
+# Manage Connections
+
+Save a connection for each instance you use, such as Personal, Work, or Test. Each interface keeps
+its own list and current choice on your device. Reopening it restores that choice. Saving a
+connection in the Web app does not configure the Mac app, browser extension, or CLI.
+
+The procedures below describe versions with saved connections. If your interface has only a single
+address field, update it before following the multiple-connection steps. The Mac app is currently
+available as a development build.
+
+## Web app
+
+First-time setup is covered in [Connect the Web App](/guide/connect). To add another instance:
+
+1. Open **Settings**, then select **Add connection** under **Connection**.
+2. Enter a **Connection name**, **PostgREST URL**, and **JWT signing secret** for that instance.
+3. Select **Save and use connection**. The app checks the candidate before saving it as current.
+4. Open **Sources** or **Peers** and confirm that you are viewing the intended instance.
+
+To switch back, choose a saved name in **Current connection**. Switching uses its saved settings and
+Peer identity; you do not need to enter them again. To rename or update the current entry, edit its
+fields and select **Save and use connection**. Use **Add connection** when the target should remain
+a separate entry.
+
+A failed connection check or save keeps the previously saved selection. If background participation
+was stopped during the attempt, use **Retry** or save a working connection to resume it. A failed
+switch does not prove that the old background runtime is still running.
+
+Under **Backup and restore**, **Export** saves all connections, the current choice, and language.
+**Import** replaces the browser's list with the imported list and selects its current connection
+after validation. Older single-connection backups remain accepted. Export the current list before
+importing if you need to keep it. Protect backup files: they contain every saved JWT secret and
+restore browser configuration, not the contents of an instance.
+
+## Mac app
+
+Mac development builds require the matching
+[native Capture database support](https://github.com/InKCre/impl-py/pull/151). Use a database
+prepared for that build; a deployment without these database changes cannot accept its Capture
+submissions.
+
+1. Open **Settings** with `⌘,` and choose **连接** (Connection).
+2. Select **添加连接…** (Add connection). Enter a name, PostgreSQL host, port, database, runtime
+   role, and database password. The optional Web address is used to open shared information in a
+   browser.
+3. Keep TLS certificate verification enabled for remote databases, then select **保存** (Save).
+4. Choose the saved name in **当前连接** (Current connection) to switch later. The main window's
+   Peer page provides the same selector. Use **编辑连接…** (Edit connection) to update the current
+   entry.
+
+Mac uses native PostgreSQL and a dedicated admitted runtime role. Its password stays in macOS
+Keychain; a Web JWT secret is not a database password. Saving selects the connection and starts a
+background check, so a saved entry alone does not confirm connectivity. Inspect the Peer page for
+connection errors.
+
+Existing single-connection settings retain their identity and Keychain reference. Switching back
+reuses that identity. Changing the database or runtime role creates a new connection while keeping
+the previous entry available.
+
+Switching clears the foreground directory selection and loads the chosen instance. Already queued
+Capture submissions and existing local-directory monitors keep their original targets. They may
+continue writing there. To stop a directory's monitoring, switch to its original connection and
+pause or remove it separately.
+
+## Browser extension
+
+Open the extension's options page. Under **连接** (Connection), select **添加连接** (Add
+connection), enter **连接名称** (Connection name) and **API 地址** (API address), then select
+**保存并使用连接** (Save and use). Choose a saved name in **当前连接** (Current connection) to
+switch. Editing the fields and saving updates the current entry. Other open extension pages observe
+the saved choice.
+
+These entries store the extension's existing compatible HTTP(S) API addresses. Use the endpoint
+supported by that extension version; PostgREST and native PostgreSQL addresses are not substitutes.
+Saving an address does not check that the remote API is available or change the extension's request
+protocol. An existing single API address is retained as the first named entry.
+
+## CLI and trusted Agents
+
+The CLI already supports named connections to the Core REST API. Follow
+[Connect the CLI](/guide/connect-cli) for installation and initial setup. To add Work alongside
+Personal, create a private `work-connection.json` with Work's Core `base_url` and `jwt_secret`, then
+run:
+
+```sh
+inkcre-cli connection set work --input work-connection.json
+inkcre-cli connection list
+inkcre-cli connection use work
+inkcre-cli connection check
+```
+
+`connection use` changes the saved default. To use Personal for just one command without changing
+that default:
+
+```sh
+inkcre-cli --connection personal connection check
+```
+
+Remove the temporary input file when finished and protect the saved
+`~/.inkcre/cli/connections.json`, which contains credentials. Connection selection configures the
+CLI only; it does not retarget the server it contacts.
+
+## Keep targets distinct
+
+Switching does not move or merge information between instances, cancel work already submitted, or
+retarget work with a saved destination. Check the current name and address before submitting new
+information. Each interface uses its own protocol and credentials even when it reaches the same
+information.
+
+Saved connections are recommended for Peers that people interact with directly. A fixed service
+process, such as the `impl-py` server deployed for one instance, normally uses its deployment
+configuration and does not need an interactive connection switcher. Its CLI is a separate interface
+with its own local connection list.