docs: align install and config guidance (#16)

ARCHITECTURE.md

@@ -1,13 +1,26 @@
 # Magpie (鹊) — architecture
 
-Magpie is the standalone IM connector for Bamboo (extraction of bamboo-server's
-in-process `connect/` module, per bamboo epic #477). Named after 鹊桥 — the
-magpie bridge that spans between worlds.
+Magpie is the standalone IM connector for
+[Bamboo](https://github.com/bigduu/Bamboo-agent) (extraction of bamboo-server's
+in-process `connect/` module, per
+[Bamboo #477](https://github.com/bigduu/Bamboo-agent/issues/477)). Named after
+鹊桥 — the magpie bridge that spans between worlds.
 
 It drives Bamboo agent sessions from IM platforms (Telegram, Feishu/Lark)
 exclusively over **Bamboo's public API** — never in-process internals — and
 ships as a Bamboo **service plugin** (bamboo-plugin `services` artifact kind,
-bamboo #479): bamboo-server installs, spawns, supervises, and restarts it.
+[Bamboo #479](https://github.com/bigduu/Bamboo-agent/issues/479)): bamboo-server
+installs, spawns, supervises, and restarts it.
+
+## Distribution boundary
+
+Each GitHub release contains a `magpie-plugin-v<version>.tar.gz` bundle for
+`bamboo plugin install` and separate `magpie-v<version>-<target>.*`
+standalone archives. Installing the plugin bundle delegates platform-binary
+selection and process lifecycle to Bamboo; running a standalone binary leaves
+both with the operator. The committed `plugin/plugin.json` is only the
+`0.0.0`/checksum template consumed by release CI, not an installable release
+manifest.
 
 ## Layout
 
@@ -36,7 +49,10 @@ plugin/
                        artifacts, sha256 filled by release CI)
 ```
 
-## Key mappings from the in-proc module (bamboo #480 gap analysis)
+## Key mappings from the in-proc module
+
+These are the seams shipped by
+[Bamboo #480](https://github.com/bigduu/Bamboo-agent/issues/480):
 
 | in-proc dependency | Magpie replacement |
 |---|---|
@@ -55,17 +71,16 @@ plugin/
 
 ```json
 {
-  "bamboo": { "base_url": "http://127.0.0.1:9560", "device_id": "…", "token": "…" },
+  "bamboo": { "base_url": "http://127.0.0.1:9562", "device_id": "…", "token": "…" },
   "platforms": [
     { "type": "telegram", "token": "…", "allow_from": ["…"] },
     { "type": "feishu", "app_id": "…", "app_secret": "…", "domain": "feishu", "allow_from": ["…"] }
   ]
 }
 ```
 
-v1 keeps secrets plaintext in the file (0600 perms enforced at load, warn
-otherwise) — bamboo's encrypted round-trip is coupled to bamboo's key store
-and does not extract; revisit post-v1.
+Magpie keeps secrets plaintext in the file. On Unix, group- or world-readable
+permissions produce a startup warning; Magpie does not rewrite the file mode.
 
 ## Invariants carried over from bamboo connect/
 
@@ -80,5 +95,4 @@ and does not extract; revisit post-v1.
 
 - WS resubscribe replays critical events + last budget only — a mid-run
   reconnect misses tokens (terminal event still lands; next edit repaints).
-- Two round trips per message (chat then execute) until/unless bamboo grows
-  a combined /turn endpoint.
+- Each message uses two requests: `/chat`, then `/execute`.

README.md

@@ -1,6 +1,6 @@
 # Magpie (鹊)
 
-Magpie is the standalone IM connector for [Bamboo](https://github.com/bigduu/bamboo). It
+Magpie is the standalone IM connector for [Bamboo](https://github.com/bigduu/Bamboo-agent). It
 drives Bamboo agent sessions from IM platforms (Telegram, Feishu/Lark) exclusively over
 Bamboo's public HTTP/WS API — never in-process internals — and ships as a Bamboo **service
 plugin**: bamboo-server installs, spawns, supervises, and restarts it.
@@ -9,17 +9,37 @@ Named after 鹊桥 (_què qiáo_, "magpie bridge") — the bridge of magpies tha
 River in the Qixi legend, connecting two separated worlds. Magpie spans the same gap between
 a chat platform and a running Bamboo agent.
 
-This repository is bamboo epic #477's extraction of bamboo-server's in-process `connect/`
-module into a standalone binary. See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full
-design, the Bamboo API surface Magpie depends on, and the layout of `src/`.
+This repository is [Bamboo #477](https://github.com/bigduu/Bamboo-agent/issues/477)'s
+extraction of bamboo-server's in-process `connect/` module into a standalone binary. See
+[`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full design, the Bamboo API surface Magpie
+depends on, and the layout of `src/`.
 
-## Quickstart
+## Install
 
-```bash
-cargo build --release
-./target/release/magpie --config ./magpie.json --check   # smoke-test auth + connectivity
-./target/release/magpie --config ./magpie.json            # run
-```
+[Magpie releases](https://github.com/bigduu/Magpie/releases/latest) publish two different
+artifacts:
+
+- `magpie-plugin-v<version>.tar.gz` is the Bamboo service-plugin bundle. With `bamboo serve`
+  running, replace `<version>` with the latest numeric release version (without the leading
+  `v`) and install it with:
+
+  ```bash
+  bamboo plugin install https://github.com/bigduu/Magpie/releases/download/v<version>/magpie-plugin-v<version>.tar.gz
+  ```
+
+  Bamboo verifies the signed release's `.sig` sidecar with the Magpie key in its default
+  trust store, so no trust-bypass flags are needed. Bamboo then selects the platform binary
+  and owns the service lifecycle. Put `magpie.json` at
+  `<Bamboo data dir>/plugin_service_config/magpie/config.json` (normally
+  `~/.bamboo/plugin_service_config/magpie/config.json`); Bamboo passes that path to Magpie.
+- `magpie-v<version>-<target>.*` contains a standalone binary. Use it when another process
+  manager owns Magpie, or build the same binary from source:
+
+  ```bash
+  cargo build --release
+  ./target/release/magpie --config ./magpie.json --check   # smoke-test auth + connectivity
+  ./target/release/magpie --config ./magpie.json            # run
+  ```
 
 `--check` calls `GET /api/v1/execute/defaults` against the configured Bamboo instance and
 prints the resolved model, then exits — use it to confirm the device token and base URL are
@@ -28,14 +48,14 @@ correct before wiring up a platform.
 ## Config
 
 Magpie reads `magpie.json` from (in priority order): the `--config` flag, then
-`$BAMBOO_PLUGIN_SERVICE_CONFIG`, then `./magpie.json`. On unix, a config file that is
+`$BAMBOO_PLUGIN_SERVICE_CONFIG`, then `./magpie.json`. On Unix, a config file that is
 group- or world-readable triggers a startup warning (it carries the bamboo device token and
-platform bot secrets in plaintext — v1 scope, see `ARCHITECTURE.md`).
+platform bot secrets in plaintext; see `ARCHITECTURE.md`).
 
 ```json
 {
   "bamboo": {
-    "base_url": "http://127.0.0.1:9560",
+    "base_url": "http://127.0.0.1:9562",
     "device_id": "bamboo_abc123",
     "token": "bd1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   },