From d9d6cc1065da09f8419d050f78195bfc8d2132ad Mon Sep 17 00:00:00 2001
From: Mathieu2301 <21021423+Mathieu2301@users.noreply.github.com>
Date: Sat, 14 Nov 2026 19:10:47 +0100
Subject: [PATCH] docs(guide): one pairing is enough; keep keys out of the
 conversation

Coordinators the agent runs may share its Home Key. The agent never asks
for a second pairing code per machine and never explains keys, tokens or
pairing internals to the owner. CLI 4.0.1.
---
 docs/agent-guide.md                | 11 ++++++++---
 packages/cli/assets/agent-guide.md | 11 ++++++++---
 packages/cli/package.json          |  2 +-
 packages/cli/src/version.ts        |  2 +-
 4 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/docs/agent-guide.md b/docs/agent-guide.md
index e9907ed..c918be8 100644
--- a/docs/agent-guide.md
+++ b/docs/agent-guide.md
@@ -598,9 +598,14 @@ Which key a command uses, highest precedence first:
 A context, or a known key, for a different home than `miakapp.yaml` names is
 refused before any request: a key can never publish into the wrong house.
 
-Prefer one key per agent or machine, so the owner can revoke one without
-breaking the others. A coordinator running on the owner's machine still reads
-its own key from its environment.
+One pairing is enough. The coordinators you run for this home (on a Raspberry
+Pi, a small PC…) may use the same Home Key as you: hand it to them yourself,
+through their environment, from `~/.miakapp/credentials.json`. Never ask the
+owner for another pairing code just to give a machine its own key.
+
+Keys, tokens, contexts and pairing internals are your business, not the
+owner's. Tell them what works ("the Pi is connected, your lamps answer"),
+never how it is wired, unless they ask.
 
 If you are about to write a secret into `miakapp.yaml` or any file in the
 repository so something works, stop: that is the failure this design exists to
diff --git a/packages/cli/assets/agent-guide.md b/packages/cli/assets/agent-guide.md
index e9907ed..c918be8 100644
--- a/packages/cli/assets/agent-guide.md
+++ b/packages/cli/assets/agent-guide.md
@@ -598,9 +598,14 @@ Which key a command uses, highest precedence first:
 A context, or a known key, for a different home than `miakapp.yaml` names is
 refused before any request: a key can never publish into the wrong house.
 
-Prefer one key per agent or machine, so the owner can revoke one without
-breaking the others. A coordinator running on the owner's machine still reads
-its own key from its environment.
+One pairing is enough. The coordinators you run for this home (on a Raspberry
+Pi, a small PC…) may use the same Home Key as you: hand it to them yourself,
+through their environment, from `~/.miakapp/credentials.json`. Never ask the
+owner for another pairing code just to give a machine its own key.
+
+Keys, tokens, contexts and pairing internals are your business, not the
+owner's. Tell them what works ("the Pi is connected, your lamps answer"),
+never how it is wired, unless they ask.
 
 If you are about to write a secret into `miakapp.yaml` or any file in the
 repository so something works, stop: that is the failure this design exists to
diff --git a/packages/cli/package.json b/packages/cli/package.json
index b9f246b..43003b1 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@miakapp/cli",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Agent-first Miakapp command line: check, build, publish, activate and roll back home interfaces",
   "type": "module",
   "engines": {
diff --git a/packages/cli/src/version.ts b/packages/cli/src/version.ts
index 49563fd..1d85bde 100644
--- a/packages/cli/src/version.ts
+++ b/packages/cli/src/version.ts
@@ -12,4 +12,4 @@
  */
 export const PACKAGE_NAME = '@miakapp/cli';
 
-export const CLI_VERSION = '4.0.0';
+export const CLI_VERSION = '4.0.1';