docs: document pi_embedded canary path and update state

README.md

@@ -20,6 +20,7 @@ Self-hosted personal AI assistant with Telegram and Terminal interfaces.
 - **Capture Tools**: `screen.capture` and `camera.capture` tools for host capture workflows
 - **Session Transfer**: Move conversations between frontends
 - **CLI**: Full command-line interface (`flynn start`, `send`, `doctor`, `completion`, etc.)
+- **Optional Pi Embedded Backend**: Canary-only in-process Pi runtime path (`pi_embedded`) with native fallback
 - **Shell Completion**: Auto-generated completions for bash, zsh, and fish with `--install` flag
 - **Cron Scheduling**: Automated messages on cron schedules with output routing
 - **Daily Briefing Automation**: Optional built-in morning briefing preset (calendar + inbox + tasks summary prompt)
@@ -351,15 +352,22 @@ backends:
   claude_code: { enabled: false, path: /usr/local/bin/claude, args: [], timeout_ms: 120000 }
   opencode: { enabled: false, path: /usr/local/bin/opencode, args: [], timeout_ms: 120000 }
   gemini: { enabled: false, path: /usr/local/bin/gemini, args: [], timeout_ms: 120000 }
+  pi_embedded:
+    enabled: false
+    timeout_ms: 120000
+    no_tools_mode: true
+    model: openclaw-default
+    system_prompt_mode: hybrid   # flynn | pi_default | hybrid
+    module: "@badlogic/pi-agent-core"  # optional module override
 ```
 
-Each external backend also supports `retries` and `retry_delay_ms` for transient CLI failures.
+`pi_embedded` is intended for canary migration cohorts. In spike mode (`no_tools_mode: true`), Flynn keeps tool-oriented turns on native and only routes plain-text turns to Pi.
 
 When `args` is non-empty:
 - use `{prompt}` in an argument to inject the full generated prompt directly into argv.
-- if `{prompt}` is not present, Flynn writes the prompt to stdin.
+- if `{prompt}` is not present, Flynn appends backend-specific prompt args.
 
-If multiple external backends are enabled, set `backends.default` to choose explicitly. If omitted, Flynn selects by priority: `codex` -> `claude_code` -> `opencode` -> `gemini`.
+If multiple external backends are enabled, set `backends.default` to choose explicitly. If omitted, Flynn selects by priority: `codex` -> `claude_code` -> `opencode` -> `gemini` -> `pi_embedded`.
 
 You can also route specific named agents to a backend:
 
@@ -367,7 +375,10 @@ You can also route specific named agents to a backend:
 agent_configs:
   coder:
     model_tier: complex
-    backend: codex   # native | codex | claude_code | opencode | gemini
+    backend: codex   # native | codex | claude_code | opencode | gemini | pi_embedded
+  pi_canary:
+    model_tier: default
+    backend: pi_embedded
 ```
 
 ### Native Audio Support