bots-garden/mini-me · 6e3ed53

modified INSTALL.MACOS.md +1 -1 Viewed

@@ -2,7 +2,7 @@
2	2
3	3	```bash
4	4	# download the binary release in https://rickub.com/bots-garden/mini-me/releases
5		-VERSION=0.2.6
	5	+VERSION=0.3.0
6	6	curl -fsSLO "https://rickub.com/bots-garden/mini-me/releases/download/v${VERSION}/mm-${VERSION}-darwin-arm64"
7	7	chmod +x ./mm-${VERSION}-darwin-arm64
8	8	xattr -cr ./mm-${VERSION}-darwin-arm64

  ```bash
  # download the binary release in https://rickub.com/bots-garden/mini-me/releases
--VERSION=0.2.6
++VERSION=0.3.0
  curl -fsSLO "https://rickub.com/bots-garden/mini-me/releases/download/v${VERSION}/mm-${VERSION}-darwin-arm64"
  chmod +x ./mm-${VERSION}-darwin-arm64
  xattr -cr ./mm-${VERSION}-darwin-arm64

added LICENSE +23 -0 Viewed

new file mode 100644
@@ -0,0 +1,23 @@
	1	+MIT License
	2	+
	3	+mini-me — https://rickub.com/bots-garden/mini-me
	4	+
	5	+Copyright (c) 2026 k33g (Philippe Charrière) and the bots-garden organization
	6	+
	7	+Permission is hereby granted, free of charge, to any person obtaining a copy
	8	+of this software and associated documentation files (the "Software"), to deal
	9	+in the Software without restriction, including without limitation the rights
	10	+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
	11	+copies of the Software, and to permit persons to whom the Software is
	12	+furnished to do so, subject to the following conditions:
	13	+
	14	+The above copyright notice and this permission notice shall be included in all
	15	+copies or substantial portions of the Software.
	16	+
	17	+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	18	+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	19	+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
	20	+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	21	+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
	22	+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
	23	+SOFTWARE.

++MIT License
++
++mini-me — https://rickub.com/bots-garden/mini-me
++
++Copyright (c) 2026 k33g (Philippe Charrière) and the bots-garden organization
++
++Permission is hereby granted, free of charge, to any person obtaining a copy
++of this software and associated documentation files (the "Software"), to deal
++in the Software without restriction, including without limitation the rights
++to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
++copies of the Software, and to permit persons to whom the Software is
++furnished to do so, subject to the following conditions:
++
++The above copyright notice and this permission notice shall be included in all
++copies or substantial portions of the Software.
++
++THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
++IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
++FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
++AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
++LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
++OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
++SOFTWARE.

modified README.md +42 -4 Viewed

@@ -8,7 +8,7 @@
8	8
9	9	Mini Me started as the preparation of a Tools-in-Action talk for Devoxx Belgium 2026, where I explain how an agent loop works with a single tool: `bash`. The model asks for a command, the agent runs it, the output goes back to the model, and so on until the model answers.
10	10
11		-From there it grew into the coding agent I wanted for local models (Docker Model Runner, llama.cpp): small enough to be read in an afternoon, and careful about what a small model does wrong:
	11	+From there it grew into the coding agent I wanted for local models (Docker Model Runner, llama.cpp, llmman, Ollama): small enough to be read in an afternoon, and careful about what a small model does wrong:
12	12
13	13	- hallucinations — the agent shows the real output of every command before the model comments on it, and the prompt forbids stating anything a command did not return;
14	14	- silent failures — a failing command, a refused edit or a rejected permission goes back to the model as text, so it reads why and tries something else;
@@ -20,7 +20,7 @@ What makes Mini Me a bit special is that it was designed from the start to be us
20	20
21	21	## Install
22	22
23		-You need Go 1.26+ and a model server that can emit tool calls: Docker Model Runner (default) or Llamacpp.
	23	+You need Go 1.26+ and a model server that can emit tool calls, through its OpenAI-compatible API: Docker Model Runner (`provider: dmr`, the default), llama.cpp's `llama-server` (`llamacpp`), [llmman](https://github.com/llmmanorg/llmman) (`llmman`) or Ollama (`ollama`).
24	24
25	25	```bash
26	26	git clone https://git.rickub.com/bots-garden/mini-me.git
@@ -34,7 +34,17 @@ mm --about # what it is, in one screen
34	34
35	35	Or download a binary from the [releases page](https://rickub.com/bots-garden/mini-me/releases) and put it on your `PATH`.
36	36
37		-Then pick a configuration file. Two are shipped: `agent.dmr.yaml` for Docker Model Runner and `agent.llamacpp.yaml` for llama.cpp. Copy one to `agent.yaml` in your project and adjust the `model:` and `system:` keys to taste.
	37	+Then pick a configuration file. Copy one to `agent.yaml` in your project and adjust the `model:` and `system:` keys to taste:
	38	+
	39	+\| File \| For \|
	40	+\|---\|---\|
	41	+\| `agent.dmr.yaml` \| Docker Model Runner \|
	42	+\| `agent.llamacpp.yaml` \| llama.cpp (`llama-server`) \|
	43	+\| `agent.llmman.yaml` \| llmman \|
	44	+\| `agent.lsp.yaml` \| the same agent with a language server behind an `lsp` tool \|
	45	+\| `agent.mcp-example.yaml` \| the same agent with MCP servers \|
	46	+
	47	+For Ollama, see [Run mini-me on Ollama](docs/en/how-to/run-with-ollama.md) and `demos/ollama/`.
38	48
39	49	## Use
40	50
@@ -85,7 +95,7 @@ Speaks the Agent Client Protocol on stdin/stdout. You never run this one by hand
85	95
86	96	`AGENT_CONFIG` must be an absolute path: Zed starts `mm` in the project directory, and a relative path would not be found. `"type": "custom"` is required.
87	97
88		-3. Open the Agent panel, pick mini-me, and talk to it. Every `bash`, `read_file`, `write_file` and `edit_file` call shows up as a tool call, and Zed asks you to allow it before it runs. File changes appear as real diffs.
	98	+3. Open the Agent panel, pick mini-me, and talk to it. Every `bash`, `read_file`, `write_file` and `edit_file` call shows up as a tool call, and file changes appear as real diffs. With `yolo: false` in the YAML, Zed asks you to allow each call before it runs; the shipped files say `yolo: true`, and the calls run unasked.
89	99	4. Handy things: Escape cancels a turn; `/new` and `/compact` are in the slash-command menu; `@file` attaches a file for the model to read; with `sessions.enabled: true` in the YAML, Reload Agent brings the whole conversation back.
90	100	5. When something looks wrong, open `dev: open acp logs`: the banner, warnings and the agent's `[acp] …` trail go there.
91	101
@@ -95,9 +105,37 @@ Speaks the Agent Client Protocol on stdin/stdout. You never run this one by hand
95	105
96	106	Anything that speaks ACP can host `mm -acp` the same way: JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm…), Neovim (CodeCompanion, agentic.nvim, avante.nvim), Emacs (agent-shell), Visual Studio Code through third-party ACP extensions, Sublime Text and Qt Creator through their ACP plugins. The registration details differ; the agent side does not.
97	107
	108	+## More features
	109	+
	110	+- One prompt and exit: `mm -p "…"` — for scripts. See [Run a single prompt](docs/en/how-to/run-a-single-prompt.md).
	111	+- Other agents: list other mm agents under `mmConfigs`; you ask them with `/ask-<name>`, your agent calls them itself with its `ask_agent` tool, a script with `mm --ask <name>`. See [Let your agent call other agents](docs/en/how-to/let-the-agent-call-other-agents.md).
	112	+- Project instructions: an `AGENTS.md` in the project directory is added to the system prompt of every conversation. See [Give the agent your project's instructions](docs/en/how-to/give-project-instructions.md).
	113	+- Answers as JSON: declare the shape of the answer as Go types under `structuredOutput`, and `mm -p "…" \| jq` works. See [Get answers as JSON](docs/en/how-to/get-json-answers.md).
	114	+- MCP servers: their tools, wrapped as mm tools. See the [MCP tutorial](docs/en/tutorials/mcp-getting-started.md).
	115	+- Sessions: with `sessions.enabled: true`, `/sessions` lists the conversations of a project and `/resume` continues one. See [Keep sessions and resume them](docs/en/how-to/keep-sessions.md).
	116	+- Trace: `AGENT_TRACE=true mm …` writes every request to the model and every response to `.mm/traces/`. See [See the JSON sent to the model](docs/en/how-to/inspect-model-traffic.md).
	117	+- Docker Sandboxes: the sandbox kit lives in its own repository, [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit); `sbx/` explains how to use it (`sbx run …`), with two mixins (`go-toolchain`, `cli-tools`) and ready-made configurations — see `sbx/README.md` and [Run mini-me in a Docker Sandbox](docs/en/how-to/run-in-a-docker-sandbox.md).
	118	+
	119	+## Demos
	120	+
	121	+The `demos/` directory holds ready-made set-ups (most with a README explaining how to run them):
	122	+
	123	+\| Directory \| What it shows \|
	124	+\|---\|---\|
	125	+\| `demos/dmr/` \| mm on Docker Model Runner, with skills, LSP and MCP configurations \|
	126	+\| `demos/llmman/` \| mm on llmman, and an agent that asks other agents \|
	127	+\| `demos/ollama/` \| mm on Ollama \|
	128	+\| `demos/structured-output/` \| agents that answer in JSON, and a coordinator using them \|
	129	+\| `demos/agents-md-file/` \| an agent following a project's `AGENTS.md` \|
	130	+\| `demos/mini-mes/` \| small teams of agents (`riker` coordinating a specifier and a coder, `gopher` a Go specialist) \|
	131	+
98	132	## Learn more
99	133
100	134	- [Documentation](docs/README.md) — tutorials, how-to guides, reference and explanations, in English and French.
101	135	- The `skills/` directory: Markdown procedures the agent can load with its `read_skill` tool.
102	136	- `agent.lsp.yaml`: the same agent with a language server behind an `lsp` tool (definition, references, hover, symbols, diagnostics, rename) — see [Navigate and refactor code with a language server](docs/en/how-to/navigate-code-with-lsp.md).
103	137	- `fetchContentTool: true` in `agent.dmr.yaml`: the built-in `fetch_content` tool, which fetches a web page as Markdown (honouring its `robots.txt`) and can save it to a file without showing it — see [Fetch a web page as Markdown](docs/en/how-to/fetch-a-web-page.md).
	138	+
	139	+## License
	140	+
	141	+MIT — see [LICENSE](LICENSE).

  Mini Me started as the preparation of a *Tools-in-Action* talk for **Devoxx Belgium 2026**, where I explain how an **agent loop** works with a single tool: `bash`. The model asks for a command, the agent runs it, the output goes back to the model, and so on until the model answers.
--From there it grew into the coding agent I wanted for local models (Docker Model Runner, llama.cpp): small enough to be read in an afternoon, and careful about what a small model does wrong:
++From there it grew into the coding agent I wanted for local models (Docker Model Runner, llama.cpp, llmman, Ollama): small enough to be read in an afternoon, and careful about what a small model does wrong:
  - **hallucinations** — the agent shows the real output of every command before the model comments on it, and the prompt forbids stating anything a command did not return;
  - **silent failures** — a failing command, a refused edit or a rejected permission goes back to the model as text, so it reads why and tries something else;
  ## Install
--You need Go 1.26+ and a model server that can emit tool calls: Docker Model Runner (default) or Llamacpp.
++You need Go 1.26+ and a model server that can emit tool calls, through its OpenAI-compatible API: Docker Model Runner (`provider: dmr`, the default), llama.cpp's `llama-server` (`llamacpp`), [llmman](https://github.com/llmmanorg/llmman) (`llmman`) or Ollama (`ollama`).
  ```bash
  git clone https://git.rickub.com/bots-garden/mini-me.git
  Or download a binary from the [releases page](https://rickub.com/bots-garden/mini-me/releases) and put it on your `PATH`.
--Then pick a configuration file. Two are shipped: `agent.dmr.yaml` for Docker Model Runner and `agent.llamacpp.yaml` for llama.cpp. Copy one to `agent.yaml` in your project and adjust the `model:` and `system:` keys to taste.
++Then pick a configuration file. Copy one to `agent.yaml` in your project and adjust the `model:` and `system:` keys to taste:
++
++| File | For |
++|---|---|
++| `agent.dmr.yaml` | Docker Model Runner |
++| `agent.llamacpp.yaml` | llama.cpp (`llama-server`) |
++| `agent.llmman.yaml` | llmman |
++| `agent.lsp.yaml` | the same agent with a language server behind an `lsp` tool |
++| `agent.mcp-example.yaml` | the same agent with MCP servers |
++
++For Ollama, see [Run mini-me on Ollama](docs/en/how-to/run-with-ollama.md) and `demos/ollama/`.
  ## Use
     `AGENT_CONFIG` must be an **absolute** path: Zed starts `mm` in the project directory, and a relative path would not be found. `"type": "custom"` is required.
--3. Open the Agent panel, pick **mini-me**, and talk to it. Every `bash`, `read_file`, `write_file` and `edit_file` call shows up as a tool call, and Zed asks you to allow it before it runs. File changes appear as real diffs.
++3. Open the Agent panel, pick **mini-me**, and talk to it. Every `bash`, `read_file`, `write_file` and `edit_file` call shows up as a tool call, and file changes appear as real diffs. With `yolo: false` in the YAML, Zed asks you to allow each call before it runs; the shipped files say `yolo: true`, and the calls run unasked.
 . Handy things: **Escape** cancels a turn; `/new` and `/compact` are in the slash-command menu; `@file` attaches a file for the model to read; with `sessions.enabled: true` in the YAML, **Reload Agent** brings the whole conversation back.
 . When something looks wrong, open `dev: open acp logs`: the banner, warnings and the agent's `[acp] …` trail go there.
  Anything that speaks ACP can host `mm -acp` the same way: **JetBrains IDEs** (IntelliJ IDEA, PyCharm, WebStorm…), **Neovim** (CodeCompanion, agentic.nvim, avante.nvim), **Emacs** (agent-shell), **Visual Studio Code** through third-party ACP extensions, Sublime Text and Qt Creator through their ACP plugins. The registration details differ; the agent side does not.
++## More features
++
++- **One prompt and exit**: `mm -p "…"` — for scripts. See [Run a single prompt](docs/en/how-to/run-a-single-prompt.md).
++- **Other agents**: list other mm agents under `mmConfigs`; you ask them with `/ask-<name>`, your agent calls them itself with its `ask_agent` tool, a script with `mm --ask <name>`. See [Let your agent call other agents](docs/en/how-to/let-the-agent-call-other-agents.md).
++- **Project instructions**: an `AGENTS.md` in the project directory is added to the system prompt of every conversation. See [Give the agent your project's instructions](docs/en/how-to/give-project-instructions.md).
++- **Answers as JSON**: declare the shape of the answer as Go types under `structuredOutput`, and `mm -p "…" | jq` works. See [Get answers as JSON](docs/en/how-to/get-json-answers.md).
++- **MCP servers**: their tools, wrapped as mm tools. See the [MCP tutorial](docs/en/tutorials/mcp-getting-started.md).
++- **Sessions**: with `sessions.enabled: true`, `/sessions` lists the conversations of a project and `/resume` continues one. See [Keep sessions and resume them](docs/en/how-to/keep-sessions.md).
++- **Trace**: `AGENT_TRACE=true mm …` writes every request to the model and every response to `.mm/traces/`. See [See the JSON sent to the model](docs/en/how-to/inspect-model-traffic.md).
++- **Docker Sandboxes**: the sandbox kit lives in its own repository, [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit); `sbx/` explains how to use it (`sbx run …`), with two mixins (`go-toolchain`, `cli-tools`) and ready-made configurations — see `sbx/README.md` and [Run mini-me in a Docker Sandbox](docs/en/how-to/run-in-a-docker-sandbox.md).
++
++## Demos
++
++The `demos/` directory holds ready-made set-ups (most with a README explaining how to run them):
++
++| Directory | What it shows |
++|---|---|
++| `demos/dmr/` | mm on Docker Model Runner, with skills, LSP and MCP configurations |
++| `demos/llmman/` | mm on llmman, and an agent that asks other agents |
++| `demos/ollama/` | mm on Ollama |
++| `demos/structured-output/` | agents that answer in JSON, and a coordinator using them |
++| `demos/agents-md-file/` | an agent following a project's `AGENTS.md` |
++| `demos/mini-mes/` | small teams of agents (`riker` coordinating a specifier and a coder, `gopher` a Go specialist) |
++
  ## Learn more
  - [Documentation](docs/README.md) — tutorials, how-to guides, reference and explanations, in English and French.
  - The `skills/` directory: Markdown procedures the agent can load with its `read_skill` tool.
  - `agent.lsp.yaml`: the same agent with a language server behind an `lsp` tool (definition, references, hover, symbols, diagnostics, rename) — see [Navigate and refactor code with a language server](docs/en/how-to/navigate-code-with-lsp.md).
  - `fetchContentTool: true` in `agent.dmr.yaml`: the built-in `fetch_content` tool, which fetches a web page as Markdown (honouring its `robots.txt`) and can save it to a file without showing it — see [Fetch a web page as Markdown](docs/en/how-to/fetch-a-web-page.md).
++
++## License
++
++MIT — see [LICENSE](LICENSE).

deleted demo-dmr/MCP_SBX_FIX.md +0 -95 Viewed

deleted file mode 100644
@@ -1,95 +0,0 @@
1		-# Fix MCP Gateway Token Issue for Mini-Me in Docker Sandbox
2		-
3		-## Problem Summary
4		-
5		-When running Mini-Me (`mm`) inside a Docker Sandbox with `sbx`, the following warning appears:
6		-```
7		-[warning: mcp server sbx-gateway: discovery failed: missing token for env var MCP_GATEWAY_TOKEN]
8		-```
9		-
10		-## Root Cause
11		-
12		-Misalignment between sbx and mini-me:
13		-
14		-- sbx injects: `MCP_GATEWAY_URL` and `MCP_SENTINEL_TOKEN_NAME` environment variables
15		-- mini-me expects: `MCP_GATEWAY_URL` and `MCP_GATEWAY_TOKEN` environment variables
16		-
17		-This is confirmed by Docker Agent's code in `sandboxes/sandboxlib/agentkits/agents/claude/spec.yaml`:
18		-```yaml
19		-# MCP_GATEWAY_URL / MCP_SENTINEL_TOKEN_NAME are injected by sandboxd as
20		-# container env at create time (gateway-first lifecycle)
21		-```
22		-
23		-## Applied Fix
24		-
25		-### 1. Code Fix in `main.go` (line 346)
26		-```diff
27		-- TokenEnv: "MCP_GATEWAY_TOKEN", // sbx may inject this, or substitute via header
28		-+ TokenEnv: "MCP_SENTINEL_TOKEN_NAME", // sbx injects this, not MCP_GATEWAY_TOKEN
29		-```
30		-
31		-### 2. Configuration in `agent.dmr.sbx.yaml`
32		-```yaml
33		-mcp:
34		- enabled: true
35		- permissions: ask
36		- discoveryTimeout: 10s
37		- servers: [] # Let sbx-gateway handle all MCP servers
38		-```
39		-
40		-## Why It Still Fails
41		-
42		-The binary in the Docker image (`k33g/mm-sandbox:0.1.4`) was built before the fix (timestamp: Sep 23 18:02, while fix was applied at 19:23).
43		-
44		-Docker's layer caching prevented the Go binary from being recompiled with the corrected `TokenEnv` value.
45		-
46		-## Verification
47		-
48		-```bash
49		-# Check binary timestamp in the image
50		- docker run --rm k33g/mm-sandbox:0.1.4 sh -c "ls -l /usr/local/bin/mm"
51		-# If date < 19:23: the fix is NOT in the binary
52		-
53		-# Check if MCP_SENTINEL_TOKEN_NAME is in the binary
54		- docker run --rm k33g/mm-sandbox:0.1.4 sh -c "strings /usr/local/bin/mm \| grep SENTINEL"
55		-# Should show: MCP_SENTINEL_TOKEN_NAME
56		-```
57		-
58		-## Solution
59		-
60		-Rebuild the Docker image with cache disabled:
61		-```bash
62		-cd /Users/k33g/kDrive/Rickub/bots-garden/mini-me
63		-
64		-# Clean everything
65		-docker rmi k33g/mm-sandbox:0.1.4
66		-docker builder prune -af
67		-
68		-# Force full rebuild (no cache for Go compilation or Docker layers)
69		-docker build --no-cache --pull -f docker-sbx/template/Dockerfile -t k33g/mm-sandbox:0.1.4 .
70		-
71		-# Resync kits
72		-./docker-sbx/sync-kits.sh k33g 0.1.4
73		-
74		-# Launch with local image
75		-sbx run --pull never ./docker-sbx/kits/mm-tui . -- agent.dmr.sbx.yaml
76		-```
77		-
78		-## Alternative: Use Claude Code Directly
79		-
80		-Claude Code in Docker Sandbox uses the correct variable name (`MCP_SENTINEL_TOKEN_NAME`) as seen in:
81		-`docker-sbx/sandboxlib/agentkits/agents/claude/spec.yaml`
82		-
83		-Reference from Docker Agent code:
84		-```yaml
85		-claude mcp add mcp-gateway "$MCP_GATEWAY_URL" \
86		- --transport http \
87		- --scope user \
88		- --header "Authorization: Bearer $MCP_SENTINEL_TOKEN_NAME"
89		-```
90		-
91		-## Status
92		-
93		-- ✅ Fix applied to mini-me source code
94		-- ⚠️ Requires clean rebuild of Docker image
95		-- 📝 This document created for reference

--# Fix MCP Gateway Token Issue for Mini-Me in Docker Sandbox
--
--## Problem Summary
--
--When running Mini-Me (`mm`) inside a Docker Sandbox with `sbx`, the following warning appears:
--```
--[warning: mcp server sbx-gateway: discovery failed: missing token for env var MCP_GATEWAY_TOKEN]
--```
--
--## Root Cause
--
--**Misalignment between sbx and mini-me:**
--
--- **sbx injects**: `MCP_GATEWAY_URL` and `MCP_SENTINEL_TOKEN_NAME` environment variables
--- **mini-me expects**: `MCP_GATEWAY_URL` and `MCP_GATEWAY_TOKEN` environment variables
--
--This is confirmed by Docker Agent's code in `sandboxes/sandboxlib/agentkits/agents/claude/spec.yaml`:
--```yaml
--# MCP_GATEWAY_URL / MCP_SENTINEL_TOKEN_NAME are injected by sandboxd as
--# container env at create time (gateway-first lifecycle)
--```
--
--## Applied Fix
--
--### 1. Code Fix in `main.go` (line 346)
--```diff
--- TokenEnv: "MCP_GATEWAY_TOKEN", // sbx may inject this, or substitute via header
--+ TokenEnv: "MCP_SENTINEL_TOKEN_NAME", // sbx injects this, not MCP_GATEWAY_TOKEN
--```
--
--### 2. Configuration in `agent.dmr.sbx.yaml`
--```yaml
--mcp:
--  enabled: true
--  permissions: ask
--  discoveryTimeout: 10s
--  servers: []  # Let sbx-gateway handle all MCP servers
--```
--
--## Why It Still Fails
--
--The binary in the Docker image (`k33g/mm-sandbox:0.1.4`) was **built before the fix** (timestamp: Sep 23 18:02, while fix was applied at 19:23).
--
--Docker's layer caching prevented the Go binary from being recompiled with the corrected `TokenEnv` value.
--
--## Verification
--
--```bash
--# Check binary timestamp in the image
-- docker run --rm k33g/mm-sandbox:0.1.4 sh -c "ls -l /usr/local/bin/mm"
--# If date < 19:23: the fix is NOT in the binary
--
--# Check if MCP_SENTINEL_TOKEN_NAME is in the binary
-- docker run --rm k33g/mm-sandbox:0.1.4 sh -c "strings /usr/local/bin/mm | grep SENTINEL"
--# Should show: MCP_SENTINEL_TOKEN_NAME
--```
--
--## Solution
--
--Rebuild the Docker image with cache disabled:
--```bash
--cd /Users/k33g/kDrive/Rickub/bots-garden/mini-me
--
--# Clean everything
--docker rmi k33g/mm-sandbox:0.1.4
--docker builder prune -af
--
--# Force full rebuild (no cache for Go compilation or Docker layers)
--docker build --no-cache --pull -f docker-sbx/template/Dockerfile -t k33g/mm-sandbox:0.1.4 .
--
--# Resync kits
--./docker-sbx/sync-kits.sh k33g 0.1.4
--
--# Launch with local image
--sbx run --pull never ./docker-sbx/kits/mm-tui . -- agent.dmr.sbx.yaml
--```
--
--## Alternative: Use Claude Code Directly
--
--Claude Code in Docker Sandbox uses the correct variable name (`MCP_SENTINEL_TOKEN_NAME`) as seen in:
--`docker-sbx/sandboxlib/agentkits/agents/claude/spec.yaml`
--
--Reference from Docker Agent code:
--```yaml
--claude mcp add mcp-gateway "$MCP_GATEWAY_URL" \
--  --transport http \
--  --scope user \
--  --header "Authorization: Bearer $MCP_SENTINEL_TOKEN_NAME"
--```
--
--## Status
--
--- ✅ Fix applied to mini-me source code
--- ⚠️ Requires clean rebuild of Docker image
--- 📝 This document created for reference

deleted demo-dmr/MCP_SERVERS_GUIDE.md +0 -630 Viewed

deleted file mode 100644
@@ -1,630 +0,0 @@
1		-# Guide: Utiliser les Serveurs MCP avec mini-me
2		-
3		-Ce document explique comment configurer et utiliser des serveurs MCP avec mini-me :
4		-- Context7 MCP - Documentation et contexte de code (nécessite une clé API)
5		-- GitHub MCP - Accès à GitHub (nécessite un Personal Access Token)
6		-- Wikipedia MCP - Accès complet à Wikipedia (gratuit, aucune authentification requise)
7		-- DuckDuckGo MCP (HasData) - Recherche web via HasData (1,000 crédits gratuits/mois) - actuellement désactivé dans la config par défaut
8		-
9		----
10		-
11		-## 🚀 Configuration Rapide
12		-
13		-### 1. Utiliser le fichier de configuration fourni
14		-
15		-Un fichier de configuration prêt à l'emploi est fourni : `demo/agent.dmr.mcp.yaml`
16		-
17		-Il contient déjà la configuration pour les deux serveurs MCP.
18		-
19		-### 2. Exporter vos clés API
20		-
21		-#### Pour Context7
22		-```bash
23		-export CONTEXT7_API_KEY="votre-clé-api-context7"
24		-```
25		-
26		-> ✅ Où obtenir une clé Context7 ?
27		-> Inscrivez-vous sur [https://context7.com](https://context7.com) pour obtenir une clé API gratuite.
28		-
29		-#### Pour GitHub
30		-```bash
31		-export GITHUB_PERSONAL_ACCESS_TOKEN="votre-token-github"
32		-```
33		-
34		-> ✅ Où obtenir un PAT GitHub ?
35		-> 1. Allez sur [https://github.com/settings/tokens](https://github.com/settings/tokens)
36		-> 2. Cliquez sur "Generate new token" (classic)
37		-> 3. Donnez un nom à votre token
38		-> 4. Sélectionnez les scopes nécessaires (ex: `repo` pour l'accès aux dépôts)
39		-> 5. Générez le token et copiez-le
40		-
41		-> ⚠️ Scopes recommandés :
42		-> - `repo` : Accès complet aux dépôts (lecture/écriture)
43		-> - `read:org` : Lire les informations d'organisation
44		-> - `user` : Accès au profil utilisateur
45		->
46		-> Pour une utilisation en lecture seule, `repo` (lecture) suffit.
47		-
48		-#### Pour Wikipedia
49		-Aucune clé n'est nécessaire ! ✅
50		-
51		-#### Pour DuckDuckGo (HasData)
52		-```bash
53		-export HASDATA_API_KEY="votre-clé-api-hasdata"
54		-```
55		-
56		-> ✅ Où obtenir une clé HasData ?
57		-> Inscrivez-vous sur [https://app.hasdata.com](https://app.hasdata.com) pour obtenir une clé API gratuite.
58		-> Gratuit : 1,000 crédits/mois (100 recherches)
59		-
60		-> ⚠️ Note importante : Le serveur DuckDuckGo utilisé est hébergé par HasData, pas par DuckDuckGo directement.
61		-
62		-### 3. Lancer mini-me avec la configuration MCP
63		-
64		-```bash
65		-# Depuis le répertoire mini-me
66		-./mm -config demo/agent.dmr.mcp.yaml
67		-```
68		-
69		----
70		-
71		-## 📝 Configuration Détailée
72		-
73		-### Structure de la Configuration MCP
74		-
75		-```yaml
76		-mcp:
77		- enabled: true # Active le support MCP
78		- permissions: ask # Demander avant d'exécuter (recommandé)
79		- discoveryTimeout: 10s # Timeout pour la découverte des outils
80		-
81		- servers:
82		- - name: context7
83		- transport: http
84		- url: https://mcp.context7.com/mcp
85		- auth:
86		- type: bearer
87		- tokenEnv: CONTEXT7_API_KEY
88		- headers:
89		- Accept: "application/json, text/event-stream"
90		-
91		- - name: github
92		- transport: http
93		- url: https://api.githubcopilot.com/mcp/
94		- auth:
95		- type: bearer
96		- tokenEnv: GITHUB_PERSONAL_ACCESS_TOKEN
97		- headers:
98		- Accept: "application/json, text/event-stream"
99		-
100		- - name: wikipedia
101		- transport: http
102		- url: https://wikipedia-mcp.vercel.app/mcp
103		- auth:
104		- type: none
105		- headers:
106		- Accept: "application/json, text/event-stream"
107		-```
108		-
109		-### Options de Transport
110		-
111		-\| Transport \| Description \| Auth Supportée \|
112		-\|-----------\|-------------\|----------------\|
113		-\| `http` \| MCP sur HTTP (streamable) \| none, bearer, api_key \|
114		-\| `stdio` \| MCP sur stdin/stdout \| Non encore implémenté \|
115		-
116		-> ⚠️ Note sur les headers : Certains serveurs MCP (comme Context7) nécessitent des headers HTTP spécifiques comme `Accept: application/json, text/event-stream`. Vous pouvez les ajouter via la section `headers` dans la configuration du serveur.
117		-
118		-### Types d'Authentification
119		-
120		-\| Type \| Description \| Variables requises \|
121		-\|------\|-------------\|-------------------\|
122		-\| `none` \| Aucune authentification \| - \|
123		-\| `bearer` \| Token Bearer (Authorization: Bearer ...) \| `tokenEnv` \|
124		-\| `api_key` \| Clé API (header personnalisable) \| `apiKeyEnv`, `apiKeyHeader` (optionnel, défaut: Authorization) \|
125		-
126		----
127		-
128		-## 🦆 DuckDuckGo MCP Server (HasData)
129		-
130		-### 📌 Qu'est-ce que c'est ?
131		-
132		-DuckDuckGo MCP (HasData) est un serveur MCP hébergé qui fournit des capacités de recherche web via l'API HasData.
133		-
134		-- Gratuit - 1,000 crédits/mois (100 recherches) sans carte bancaire
135		-- Simple - Une tool principale: `hasdata_duckduckgo_serp_getSearchResults`
136		-- Régions - Support de 37 régions différentes
137		-- Résultats structurés - JSON avec position, titre, URL, snippet, etc.
138		-
139		-### 🔧 Configuration
140		-
141		-```yaml
142		-- name: duckduckgo
143		- transport: http
144		- url: https://mcp.hasdata.com/mcp?apis=duckduckgo
145		- auth:
146		- type: api_key
147		- apiKeyEnv: HASDATA_API_KEY
148		- apiKeyHeader: x-api-key
149		-```
150		-
151		-> ⚠️ Note importante : Le serveur DuckDuckGo MCP officiel est hébergé par HasData.
152		-> L'URL `https://duckduckgo.com/mcp` n'est PAS un serveur MCP - c'est juste le site web de DuckDuckGo.
153		->
154		-> Test de connectivité :
155		-> ```bash
156		-> curl -I -H "x-api-key: VOTRE_CLE" https://mcp.hasdata.com/mcp?apis=duckduckgo
157		-> ```
158		-> Doit retourner HTTP 200 ou 401 (si la clé est invalide).
159		-
160		-### 💡 Utilisation
161		-
162		-Une fois configuré, mini-me aura accès à l'outil : `hasdata_duckduckgo_serp_getSearchResults`
163		-
164		-Exemples de requêtes :
165		-
166		-```
167		-"Recherche des dernières nouvelles sur l'IA"
168		--> Le modèle peut utiliser hasdata_duckduckgo_serp_getSearchResults avec votre requête
169		-
170		-"Quelle est la documentation officielle de Go 1.22 ?"
171		--> Le modèle peut rechercher et retourner des liens pertinents
172		-```
173		-
174		-Paramètres disponibles :
175		-- `q` (requis) : La requête de recherche
176		-- `kl` : Région au format `<pays>-<langue>` (ex: `fr-fr`, `us-en`, `de-de`)
177		-- `cc` : Code pays à 2 lettres
178		-- `setLang` : Langue de l'interface
179		-- `safeSearch` : `off`, `moderate`, ou `strict`
180		-- `max_results` : Nombre maximum de résultats (par défaut: 10)
181		-
182		-> ⚠️ Coût : Chaque appel coûte 10 crédits. Le tier gratuit offre 1,000 crédits/mois (100 recherches).
183		-
184		-### 🎯 Cas d'usage
185		-
186		-- Recherche de documentation
187		-- Vérification de faits récents
188		-- Trouver des exemples de code
189		-- Résoudre des problèmes avec des solutions en ligne
190		-
191		-### ⚠️ Limitations
192		-
193		-- Une seule tool disponible via HasData: `hasdata_duckduckgo_serp_getSearchResults`
194		-
195		----
196		-
197		-## 🐙 GitHub MCP Server
198		-
199		-### 📌 Qu'est-ce que c'est ?
200		-
201		-GitHub MCP est le serveur MCP officiel de GitHub, qui fournit un accès complet à l'API GitHub.
202		-
203		-- Authentification : GitHub Personal Access Token (PAT) requis
204		-- Transport : Streamable HTTP
205		-- Outils : Accès aux dépôts, code, issues, pull requests, etc.
206		-- Official : Maintenu par GitHub
207		-
208		-### 🔧 Configuration
209		-
210		-```yaml
211		-- name: github
212		- transport: http
213		- url: https://api.githubcopilot.com/mcp/
214		- auth:
215		- type: bearer
216		- tokenEnv: GITHUB_PERSONAL_ACCESS_TOKEN
217		- headers:
218		- Accept: "application/json, text/event-stream"
219		-```
220		-
221		-### 💡 Utilisation
222		-
223		-Une fois configuré, mini-me aura accès aux outils GitHub (préfixés par `github_`).
224		-
225		-Exemples d'outils typiques :
226		-- `list_repositories` - Lister vos dépôts
227		-- `read_repository` - Lire le contenu d'un dépôt
228		-- `search_code` - Rechercher dans le code
229		-- `get_issue` - Obtenir une issue
230		-- `list_pull_requests` - Lister les pull requests
231		-
232		-> ⚠️ Note : Les outils disponibles dépendent des scopes de votre PAT.
233		-
234		-Exemples de requêtes :
235		-
236		-```
237		-"Quels sont mes dépôts publics sur GitHub ?"
238		--> Le modèle peut utiliser github_list_repositories
239		-
240		-"Montre-moi le fichier README.md de mon dépôt mini-me"
241		--> Le modèle peut utiliser github_read_repository
242		-
243		-"Recherche l'utilisation de modelcontextprotocol dans mon code"
244		--> Le modèle peut utiliser github_search_code
245		-```
246		-
247		-### 🎯 Cas d'usage
248		-
249		-- Explorer vos dépôts GitHub
250		-- Lire des fichiers spécifiques
251		-- Rechercher dans votre code
252		-- Gérer les issues et pull requests
253		-- Analyser la structure de vos projets
254		-
255		-### 🔑 Authentification et Scopes
256		-
257		-Votre PAT doit avoir les scopes appropriés pour les outils que vous voulez utiliser :
258		-
259		-\| Outils \| Scopes requis \|
260		-\|-------\|---------------\|
261		-\| Lister les dépôts \| `repo` (lecture) \|
262		-\| Lire les fichiers \| `repo` (lecture) \|
263		-\| Rechercher dans le code \| `repo` (lecture) \|
264		-\| Gérer les issues \| `repo`, `issues` \|
265		-\| Gérer les PR \| `repo`, `pull_requests` \|
266		-
267		-> ✅ Pour commencer : Utilisez un PAT avec le scope `repo` (lecture seulement)
268		-
269		----
270		-
271		-## 📚 Wikipedia MCP Server
272		-
273		-### 📌 Qu'est-ce que c'est ?
274		-
275		-Wikipedia MCP est un serveur MCP hébergé qui fournit un accès complet à Wikipedia.
276		-
277		-- Gratuit - Aucune clé API nécessaire
278		-- Complet - Recherche, articles, résumés, sections, liens, etc.
279		-- Multi-langues - Support de nombreuses langues
280		-- Aucune authentification requise
281		-
282		-### 🔧 Configuration
283		-
284		-```yaml
285		-- name: wikipedia
286		- transport: http
287		- url: https://wikipedia-mcp.vercel.app/mcp
288		- auth:
289		- type: none
290		- headers:
291		- Accept: "application/json, text/event-stream"
292		-```
293		-
294		-### 💡 Utilisation
295		-
296		-Une fois configuré, mini-me aura accès aux outils Wikipedia suivants (préfixés par `wikipedia_`) :
297		-- `wikipedia_search_wikipedia` - Rechercher des articles
298		-- `wikipedia_get_article` - Récupérer un article complet
299		-- `wikipedia_get_summary` - Obtenir un résumé
300		-- `wikipedia_get_sections` - Lister les sections d'un article
301		-- `wikipedia_get_links` - Obtenir les liens d'un article
302		-- `wikipedia_get_coordinates` - Coordonnées géographiques
303		-- `wikipedia_get_related_topics` - Sujets liés
304		-- `wikipedia_summarize_article_for_query` - Résumer un article pour une requête
305		-- `wikipedia_summarize_article_section` - Résumer une section
306		-- `wikipedia_extract_key_facts` - Extraire les faits clés
307		-- `wikipedia_test_wikipedia_connectivity` - Tester la connectivité
308		-- `wikipedia_list_supported_countries` - Lister les pays supportés
309		-- `wikipedia_multi_search_wikipedia` - Recherche multiple
310		-
311		-Exemples de requêtes :
312		-
313		-```
314		-"Qu'est-ce que le Model Context Protocol ?"
315		--> Le modèle peut utiliser wikipedia_search_wikipedia pour trouver l'article
316		-
317		-"Donne-moi un résumé de l'article sur la relativité"
318		--> Le modèle peut utiliser wikipedia_get_summary
319		-
320		-"Quels sont les liens dans l'article sur l'IA ?"
321		--> Le modèle peut utiliser wikipedia_get_links
322		-```
323		-
324		-### 🎯 Cas d'usage
325		-
326		-- Recherche d'informations générales
327		-- Vérification de faits
328		-- Obtenir des définitions et explications
329		-- Explorer des sujets de manière approfondie
330		-
331		-### ✅ Avantages
332		-
333		-- Gratuit - Pas de limitations de quota connues
334		-- Immédiat - Pas besoin de s'inscrire
335		-- Complet - Accès à toutes les fonctionnalités Wikipedia
336		-- Les résultats sont limités par le format de réponse de DuckDuckGo
337		-- Pas de contexte de conversation (chaque recherche est indépendante)
338		-
339		----
340		-
341		-## 🎯 Context7 MCP Server
342		-
343		-### 📌 Qu'est-ce que c'est ?
344		-
345		-Context7 est un serveur MCP qui fournit :
346		-- Recherche dans la documentation officielle
347		-- Compréhension du contexte de code
348		-- Génération de code contextuel
349		-
350		-### 🔑 Authentification Requise
351		-
352		-Context7 nécessite une clé API.
353		-
354		-1. Obtenez une clé API :
355		- - Allez sur [https://context7.com](https://context7.com)
356		- - Inscrivez-vous (gratuit)
357		- - Récupérez votre clé API dans le tableau de bord
358		-
359		-2. Exportez la clé :
360		- ```bash
361		- export CONTEXT7_API_KEY="votre-clé-api"
362		- ```
363		-
364		-3. Ajoutez au shell profile (optionnel) :
365		- ```bash
366		- # Pour bash/zsh
367		- echo 'export CONTEXT7_API_KEY="votre-clé-api"' >> ~/.bashrc
368		- source ~/.bashrc
369		- ```
370		-
371		-### 🔧 Configuration
372		-
373		-```yaml
374		-- name: context7
375		- transport: http
376		- url: https://mcp.context7.com/mcp
377		- timeout: 60s # Temps plus long pour les requêtes complexes
378		- auth:
379		- type: bearer
380		- tokenEnv: CONTEXT7_API_KEY
381		-```
382		-
383		-### 💡 Utilisation
384		-
385		-Une fois configuré, mini-me aura accès aux outils Context7, préfixés par `context7_` :
386		-- Les outils disponibles dépendent de ce que le serveur Context7 expose
387		-- Exemples typiques : `search_documentation`, `get_code_context`, etc.
388		-
389		-Exemples de requêtes :
390		-
391		-```
392		-"Comment utiliser le package http en Go ?"
393		--> Le modèle peut utiliser context7_search_documentation pour trouver la doc officielle
394		-
395		-"Explique moi ce code React"
396		--> Le modèle peut utiliser context7_get_code_context pour comprendre le contexte
397		-```
398		-
399		-### 🎯 Cas d'usage
400		-
401		-- Recherche de documentation technique
402		-- Compréhension de bibliothèques et frameworks
403		-- Génération de code avec contexte
404		-- Debugging avec des exemples réels
405		-
406		-### ⚠️ Limitations
407		-
408		-- Nécessite une connexion internet
409		-- Dépend de la disponibilité du service Context7
410		-- Les outils disponibles peuvent changer
411		-
412		----
413		-
414		-## 🔄 Filtrage des Outils
415		-
416		-Par défaut, tous les outils d'un serveur MCP sont exposés à mini-me.
417		-
418		-Vous pouvez filtrer les outils en spécifiant une liste :
419		-
420		-```yaml
421		-- name: context7
422		- transport: http
423		- url: https://mcp.context7.com/mcp
424		- auth:
425		- type: bearer
426		- tokenEnv: CONTEXT7_API_KEY
427		- tools: # Seuls ces outils seront exposés
428		- - search_documentation
429		- - get_code_context
430		-```
431		-
432		-Cela réduit :
433		-- Le nombre d'outils dans le prompt (économie de tokens)
434		-- La surface d'attaque potentielle
435		-- Le bruit dans la liste des outils
436		-
437		----
438		-
439		-## 🛡️ Sécurité
440		-
441		-### Permissions
442		-
443		-Deux modes de permissions sont disponibles :
444		-
445		-\| Mode \| Comportement \| Recommandation \|
446		-\|------\|-------------\|----------------\|
447		-\| `ask` \| Demande confirmation avant chaque appel MCP \| ✅ Recommandé \|
448		-\| `auto` \| Exécute automatiquement (comme bash) \| ⚠️ À utiliser avec prudence \|
449		-
450		-Configuration globale :
451		-```yaml
452		-mcp:
453		- permissions: ask # Mode par défaut pour tous les serveurs
454		-```
455		-
456		-Override par serveur :
457		-```yaml
458		-servers:
459		- - name: duckduckgo
460		- permissions: auto # Auto pour ce serveur spécifique
461		- ...
462		- - name: context7
463		- permissions: ask # Ask pour ce serveur
464		- ...
465		-```
466		-
467		-### Bonnes Pratiques
468		-
469		-1. Utilisez toujours `permissions: ask` pour les serveurs que vous ne connaissez pas
470		-2. Ne partagez pas vos clés API dans les fichiers de configuration
471		-3. Utilisez des variables d'environnement pour les clés sensibles
472		-4. Filtrez les outils que vous n'utilisez pas
473		-5. Testez en local avant de déployer en production
474		-
475		----
476		-
477		-## 🛠️ Dépannage
478		-
479		-### Problème : "mcp: enabled but no servers configured"
480		-
481		-Cause : MCP est activé mais aucun serveur n'est configuré.
482		-
483		-Solution : Ajoutez au moins un serveur dans la liste `servers`.
484		-
485		----
486		-
487		-### Problème : "mcp server X: discovery failed: connection refused"
488		-
489		-Causes possibles :
490		-- Le serveur MCP est hors ligne
491		-- L'URL est incorrecte
492		-- Problème de réseau
493		-- Authentification manquante ou incorrecte
494		-- Headers HTTP manquants (comme `Accept: application/json, text/event-stream`)
495		-
496		-Solutions :
497		-- Vérifiez l'URL du serveur
498		-- Vérifiez que les variables d'environnement pour l'authentification sont définies
499		-- Pour Context7, assurez-vous que le header `Accept` est correctement configuré
500		-- Testez la connectivité : `curl -v -H "Authorization: Bearer VOTRE_TOKEN" -H "Accept: application/json, text/event-stream" https://mcp.context7.com/mcp`
501		-- Essayez plus tard
502		-
503		----
504		-
505		-### Problème : "missing bearer token for env var CONTEXT7_API_KEY"
506		-
507		-Cause : La variable d'environnement `CONTEXT7_API_KEY` n'est pas définie.
508		-
509		-Solution :
510		-```bash
511		-export CONTEXT7_API_KEY="votre-clé"
512		-./mm -config demo/agent.dmr.mcp.yaml
513		-```
514		-
515		----
516		-
517		-### Problème : "missing api_key for env var HASDATA_API_KEY"
518		-
519		-Cause : La variable d'environnement `HASDATA_API_KEY` n'est pas définie.
520		-
521		-Solution :
522		-```bash
523		-export HASDATA_API_KEY="votre-clé"
524		-./mm -config demo/agent.dmr.mcp.yaml
525		-```
526		-
527		-> ✅ Comment obtenir une clé HasData :
528		-> 1. Inscrivez-vous gratuitement sur [https://app.hasdata.com](https://app.hasdata.com)
529		-> 2. Récupérez votre clé API dans le tableau de bord
530		-> 3. Vous obtenez 1,000 crédits gratuits par mois (100 recherches)
531		-
532		----
533		-
534		-### Problème : Les outils MCP n'apparaissent pas dans la bannière
535		-
536		-Causes possibles :
537		-- MCP est désactivé
538		-- La discovery a échoué silencieusement
539		-- Tous les outils ont été filtrés (binary I/O)
540		-
541		-Solution :
542		-- Vérifiez les warnings dans la bannière de démarrage
543		-- Vérifiez que `mcp.enabled: true`
544		-- Essayez avec un timeout de discovery plus long
545		-
546		----
547		-
548		-## 📊 Exemples Complets
549		-
550		-### Configuration Minimale (DuckDuckGo seul)
551		-
552		-```yaml
553		-mcp:
554		- enabled: true
555		- permissions: ask
556		- servers:
557		- - name: duckduckgo
558		- transport: http
559		- url: https://mcp.hasdata.com/mcp?apis=duckduckgo
560		- auth:
561		- type: api_key
562		- apiKeyEnv: HASDATA_API_KEY
563		- apiKeyHeader: x-api-key
564		-```
565		-
566		-### Configuration Complète (Les deux serveurs)
567		-
568		-Voir `demo/agent.dmr.mcp.yaml` pour un exemple complet.
569		-
570		----
571		-
572		-## 🎓 Astuces
573		-
574		-### 1. Nom des Outils
575		-
576		-Les outils MCP sont préfixés avec le nom du serveur :
577		-- `duckduckgo_search`
578		-- `context7_search_documentation`
579		-
580		-Cela évite les collisions et permet de savoir d'où vient chaque outil.
581		-
582		-### 2. Découverte au Démarrage
583		-
584		-La découverte des outils MCP se fait au démarrage de mini-me, pas à la première utilisation.
585		-Cela signifie :
586		-- Un temps de démarrage légèrement plus long
587		-- La liste des outils est statique pour la session
588		-- Si un serveur meurt pendant la session, les outils deviennent indisponibles
589		-
590		-### 3. Texte Seulement
591		-
592		-Mini-me ignore les outils binaires. Seuls les outils avec entrée/sortie texte sont exposés.
593		-
594		-Cela signifie que les outils qui manipulent des images, PDFs, ou autres données binaires ne seront pas disponibles.
595		-
596		----
597		-
598		-## 📚 Références
599		-
600		-- [Context7 Official Site](https://context7.com)
601		-- [DuckDuckGo](https://duckduckgo.com)
602		-- [HasData DuckDuckGo MCP Server](https://github.com/HasData/duckduckgo-mcp)
603		-- [HasData Dashboard](https://app.hasdata.com)
604		-- [MCP Specification](https://modelcontextprotocol.io/)
605		-
606		----
607		-
608		-## 🔄 Changelog
609		-
610		-\| Date \| Changement \|
611		-\|------\|------------\|
612		-\| 2026-09-23 \| Guide initial créé \|
613		-\| 2026-09-23 \| Configuration MCP ajoutée à agent.dmr.mcp.yaml \|
614		-\| 2026-09-23 \| Mise à jour : DuckDuckGo utilise maintenant le serveur HasData (https://mcp.hasdata.com) \|
615		-\| 2026-09-23 \| Ajout du header Accept pour Context7 \|
616		-\| 2026-09-23 \| Correction des URLs et authentifications \|
617		-
618		----
619		-
620		-## 💬 Support
621		-
622		-Si vous rencontrez des problèmes avec les serveurs MCP :
623		-1. Vérifiez les warnings dans la bannière de mini-me
624		-2. Consultez ce guide
625		-3. Vérifiez les logs et les messages d'erreur
626		-4. Ouvrez un issue avec les détails du problème
627		-
628		----
629		-
630		-Note : Les serveurs MCP sont des services tiers. Leur disponibilité, leurs outils et leur comportement peuvent changer sans préavis. Mini-me fait de son mieux pour intégrer ces services de manière sûre et fiable, mais ne peut pas garantir leur fonctionnement.

--# Guide: Utiliser les Serveurs MCP avec mini-me
--
--Ce document explique comment configurer et utiliser des serveurs MCP avec mini-me :
--- **Context7 MCP** - Documentation et contexte de code (nécessite une clé API)
--- **GitHub MCP** - Accès à GitHub (nécessite un Personal Access Token)
--- **Wikipedia MCP** - Accès complet à Wikipedia (gratuit, aucune authentification requise)
--- **DuckDuckGo MCP (HasData)** - Recherche web via HasData (1,000 crédits gratuits/mois) - *actuellement désactivé dans la config par défaut*
--
-----
--
--## 🚀 Configuration Rapide
--
--### 1. Utiliser le fichier de configuration fourni
--
--Un fichier de configuration prêt à l'emploi est fourni : `demo/agent.dmr.mcp.yaml`
--
--Il contient déjà la configuration pour les deux serveurs MCP.
--
--### 2. Exporter vos clés API
--
--#### Pour Context7
--```bash
--export CONTEXT7_API_KEY="votre-clé-api-context7"
--```
--
--> ✅ **Où obtenir une clé Context7 ?**
--> Inscrivez-vous sur [https://context7.com](https://context7.com) pour obtenir une clé API gratuite.
--
--#### Pour GitHub
--```bash
--export GITHUB_PERSONAL_ACCESS_TOKEN="votre-token-github"
--```
--
--> ✅ **Où obtenir un PAT GitHub ?**
--> 1. Allez sur [https://github.com/settings/tokens](https://github.com/settings/tokens)
--> 2. Cliquez sur "Generate new token" (classic)
--> 3. Donnez un nom à votre token
--> 4. Sélectionnez les scopes nécessaires (ex: `repo` pour l'accès aux dépôts)
--> 5. Générez le token et copiez-le
--
--> ⚠️ **Scopes recommandés :**
--> - `repo` : Accès complet aux dépôts (lecture/écriture)
--> - `read:org` : Lire les informations d'organisation
--> - `user` : Accès au profil utilisateur
-->
--> Pour une utilisation en lecture seule, `repo` (lecture) suffit.
--
--#### Pour Wikipedia
--Aucune clé n'est nécessaire ! ✅
--
--#### Pour DuckDuckGo (HasData)
--```bash
--export HASDATA_API_KEY="votre-clé-api-hasdata"
--```
--
--> ✅ **Où obtenir une clé HasData ?**
--> Inscrivez-vous sur [https://app.hasdata.com](https://app.hasdata.com) pour obtenir une clé API gratuite.
--> **Gratuit : 1,000 crédits/mois (100 recherches)**
--
--> ⚠️ **Note importante :** Le serveur DuckDuckGo utilisé est hébergé par HasData, pas par DuckDuckGo directement.
--
--### 3. Lancer mini-me avec la configuration MCP
--
--```bash
--# Depuis le répertoire mini-me
--./mm -config demo/agent.dmr.mcp.yaml
--```
--
-----
--
--## 📝 Configuration Détailée
--
--### Structure de la Configuration MCP
--
--```yaml
--mcp:
--  enabled: true                    # Active le support MCP
--  permissions: ask                # Demander avant d'exécuter (recommandé)
--  discoveryTimeout: 10s           # Timeout pour la découverte des outils
--
--  servers:
--    - name: context7
--      transport: http
--      url: https://mcp.context7.com/mcp
--      auth:
--        type: bearer
--        tokenEnv: CONTEXT7_API_KEY
--      headers:
--        Accept: "application/json, text/event-stream"
--
--    - name: github
--      transport: http
--      url: https://api.githubcopilot.com/mcp/
--      auth:
--        type: bearer
--        tokenEnv: GITHUB_PERSONAL_ACCESS_TOKEN
--      headers:
--        Accept: "application/json, text/event-stream"
--
--    - name: wikipedia
--      transport: http
--      url: https://wikipedia-mcp.vercel.app/mcp
--      auth:
--        type: none
--      headers:
--        Accept: "application/json, text/event-stream"
--```
--
--### Options de Transport
--
--| Transport | Description | Auth Supportée |
--|-----------|-------------|----------------|
--| `http` | MCP sur HTTP (streamable) | none, bearer, api_key |
--| `stdio` | MCP sur stdin/stdout | Non encore implémenté |
--
--> ⚠️ **Note sur les headers :** Certains serveurs MCP (comme Context7) nécessitent des headers HTTP spécifiques comme `Accept: application/json, text/event-stream`. Vous pouvez les ajouter via la section `headers` dans la configuration du serveur.
--
--### Types d'Authentification
--
--| Type | Description | Variables requises |
--|------|-------------|-------------------|
--| `none` | Aucune authentification | - |
--| `bearer` | Token Bearer (Authorization: Bearer ...) | `tokenEnv` |
--| `api_key` | Clé API (header personnalisable) | `apiKeyEnv`, `apiKeyHeader` (optionnel, défaut: Authorization) |
--
-----
--
--## 🦆 DuckDuckGo MCP Server (HasData)
--
--### 📌 Qu'est-ce que c'est ?
--
--**DuckDuckGo MCP (HasData)** est un serveur MCP hébergé qui fournit des capacités de **recherche web** via l'API HasData.
--
--- **Gratuit** - 1,000 crédits/mois (100 recherches) sans carte bancaire
--- **Simple** - Une tool principale: `hasdata_duckduckgo_serp_getSearchResults`
--- **Régions** - Support de 37 régions différentes
--- **Résultats structurés** - JSON avec position, titre, URL, snippet, etc.
--
--### 🔧 Configuration
--
--```yaml
--- name: duckduckgo
--  transport: http
--  url: https://mcp.hasdata.com/mcp?apis=duckduckgo
--  auth:
--    type: api_key
--    apiKeyEnv: HASDATA_API_KEY
--    apiKeyHeader: x-api-key
--```
--
--> ⚠️ **Note importante :** Le serveur DuckDuckGo MCP officiel est hébergé par HasData.
--> L'URL `https://duckduckgo.com/mcp` n'est PAS un serveur MCP - c'est juste le site web de DuckDuckGo.
-->
--> **Test de connectivité :**
--> ```bash
--> curl -I -H "x-api-key: VOTRE_CLE" https://mcp.hasdata.com/mcp?apis=duckduckgo
--> ```
--> Doit retourner HTTP 200 ou 401 (si la clé est invalide).
--
--### 💡 Utilisation
--
--Une fois configuré, mini-me aura accès à l'outil : **`hasdata_duckduckgo_serp_getSearchResults`**
--
--**Exemples de requêtes :**
--
--```
--"Recherche des dernières nouvelles sur l'IA"
---> Le modèle peut utiliser hasdata_duckduckgo_serp_getSearchResults avec votre requête
--
--"Quelle est la documentation officielle de Go 1.22 ?"
---> Le modèle peut rechercher et retourner des liens pertinents
--```
--
--**Paramètres disponibles :**
--- `q` (requis) : La requête de recherche
--- `kl` : Région au format `<pays>-<langue>` (ex: `fr-fr`, `us-en`, `de-de`)
--- `cc` : Code pays à 2 lettres
--- `setLang` : Langue de l'interface
--- `safeSearch` : `off`, `moderate`, ou `strict`
--- `max_results` : Nombre maximum de résultats (par défaut: 10)
--
--> ⚠️ **Coût :** Chaque appel coûte **10 crédits**. Le tier gratuit offre 1,000 crédits/mois (100 recherches).
--
--### 🎯 Cas d'usage
--
--- Recherche de documentation
--- Vérification de faits récents
--- Trouver des exemples de code
--- Résoudre des problèmes avec des solutions en ligne
--
--### ⚠️ Limitations
--
--- Une seule tool disponible via HasData: `hasdata_duckduckgo_serp_getSearchResults`
--
-----
--
--## 🐙 GitHub MCP Server
--
--### 📌 Qu'est-ce que c'est ?
--
--**GitHub MCP** est le serveur MCP **officiel** de GitHub, qui fournit un accès complet à l'API GitHub.
--
--- **Authentification** : GitHub Personal Access Token (PAT) requis
--- **Transport** : Streamable HTTP
--- **Outils** : Accès aux dépôts, code, issues, pull requests, etc.
--- **Official** : Maintenu par GitHub
--
--### 🔧 Configuration
--
--```yaml
--- name: github
--  transport: http
--  url: https://api.githubcopilot.com/mcp/
--  auth:
--    type: bearer
--    tokenEnv: GITHUB_PERSONAL_ACCESS_TOKEN
--  headers:
--    Accept: "application/json, text/event-stream"
--```
--
--### 💡 Utilisation
--
--Une fois configuré, mini-me aura accès aux outils GitHub (préfixés par `github_`).
--
--**Exemples d'outils typiques :**
--- `list_repositories` - Lister vos dépôts
--- `read_repository` - Lire le contenu d'un dépôt
--- `search_code` - Rechercher dans le code
--- `get_issue` - Obtenir une issue
--- `list_pull_requests` - Lister les pull requests
--
--> ⚠️ **Note :** Les outils disponibles dépendent des **scopes** de votre PAT.
--
--**Exemples de requêtes :**
--
--```
--"Quels sont mes dépôts publics sur GitHub ?"
---> Le modèle peut utiliser github_list_repositories
--
--"Montre-moi le fichier README.md de mon dépôt mini-me"
---> Le modèle peut utiliser github_read_repository
--
--"Recherche l'utilisation de modelcontextprotocol dans mon code"
---> Le modèle peut utiliser github_search_code
--```
--
--### 🎯 Cas d'usage
--
--- Explorer vos dépôts GitHub
--- Lire des fichiers spécifiques
--- Rechercher dans votre code
--- Gérer les issues et pull requests
--- Analyser la structure de vos projets
--
--### 🔑 Authentification et Scopes
--
--Votre PAT doit avoir les **scopes** appropriés pour les outils que vous voulez utiliser :
--
--| Outils | Scopes requis |
--|-------|---------------|
--| Lister les dépôts | `repo` (lecture) |
--| Lire les fichiers | `repo` (lecture) |
--| Rechercher dans le code | `repo` (lecture) |
--| Gérer les issues | `repo`, `issues` |
--| Gérer les PR | `repo`, `pull_requests` |
--
--> ✅ **Pour commencer** : Utilisez un PAT avec le scope `repo` (lecture seulement)
--
-----
--
--## 📚 Wikipedia MCP Server
--
--### 📌 Qu'est-ce que c'est ?
--
--**Wikipedia MCP** est un serveur MCP hébergé qui fournit un **accès complet à Wikipedia**.
--
--- **Gratuit** - Aucune clé API nécessaire
--- **Complet** - Recherche, articles, résumés, sections, liens, etc.
--- **Multi-langues** - Support de nombreuses langues
--- **Aucune authentification** requise
--
--### 🔧 Configuration
--
--```yaml
--- name: wikipedia
--  transport: http
--  url: https://wikipedia-mcp.vercel.app/mcp
--  auth:
--    type: none
--  headers:
--    Accept: "application/json, text/event-stream"
--```
--
--### 💡 Utilisation
--
--Une fois configuré, mini-me aura accès aux outils Wikipedia suivants (préfixés par `wikipedia_`) :
--- `wikipedia_search_wikipedia` - Rechercher des articles
--- `wikipedia_get_article` - Récupérer un article complet
--- `wikipedia_get_summary` - Obtenir un résumé
--- `wikipedia_get_sections` - Lister les sections d'un article
--- `wikipedia_get_links` - Obtenir les liens d'un article
--- `wikipedia_get_coordinates` - Coordonnées géographiques
--- `wikipedia_get_related_topics` - Sujets liés
--- `wikipedia_summarize_article_for_query` - Résumer un article pour une requête
--- `wikipedia_summarize_article_section` - Résumer une section
--- `wikipedia_extract_key_facts` - Extraire les faits clés
--- `wikipedia_test_wikipedia_connectivity` - Tester la connectivité
--- `wikipedia_list_supported_countries` - Lister les pays supportés
--- `wikipedia_multi_search_wikipedia` - Recherche multiple
--
--**Exemples de requêtes :**
--
--```
--"Qu'est-ce que le Model Context Protocol ?"
---> Le modèle peut utiliser wikipedia_search_wikipedia pour trouver l'article
--
--"Donne-moi un résumé de l'article sur la relativité"
---> Le modèle peut utiliser wikipedia_get_summary
--
--"Quels sont les liens dans l'article sur l'IA ?"
---> Le modèle peut utiliser wikipedia_get_links
--```
--
--### 🎯 Cas d'usage
--
--- Recherche d'informations générales
--- Vérification de faits
--- Obtenir des définitions et explications
--- Explorer des sujets de manière approfondie
--
--### ✅ Avantages
--
--- **Gratuit** - Pas de limitations de quota connues
--- **Immédiat** - Pas besoin de s'inscrire
--- **Complet** - Accès à toutes les fonctionnalités Wikipedia
--- Les résultats sont limités par le format de réponse de DuckDuckGo
--- Pas de contexte de conversation (chaque recherche est indépendante)
--
-----
--
--## 🎯 Context7 MCP Server
--
--### 📌 Qu'est-ce que c'est ?
--
--**Context7** est un serveur MCP qui fournit :
--- Recherche dans la documentation officielle
--- Compréhension du contexte de code
--- Génération de code contextuel
--
--### 🔑 Authentification Requise
--
--Context7 nécessite une **clé API**.
--
--1. **Obtenez une clé API :**
--   - Allez sur [https://context7.com](https://context7.com)
--   - Inscrivez-vous (gratuit)
--   - Récupérez votre clé API dans le tableau de bord
--
--2. **Exportez la clé :**
--   ```bash
--   export CONTEXT7_API_KEY="votre-clé-api"
--   ```
--
--3. **Ajoutez au shell profile (optionnel) :**
--   ```bash
--   # Pour bash/zsh
--   echo 'export CONTEXT7_API_KEY="votre-clé-api"' >> ~/.bashrc
--   source ~/.bashrc
--   ```
--
--### 🔧 Configuration
--
--```yaml
--- name: context7
--  transport: http
--  url: https://mcp.context7.com/mcp
--  timeout: 60s  # Temps plus long pour les requêtes complexes
--  auth:
--    type: bearer
--    tokenEnv: CONTEXT7_API_KEY
--```
--
--### 💡 Utilisation
--
--Une fois configuré, mini-me aura accès aux outils Context7, préfixés par `context7_` :
--- Les outils disponibles dépendent de ce que le serveur Context7 expose
--- Exemples typiques : `search_documentation`, `get_code_context`, etc.
--
--**Exemples de requêtes :**
--
--```
--"Comment utiliser le package http en Go ?"
---> Le modèle peut utiliser context7_search_documentation pour trouver la doc officielle
--
--"Explique moi ce code React"
---> Le modèle peut utiliser context7_get_code_context pour comprendre le contexte
--```
--
--### 🎯 Cas d'usage
--
--- Recherche de documentation technique
--- Compréhension de bibliothèques et frameworks
--- Génération de code avec contexte
--- Debugging avec des exemples réels
--
--### ⚠️ Limitations
--
--- Nécessite une connexion internet
--- Dépend de la disponibilité du service Context7
--- Les outils disponibles peuvent changer
--
-----
--
--## 🔄 Filtrage des Outils
--
--Par défaut, **tous les outils** d'un serveur MCP sont exposés à mini-me.
--
--Vous pouvez **filtrer** les outils en spécifiant une liste :
--
--```yaml
--- name: context7
--  transport: http
--  url: https://mcp.context7.com/mcp
--  auth:
--    type: bearer
--    tokenEnv: CONTEXT7_API_KEY
--  tools:                     # Seuls ces outils seront exposés
--    - search_documentation
--    - get_code_context
--```
--
--Cela réduit :
--- Le nombre d'outils dans le prompt (économie de tokens)
--- La surface d'attaque potentielle
--- Le bruit dans la liste des outils
--
-----
--
--## 🛡️ Sécurité
--
--### Permissions
--
--Deux modes de permissions sont disponibles :
--
--| Mode | Comportement | Recommandation |
--|------|-------------|----------------|
--| `ask` | Demande confirmation avant chaque appel MCP | ✅ Recommandé |
--| `auto` | Exécute automatiquement (comme bash) | ⚠️ À utiliser avec prudence |
--
--**Configuration globale :**
--```yaml
--mcp:
--  permissions: ask  # Mode par défaut pour tous les serveurs
--```
--
--**Override par serveur :**
--```yaml
--servers:
--  - name: duckduckgo
--    permissions: auto  # Auto pour ce serveur spécifique
--    ...
--  - name: context7
--    permissions: ask   # Ask pour ce serveur
--    ...
--```
--
--### Bonnes Pratiques
--
--1. **Utilisez toujours `permissions: ask`** pour les serveurs que vous ne connaissez pas
--2. **Ne partagez pas vos clés API** dans les fichiers de configuration
--3. **Utilisez des variables d'environnement** pour les clés sensibles
--4. **Filtrez les outils** que vous n'utilisez pas
--5. **Testez en local** avant de déployer en production
--
-----
--
--## 🛠️ Dépannage
--
--### Problème : "mcp: enabled but no servers configured"
--
--**Cause :** MCP est activé mais aucun serveur n'est configuré.
--
--**Solution :** Ajoutez au moins un serveur dans la liste `servers`.
--
-----
--
--### Problème : "mcp server X: discovery failed: connection refused"
--
--**Causes possibles :**
--- Le serveur MCP est hors ligne
--- L'URL est incorrecte
--- Problème de réseau
--- Authentification manquante ou incorrecte
--- Headers HTTP manquants (comme `Accept: application/json, text/event-stream`)
--
--**Solutions :**
--- Vérifiez l'URL du serveur
--- Vérifiez que les variables d'environnement pour l'authentification sont définies
--- Pour Context7, assurez-vous que le header `Accept` est correctement configuré
--- Testez la connectivité : `curl -v -H "Authorization: Bearer VOTRE_TOKEN" -H "Accept: application/json, text/event-stream" https://mcp.context7.com/mcp`
--- Essayez plus tard
--
-----
--
--### Problème : "missing bearer token for env var CONTEXT7_API_KEY"
--
--**Cause :** La variable d'environnement `CONTEXT7_API_KEY` n'est pas définie.
--
--**Solution :**
--```bash
--export CONTEXT7_API_KEY="votre-clé"
--./mm -config demo/agent.dmr.mcp.yaml
--```
--
-----
--
--### Problème : "missing api_key for env var HASDATA_API_KEY"
--
--**Cause :** La variable d'environnement `HASDATA_API_KEY` n'est pas définie.
--
--**Solution :**
--```bash
--export HASDATA_API_KEY="votre-clé"
--./mm -config demo/agent.dmr.mcp.yaml
--```
--
--> ✅ **Comment obtenir une clé HasData :**
--> 1. Inscrivez-vous gratuitement sur [https://app.hasdata.com](https://app.hasdata.com)
--> 2. Récupérez votre clé API dans le tableau de bord
--> 3. Vous obtenez **1,000 crédits gratuits par mois** (100 recherches)
--
-----
--
--### Problème : Les outils MCP n'apparaissent pas dans la bannière
--
--**Causes possibles :**
--- MCP est désactivé
--- La discovery a échoué silencieusement
--- Tous les outils ont été filtrés (binary I/O)
--
--**Solution :**
--- Vérifiez les warnings dans la bannière de démarrage
--- Vérifiez que `mcp.enabled: true`
--- Essayez avec un timeout de discovery plus long
--
-----
--
--## 📊 Exemples Complets
--
--### Configuration Minimale (DuckDuckGo seul)
--
--```yaml
--mcp:
--  enabled: true
--  permissions: ask
--  servers:
--    - name: duckduckgo
--      transport: http
--      url: https://mcp.hasdata.com/mcp?apis=duckduckgo
--      auth:
--        type: api_key
--        apiKeyEnv: HASDATA_API_KEY
--        apiKeyHeader: x-api-key
--```
--
--### Configuration Complète (Les deux serveurs)
--
--Voir `demo/agent.dmr.mcp.yaml` pour un exemple complet.
--
-----
--
--## 🎓 Astuces
--
--### 1. Nom des Outils
--
--Les outils MCP sont **préfixés avec le nom du serveur** :
--- `duckduckgo_search`
--- `context7_search_documentation`
--
--Cela évite les collisions et permet de savoir d'où vient chaque outil.
--
--### 2. Découverte au Démarrage
--
--La découverte des outils MCP se fait **au démarrage** de mini-me, pas à la première utilisation.
--Cela signifie :
--- Un temps de démarrage légèrement plus long
--- La liste des outils est **statique** pour la session
--- Si un serveur meurt pendant la session, les outils deviennent indisponibles
--
--### 3. Texte Seulement
--
--Mini-me **ignore les outils binaires**. Seuls les outils avec entrée/sortie texte sont exposés.
--
--Cela signifie que les outils qui manipulent des images, PDFs, ou autres données binaires ne seront **pas disponibles**.
--
-----
--
--## 📚 Références
--
--- [Context7 Official Site](https://context7.com)
--- [DuckDuckGo](https://duckduckgo.com)
--- [HasData DuckDuckGo MCP Server](https://github.com/HasData/duckduckgo-mcp)
--- [HasData Dashboard](https://app.hasdata.com)
--- [MCP Specification](https://modelcontextprotocol.io/)
--
-----
--
--## 🔄 Changelog
--
--| Date | Changement |
--|------|------------|
--| 2026-09-23 | Guide initial créé |
--| 2026-09-23 | Configuration MCP ajoutée à agent.dmr.mcp.yaml |
--| 2026-09-23 | Mise à jour : DuckDuckGo utilise maintenant le serveur HasData (https://mcp.hasdata.com) |
--| 2026-09-23 | Ajout du header Accept pour Context7 |
--| 2026-09-23 | Correction des URLs et authentifications |
--
-----
--
--## 💬 Support
--
--Si vous rencontrez des problèmes avec les serveurs MCP :
--1. Vérifiez les warnings dans la bannière de mini-me
--2. Consultez ce guide
--3. Vérifiez les logs et les messages d'erreur
--4. Ouvrez un issue avec les détails du problème
--
-----
--
--**Note :** Les serveurs MCP sont des services tiers. Leur disponibilité, leurs outils et leur comportement peuvent changer sans préavis. Mini-me fait de son mieux pour intégrer ces services de manière sûre et fiable, mais ne peut pas garantir leur fonctionnement.

deleted demo-dmr/newfile.txt +0 -0 Viewed

deleted file mode 100644

deleted demo-dmr/prompt.md +0 -100 Viewed

deleted file mode 100644
@@ -1,100 +0,0 @@
1		-
2		-Étape 1 — Squelette du projet
3		-```
4		-Crée un projet Go pour une application web de gestion d'issues (comme un mini Jira).
5		-Structure attendue :
6		-- go.mod (module "issue-tracker")
7		-- cmd/server/main.go : lance un serveur HTTP sur le port 8080
8		-- Une seule route "/" qui répond "OK" en texte brut
9		-Pas de base de données, pas de HTML pour l'instant. Vérifie que "go run cmd/server/main.go" démarre sans erreur et que curl localhost:8080 répond "OK".
10		-```
11		-
12		-Étape 2 — Modèle de données + stockage mémoire
13		-```
14		-Contexte : projet Go "issue-tracker" avec cmd/server/main.go qui lance un serveur sur le port 8080.
15		-Ajoute un package internal/store avec :
16		-- une struct Issue (ID int, Title string, Description string, Status string, Priority string, CreatedAt time.Time)
17		-- un store en mémoire (map protégée par un sync.Mutex)
18		-- des fonctions Create(issue) Issue, Get(id) (Issue, bool), List() []Issue, Update(id, issue) bool, Delete(id) bool
19		-N'ajoute aucune route HTTP pour l'instant. Ajoute juste un test unitaire simple qui vérifie Create + Get + List.
20		-```
21		-
22		-Étape 3 — Routes CRUD en JSON
23		-```
24		-Contexte : projet Go "issue-tracker" avec un package internal/store (CRUD en mémoire sur des Issue).
25		-Ajoute dans main.go les routes HTTP suivantes qui utilisent le store, en JSON :
26		-- GET /issues : liste toutes les issues
27		-- POST /issues : crée une issue à partir du JSON envoyé
28		-- GET /issues/{id} : retourne une issue
29		-- PUT /issues/{id} : met à jour une issue
30		-- DELETE /issues/{id} : supprime une issue
31		-Utilise net/http standard (pas de framework externe). Donne-moi ensuite 4 commandes curl pour tester chaque route.
32		-```
33		-
34		-Étape 4 — Première page HTML
35		-```
36		-Contexte : projet Go "issue-tracker" avec routes JSON /issues (GET/POST/PUT/DELETE) basées sur internal/store.
37		-Ajoute le rendu HTML avec html/template :
38		-- un dossier web/templates avec un layout.html (header/footer minimal) et une page index.html
39		-- une route GET / qui affiche la liste des issues dans un tableau HTML (ID, titre, statut, priorité)
40		-Ne touche pas encore aux routes JSON existantes, elles doivent continuer à fonctionner. Vérifie que localhost:8080/ affiche bien un tableau.
41		-```
42		-
43		-Étape 5 — Création d'issue avec HTMX
44		-```
45		-Contexte : projet Go "issue-tracker" avec une page / qui affiche un tableau d'issues (web/templates), et un store en mémoire.
46		-Ajoute HTMX (via CDN dans le layout) et :
47		-- un formulaire de création d'issue (titre, description, priorité) au-dessus du tableau
48		-- le formulaire poste en hx-post vers /issues/new, qui crée l'issue et renvoie le HTML d'une seule ligne <tr>
49		-- le tableau a un <tbody id="issues-list"> et le formulaire utilise hx-target="#issues-list" hx-swap="afterbegin"
50		-Vérifie que créer une issue l'ajoute dans le tableau sans recharger la page.
51		-```
52		-
53		-Étape 6 — Édition inline
54		-```
55		-Contexte : projet Go "issue-tracker", page / avec tableau d'issues et création via HTMX (route POST /issues/new).
56		-Ajoute l'édition d'une issue directement dans le tableau :
57		-- chaque ligne a un bouton "Éditer" avec hx-get vers /issues/{id}/edit qui remplace la ligne par un formulaire inline (hx-target="closest tr" hx-swap="outerHTML")
58		-- le formulaire d'édition poste en hx-put vers /issues/{id} et remplace la ligne par la version mise à jour
59		-Vérifie que l'édition fonctionne sans rechargement de page et sans casser la création.
60		-```
61		-
62		-Étape 7 — Suppression
63		-```
64		-Contexte : projet Go "issue-tracker", tableau d'issues avec création et édition inline via HTMX.
65		-Ajoute un bouton "Supprimer" sur chaque ligne :
66		-- hx-delete vers /issues/{id}
67		-- hx-confirm="Confirmer la suppression ?"
68		-- hx-target="closest tr" hx-swap="outerHTML swap:1s" (ou équivalent) pour retirer la ligne du tableau
69		-Vérifie que la suppression fonctionne et que les autres actions (création, édition) marchent toujours.
70		-```
71		-
72		-Étape 8 — Filtrage / recherche
73		-```
74		-Contexte : projet Go "issue-tracker" avec CRUD complet en HTMX sur les issues.
75		-Ajoute une barre de recherche au-dessus du tableau :
76		-- un input avec hx-get vers /issues/search, hx-trigger="keyup changed delay:300ms", hx-target="#issues-list"
77		-- la route /issues/search filtre les issues par titre (insensible à la casse) et renvoie uniquement les <tr> correspondants
78		-Vérifie que taper dans la barre filtre la liste en direct.
79		-```
80		-
81		-Étape 9 — Persistance SQLite
82		-```
83		-Contexte : projet Go "issue-tracker" avec store en mémoire (internal/store) et CRUD HTMX complet.
84		-Remplace le store en mémoire par SQLite :
85		-- utilise la lib modernc.org/sqlite (pure Go, pas besoin de cgo)
86		-- crée un fichier issues.db, table issues avec les mêmes champs que la struct Issue
87		-- garde exactement la même interface publique du package store (Create, Get, List, Update, Delete) pour ne rien casser côté routes
88		-Vérifie que les issues survivent à un redémarrage du serveur.
89		-```
90		-
91		-Étape 10 — Finitions
92		-```
93		-Contexte : projet Go "issue-tracker" complet (CRUD HTMX + SQLite).
94		-Ajoute :
95		-- un fichier web/static/style.css minimal (tableau propre, badges colorés selon le statut : open=vert, in_progress=orange, closed=gris)
96		-- une route pour servir web/static/
97		-- un favicon simple si possible
98		-N'ajoute rien d'autre, pas de nouvelle fonctionnalité.
99		-```
100		-

--
--**Étape 1 — Squelette du projet**
--```
--Crée un projet Go pour une application web de gestion d'issues (comme un mini Jira).
--Structure attendue :
--- go.mod (module "issue-tracker")
--- cmd/server/main.go : lance un serveur HTTP sur le port 8080
--- Une seule route "/" qui répond "OK" en texte brut
--Pas de base de données, pas de HTML pour l'instant. Vérifie que "go run cmd/server/main.go" démarre sans erreur et que curl localhost:8080 répond "OK".
--```
--
--**Étape 2 — Modèle de données + stockage mémoire**
--```
--Contexte : projet Go "issue-tracker" avec cmd/server/main.go qui lance un serveur sur le port 8080.
--Ajoute un package internal/store avec :
--- une struct Issue (ID int, Title string, Description string, Status string, Priority string, CreatedAt time.Time)
--- un store en mémoire (map protégée par un sync.Mutex)
--- des fonctions Create(issue) Issue, Get(id) (Issue, bool), List() []Issue, Update(id, issue) bool, Delete(id) bool
--N'ajoute aucune route HTTP pour l'instant. Ajoute juste un test unitaire simple qui vérifie Create + Get + List.
--```
--
--**Étape 3 — Routes CRUD en JSON**
--```
--Contexte : projet Go "issue-tracker" avec un package internal/store (CRUD en mémoire sur des Issue).
--Ajoute dans main.go les routes HTTP suivantes qui utilisent le store, en JSON :
--- GET /issues : liste toutes les issues
--- POST /issues : crée une issue à partir du JSON envoyé
--- GET /issues/{id} : retourne une issue
--- PUT /issues/{id} : met à jour une issue
--- DELETE /issues/{id} : supprime une issue
--Utilise net/http standard (pas de framework externe). Donne-moi ensuite 4 commandes curl pour tester chaque route.
--```
--
--**Étape 4 — Première page HTML**
--```
--Contexte : projet Go "issue-tracker" avec routes JSON /issues (GET/POST/PUT/DELETE) basées sur internal/store.
--Ajoute le rendu HTML avec html/template :
--- un dossier web/templates avec un layout.html (header/footer minimal) et une page index.html
--- une route GET / qui affiche la liste des issues dans un tableau HTML (ID, titre, statut, priorité)
--Ne touche pas encore aux routes JSON existantes, elles doivent continuer à fonctionner. Vérifie que localhost:8080/ affiche bien un tableau.
--```
--
--**Étape 5 — Création d'issue avec HTMX**
--```
--Contexte : projet Go "issue-tracker" avec une page / qui affiche un tableau d'issues (web/templates), et un store en mémoire.
--Ajoute HTMX (via CDN dans le layout) et :
--- un formulaire de création d'issue (titre, description, priorité) au-dessus du tableau
--- le formulaire poste en hx-post vers /issues/new, qui crée l'issue et renvoie le HTML d'une seule ligne <tr>
--- le tableau a un <tbody id="issues-list"> et le formulaire utilise hx-target="#issues-list" hx-swap="afterbegin"
--Vérifie que créer une issue l'ajoute dans le tableau sans recharger la page.
--```
--
--**Étape 6 — Édition inline**
--```
--Contexte : projet Go "issue-tracker", page / avec tableau d'issues et création via HTMX (route POST /issues/new).
--Ajoute l'édition d'une issue directement dans le tableau :
--- chaque ligne a un bouton "Éditer" avec hx-get vers /issues/{id}/edit qui remplace la ligne par un formulaire inline (hx-target="closest tr" hx-swap="outerHTML")
--- le formulaire d'édition poste en hx-put vers /issues/{id} et remplace la ligne par la version mise à jour
--Vérifie que l'édition fonctionne sans rechargement de page et sans casser la création.
--```
--
--**Étape 7 — Suppression**
--```
--Contexte : projet Go "issue-tracker", tableau d'issues avec création et édition inline via HTMX.
--Ajoute un bouton "Supprimer" sur chaque ligne :
--- hx-delete vers /issues/{id}
--- hx-confirm="Confirmer la suppression ?"
--- hx-target="closest tr" hx-swap="outerHTML swap:1s" (ou équivalent) pour retirer la ligne du tableau
--Vérifie que la suppression fonctionne et que les autres actions (création, édition) marchent toujours.
--```
--
--**Étape 8 — Filtrage / recherche**
--```
--Contexte : projet Go "issue-tracker" avec CRUD complet en HTMX sur les issues.
--Ajoute une barre de recherche au-dessus du tableau :
--- un input avec hx-get vers /issues/search, hx-trigger="keyup changed delay:300ms", hx-target="#issues-list"
--- la route /issues/search filtre les issues par titre (insensible à la casse) et renvoie uniquement les <tr> correspondants
--Vérifie que taper dans la barre filtre la liste en direct.
--```
--
--**Étape 9 — Persistance SQLite**
--```
--Contexte : projet Go "issue-tracker" avec store en mémoire (internal/store) et CRUD HTMX complet.
--Remplace le store en mémoire par SQLite :
--- utilise la lib modernc.org/sqlite (pure Go, pas besoin de cgo)
--- crée un fichier issues.db, table issues avec les mêmes champs que la struct Issue
--- garde exactement la même interface publique du package store (Create, Get, List, Update, Delete) pour ne rien casser côté routes
--Vérifie que les issues survivent à un redémarrage du serveur.
--```
--
--**Étape 10 — Finitions**
--```
--Contexte : projet Go "issue-tracker" complet (CRUD HTMX + SQLite).
--Ajoute :
--- un fichier web/static/style.css minimal (tableau propre, badges colorés selon le statut : open=vert, in_progress=orange, closed=gris)
--- une route pour servir web/static/
--- un favicon simple si possible
--N'ajoute rien d'autre, pas de nouvelle fonctionnalité.
--```
--

renamed demos/agents-md-file/README.en.md +14 -14 Viewed

similarity index 86%
rename from demo-agents-file/README.en.md
rename to demos/agents-md-file/README.en.md
@@ -22,7 +22,7 @@ All three agents use `hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M`.
22	22	3. Start mm from `project/`: `AGENTS.md` is looked for in the working directory, not next to the configuration file.
23	23
24	24	```bash
25		- cd demo-agents-file/project
	25	+ cd demos/agents-md-file/project
26	26	```
27	27
28	28	## The setting
@@ -39,7 +39,7 @@ agentsMd:
39	39	The model receives its `system` prompt, then:
40	40
41	41	```text
42		-PROJECT INSTRUCTIONS (from /…/demo-agents-file/project/AGENTS.md)
	42	+PROJECT INSTRUCTIONS (from /…/demos/agents-md-file/project/AGENTS.md)
43	43	The instructions of the project you work in. Follow them; when the user asks otherwise in the conversation, the user wins.
44	44
45	45	# Project "Tangerine" — instructions for coding agents
@@ -49,11 +49,11 @@ The instructions of the project you work in. Follow them; when the user asks oth
49	49	## 1. The banner says which file is read
50	50
51	51	```bash
52		-../../mm ../agent.yaml
	52	+../../../mm ../agent.yaml
53	53	```
54	54
55	55	```
56		-mm … \| tools: bash, read_file, write_file, edit_file, ask_agent \| skills: 0 \| yolo: on \| agents.md: /…/demo-agents-file/project/AGENTS.md (~125 tokens)
	56	+mm … \| tools: bash, read_file, write_file, edit_file, ask_agent \| skills: 0 \| yolo: on \| agents.md: /…/demos/agents-md-file/project/AGENTS.md (~125 tokens)
57	57	```
58	58
59	59	(The `no skills found` warning is expected: this demo has no skills.)
@@ -61,7 +61,7 @@ mm … \| tools: bash, read_file, write_file, edit_file, ask_agent \| skills: 0 \|
61	61	## 2. Bob follows the project's instructions
62	62
63	63	```bash
64		-../../mm ../agent.yaml -p "Run the tests."
	64	+../../../mm ../agent.yaml -p "Run the tests."
65	65	```
66	66
67	67	```
@@ -77,7 +77,7 @@ Bob runs `make check`, the command `AGENTS.md` sets, not a guessed one.
77	77
78	78	```bash
79	79	mv AGENTS.md AGENTS.md.off
80		-AGENT_YOLO=false ../../mm ../agent.yaml -p "Run the tests."
	80	+AGENT_YOLO=false ../../../mm ../agent.yaml -p "Run the tests."
81	81	mv AGENTS.md.off AGENTS.md
82	82	```
83	83
@@ -96,7 +96,7 @@ Without instructions the model guesses (here `pytest`, in a project without a li
96	96	When Bob hands a question to another agent (`ask_agent`, `/ask`, `mm --ask`), the asked agent works in the same directory, but its own `agentsMd` setting decides whether it reads the file.
97	97
98	98	```bash
99		-../../mm ../agent.yaml --ask helper -p "How do I run the tests in this project?"
	99	+../../../mm ../agent.yaml --ask helper -p "How do I run the tests in this project?"
100	100	```
101	101
102	102	```
@@ -105,7 +105,7 @@ To run the tests, execute `make check` as instructed by the project's build and
105	105	```
106	106
107	107	```bash
108		-../../mm ../agent.yaml --ask reviewer -p "How do I run the tests in this project?"
	108	+../../../mm ../agent.yaml --ask reviewer -p "How do I run the tests in this project?"
109	109	```
110	110
111	111	```
@@ -119,7 +119,7 @@ helper knows `make check` and signs; reviewer (`agentsMd.enabled: false`) gives
119	119	The file is read at the start of every conversation, never in the middle of one (changing the system message mid-way would make the server re-read the whole history). To take an edit into account:
120	120
121	121	```bash
122		-../../mm ../agent.yaml
	122	+../../../mm ../agent.yaml
123	123	> Run the tests. # make check
124	124	```
125	125
@@ -139,7 +139,7 @@ The new instruction applies from the new conversation on. (In our run Bob then a
139	139	## 5. Check what the model received
140	140
141	141	```bash
142		-AGENT_TRACE=true ../../mm ../agent.yaml -p "Run the tests."
	142	+AGENT_TRACE=true ../../../mm ../agent.yaml -p "Run the tests."
143	143	jq -r '.messages[0].content' .mm/traces/*-0001.request.json
144	144	```
145	145
@@ -149,11 +149,11 @@ The system message ends with the `PROJECT INSTRUCTIONS (from …)` section.
149	149
150	150	- A small model does not follow every rule every time: with Qwen3.5-4B, Bob ran `make check` on every try but left out the `-- Tangerine bot` signature; helper, with no tools, added it. Short, concrete instructions work best.
151	151	- Size: the file rides with every request. The banner warns when it takes 20 % or more of the context window; `agentsMd.maxChars` sets a hard limit (above it the file is skipped whole, and the banner says `skipped (too long)`).
152		-- A JSON agent (`structuredOutput`) never reads `AGENTS.md`; its banner says `agents.md: ignored (structured output)`. See [demo-structured-output](../demo-structured-output/README.en.md).
	152	+- A JSON agent (`structuredOutput`) never reads `AGENTS.md`; its banner says `agents.md: ignored (structured output)`. See [demos/structured-output](../structured-output/README.en.md).
153	153	- In an editor (Zed…, ACP mode), each session reads the `AGENTS.md` of the project it opened.
154	154
155	155	## Further reading
156	156
157		-- [Give the agent your project's instructions](../docs/en/how-to/give-project-instructions.md)
158		-- [`agentsMd` reference](../docs/en/reference/configuration.md#agentsmd-keys)
159		-- [Project instructions — explanation](../docs/en/explanation/project-instructions.md)
	157	+- [Give the agent your project's instructions](../../docs/en/how-to/give-project-instructions.md)
	158	+- [`agentsMd` reference](../../docs/en/reference/configuration.md#agentsmd-keys)
	159	+- [Project instructions — explanation](../../docs/en/explanation/project-instructions.md)

 . **Start mm from `project/`**: `AGENTS.md` is looked for in the working directory, not next to the configuration file.
     ```bash
--   cd demo-agents-file/project
++   cd demos/agents-md-file/project
     ```
  ## The setting
  The model receives its `system` prompt, then:
  ```text
--PROJECT INSTRUCTIONS (from /…/demo-agents-file/project/AGENTS.md)
++PROJECT INSTRUCTIONS (from /…/demos/agents-md-file/project/AGENTS.md)
  The instructions of the project you work in. Follow them; when the user asks otherwise in the conversation, the user wins.
  # Project "Tangerine" — instructions for coding agents
  ## 1. The banner says which file is read
  ```bash
--../../mm ../agent.yaml
++../../../mm ../agent.yaml
  ```
  ```
--mm … | tools: bash, read_file, write_file, edit_file, ask_agent | skills: 0 | yolo: on | agents.md: /…/demo-agents-file/project/AGENTS.md (~125 tokens)
++mm … | tools: bash, read_file, write_file, edit_file, ask_agent | skills: 0 | yolo: on | agents.md: /…/demos/agents-md-file/project/AGENTS.md (~125 tokens)
  ```
  (The `no skills found` warning is expected: this demo has no skills.)
  ## 2. Bob follows the project's instructions
  ```bash
--../../mm ../agent.yaml -p "Run the tests."
++../../../mm ../agent.yaml -p "Run the tests."
  ```
  ```
  ```bash
  mv AGENTS.md AGENTS.md.off
--AGENT_YOLO=false ../../mm ../agent.yaml -p "Run the tests."
++AGENT_YOLO=false ../../../mm ../agent.yaml -p "Run the tests."
  mv AGENTS.md.off AGENTS.md
  ```
  When Bob hands a question to another agent (`ask_agent`, `/ask`, `mm --ask`), the asked agent works in the same directory, but **its own** `agentsMd` setting decides whether it reads the file.
  ```bash
--../../mm ../agent.yaml --ask helper -p "How do I run the tests in this project?"
++../../../mm ../agent.yaml --ask helper -p "How do I run the tests in this project?"
  ```
  ```
  ```
  ```bash
--../../mm ../agent.yaml --ask reviewer -p "How do I run the tests in this project?"
++../../../mm ../agent.yaml --ask reviewer -p "How do I run the tests in this project?"
  ```
  ```
  The file is read **at the start of every conversation**, never in the middle of one (changing the system message mid-way would make the server re-read the whole history). To take an edit into account:
  ```bash
--../../mm ../agent.yaml
++../../../mm ../agent.yaml
  > Run the tests.            # make check
  ```
  ## 5. Check what the model received
  ```bash
--AGENT_TRACE=true ../../mm ../agent.yaml -p "Run the tests."
++AGENT_TRACE=true ../../../mm ../agent.yaml -p "Run the tests."
  jq -r '.messages[0].content' .mm/traces/*-0001.request.json
  ```
  - **A small model does not follow every rule every time**: with Qwen3.5-4B, Bob ran `make check` on every try but left out the `-- Tangerine bot` signature; helper, with no tools, added it. Short, concrete instructions work best.
  - **Size**: the file rides with every request. The banner warns when it takes 20 % or more of the context window; `agentsMd.maxChars` sets a hard limit (above it the file is skipped whole, and the banner says `skipped (too long)`).
--- **A JSON agent** (`structuredOutput`) never reads `AGENTS.md`; its banner says `agents.md: ignored (structured output)`. See [demo-structured-output](../demo-structured-output/README.en.md).
++- **A JSON agent** (`structuredOutput`) never reads `AGENTS.md`; its banner says `agents.md: ignored (structured output)`. See [demos/structured-output](../structured-output/README.en.md).
  - **In an editor** (Zed…, ACP mode), each session reads the `AGENTS.md` of the project it opened.
  ## Further reading
--- [Give the agent your project's instructions](../docs/en/how-to/give-project-instructions.md)
++- [Give the agent your project's instructions](../../docs/en/how-to/give-project-instructions.md)
--- [`agentsMd` reference](../docs/en/reference/configuration.md#agentsmd-keys)
++- [`agentsMd` reference](../../docs/en/reference/configuration.md#agentsmd-keys)
--- [Project instructions — explanation](../docs/en/explanation/project-instructions.md)
++- [Project instructions — explanation](../../docs/en/explanation/project-instructions.md)

renamed demos/agents-md-file/README.md +10 -10 Viewed

similarity index 90%
rename from demo-agents-file/README.md
rename to demos/agents-md-file/README.md
@@ -22,7 +22,7 @@ Les trois agents utilisent `hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M`.
22	22	3. Lancez mm depuis `project/` : `AGENTS.md` est cherché dans le répertoire de travail, pas à côté du fichier de configuration.
23	23
24	24	```bash
25		- cd demo-agents-file/project
	25	+ cd demos/agents-md-file/project
26	26	```
27	27
28	28	## Le réglage
@@ -39,7 +39,7 @@ agentsMd:
39	39	Le modèle reçoit son prompt `system`, puis :
40	40
41	41	```text
42		-PROJECT INSTRUCTIONS (from /…/demo-agents-file/project/AGENTS.md)
	42	+PROJECT INSTRUCTIONS (from /…/demos/agents-md-file/project/AGENTS.md)
43	43	The instructions of the project you work in. Follow them; when the user asks otherwise in the conversation, the user wins.
44	44
45	45	# Project "Tangerine" — instructions for coding agents
@@ -53,7 +53,7 @@ mm ../agent.yaml
53	53	```
54	54
55	55	```
56		-mm … \| tools: bash, read_file, write_file, edit_file, ask_agent \| skills: 0 \| yolo: on \| agents.md: /…/demo-agents-file/project/AGENTS.md (~125 tokens)
	56	+mm … \| tools: bash, read_file, write_file, edit_file, ask_agent \| skills: 0 \| yolo: on \| agents.md: /…/demos/agents-md-file/project/AGENTS.md (~125 tokens)
57	57	```
58	58
59	59	(L'avertissement `no skills found` est normal : cette démo n'a pas de skills.)
@@ -77,7 +77,7 @@ Bob lance `make check`, la commande que fixe `AGENTS.md`, et pas une commande de
77	77
78	78	```bash
79	79	mv AGENTS.md AGENTS.md.off
80		-AGENT_YOLO=false ../../mm ../agent.yaml -p "Run the tests."
	80	+AGENT_YOLO=false ../../../mm ../agent.yaml -p "Run the tests."
81	81	mv AGENTS.md.off AGENTS.md
82	82	```
83	83
@@ -119,7 +119,7 @@ helper connaît `make check` et signe ; reviewer (`agentsMd.enabled: false`) don
119	119	Le fichier est lu au début de chaque conversation, jamais au milieu (changer le message système en cours de route obligerait le serveur à relire tout l'historique). Pour prendre une modification en compte :
120	120
121	121	```bash
122		-../../mm ../agent.yaml
	122	+../../../mm ../agent.yaml
123	123	> Run the tests. # make check
124	124	```
125	125
@@ -139,7 +139,7 @@ La nouvelle consigne s'applique dès la nouvelle conversation. (Lors de notre es
139	139	## 5. Vérifier ce que le modèle a reçu
140	140
141	141	```bash
142		-AGENT_TRACE=true ../../mm ../agent.yaml -p "Run the tests."
	142	+AGENT_TRACE=true ../../../mm ../agent.yaml -p "Run the tests."
143	143	jq -r '.messages[0].content' .mm/traces/*-0001.request.json
144	144	```
145	145
@@ -149,11 +149,11 @@ Le message système se termine par la section `PROJECT INSTRUCTIONS (from …)`.
149	149
150	150	- Un petit modèle ne suit pas toutes les règles à chaque fois : avec Qwen3.5-4B, Bob a lancé `make check` à chaque essai, mais a oublié la signature `-- Tangerine bot` ; helper, sans outils, l'a mise. Des consignes courtes et concrètes passent mieux.
151	151	- Taille : le fichier part avec chaque requête. La bannière avertit quand il occupe 20 % ou plus de la fenêtre de contexte ; `agentsMd.maxChars` fixe une limite ferme (au-delà, il est ignoré en entier, et la bannière l'indique `skipped (too long)`).
152		-- Un agent JSON (`structuredOutput`) ne lit jamais `AGENTS.md` ; sa bannière indique `agents.md: ignored (structured output)`. Voir [demo-structured-output](../demo-structured-output/README.md).
	152	+- Un agent JSON (`structuredOutput`) ne lit jamais `AGENTS.md` ; sa bannière indique `agents.md: ignored (structured output)`. Voir [demos/structured-output](../structured-output/README.md).
153	153	- Dans un éditeur (Zed…, mode ACP), chaque session lit le `AGENTS.md` du projet ouvert.
154	154
155	155	## Pour aller plus loin
156	156
157		-- [Donner à l'agent les consignes de votre projet](../docs/fr/how-to/give-project-instructions.md)
158		-- [Référence de `agentsMd`](../docs/fr/reference/configuration.md#clés-de-agentsmd)
159		-- [Consignes du projet — explication](../docs/fr/explanation/project-instructions.md)
	157	+- [Donner à l'agent les consignes de votre projet](../../docs/fr/how-to/give-project-instructions.md)
	158	+- [Référence de `agentsMd`](../../docs/fr/reference/configuration.md#clés-de-agentsmd)
	159	+- [Consignes du projet — explication](../../docs/fr/explanation/project-instructions.md)

 . **Lancez mm depuis `project/`** : `AGENTS.md` est cherché dans le répertoire de travail, pas à côté du fichier de configuration.
     ```bash
--   cd demo-agents-file/project
++   cd demos/agents-md-file/project
     ```
  ## Le réglage
  Le modèle reçoit son prompt `system`, puis :
  ```text
--PROJECT INSTRUCTIONS (from /…/demo-agents-file/project/AGENTS.md)
++PROJECT INSTRUCTIONS (from /…/demos/agents-md-file/project/AGENTS.md)
  The instructions of the project you work in. Follow them; when the user asks otherwise in the conversation, the user wins.
  # Project "Tangerine" — instructions for coding agents
  ```
  ```
--mm … | tools: bash, read_file, write_file, edit_file, ask_agent | skills: 0 | yolo: on | agents.md: /…/demo-agents-file/project/AGENTS.md (~125 tokens)
++mm … | tools: bash, read_file, write_file, edit_file, ask_agent | skills: 0 | yolo: on | agents.md: /…/demos/agents-md-file/project/AGENTS.md (~125 tokens)
  ```
  (L'avertissement `no skills found` est normal : cette démo n'a pas de skills.)
  ```bash
  mv AGENTS.md AGENTS.md.off
--AGENT_YOLO=false ../../mm ../agent.yaml -p "Run the tests."
++AGENT_YOLO=false ../../../mm ../agent.yaml -p "Run the tests."
  mv AGENTS.md.off AGENTS.md
  ```
  Le fichier est lu **au début de chaque conversation**, jamais au milieu (changer le message système en cours de route obligerait le serveur à relire tout l'historique). Pour prendre une modification en compte :
  ```bash
--../../mm ../agent.yaml
++../../../mm ../agent.yaml
  > Run the tests.            # make check
  ```
  ## 5. Vérifier ce que le modèle a reçu
  ```bash
--AGENT_TRACE=true ../../mm ../agent.yaml -p "Run the tests."
++AGENT_TRACE=true ../../../mm ../agent.yaml -p "Run the tests."
  jq -r '.messages[0].content' .mm/traces/*-0001.request.json
  ```
  - **Un petit modèle ne suit pas toutes les règles à chaque fois** : avec Qwen3.5-4B, Bob a lancé `make check` à chaque essai, mais a oublié la signature `-- Tangerine bot` ; helper, sans outils, l'a mise. Des consignes courtes et concrètes passent mieux.
  - **Taille** : le fichier part avec chaque requête. La bannière avertit quand il occupe 20 % ou plus de la fenêtre de contexte ; `agentsMd.maxChars` fixe une limite ferme (au-delà, il est ignoré en entier, et la bannière l'indique `skipped (too long)`).
--- **Un agent JSON** (`structuredOutput`) ne lit jamais `AGENTS.md` ; sa bannière indique `agents.md: ignored (structured output)`. Voir [demo-structured-output](../demo-structured-output/README.md).
++- **Un agent JSON** (`structuredOutput`) ne lit jamais `AGENTS.md` ; sa bannière indique `agents.md: ignored (structured output)`. Voir [demos/structured-output](../structured-output/README.md).
  - **Dans un éditeur** (Zed…, mode ACP), chaque session lit le `AGENTS.md` du projet ouvert.
  ## Pour aller plus loin
--- [Donner à l'agent les consignes de votre projet](../docs/fr/how-to/give-project-instructions.md)
++- [Donner à l'agent les consignes de votre projet](../../docs/fr/how-to/give-project-instructions.md)
--- [Référence de `agentsMd`](../docs/fr/reference/configuration.md#clés-de-agentsmd)
++- [Référence de `agentsMd`](../../docs/fr/reference/configuration.md#clés-de-agentsmd)
--- [Consignes du projet — explication](../docs/fr/explanation/project-instructions.md)
++- [Consignes du projet — explication](../../docs/fr/explanation/project-instructions.md)

renamed demos/agents-md-file/agent.helper.yaml +0 -0 Viewed

similarity index 100%
rename from demo-agents-file/agent.helper.yaml
rename to demos/agents-md-file/agent.helper.yaml

similarity index 100%
rename from demo-agents-file/agent.helper.yaml
rename to demos/agents-md-file/agent.helper.yaml

renamed demos/agents-md-file/agent.reviewer.yaml +0 -0 Viewed

similarity index 100%
rename from demo-agents-file/agent.reviewer.yaml
rename to demos/agents-md-file/agent.reviewer.yaml

similarity index 100%
rename from demo-agents-file/agent.reviewer.yaml
rename to demos/agents-md-file/agent.reviewer.yaml

renamed demos/agents-md-file/agent.yaml +2 -2 Viewed

similarity index 96%
rename from demo-agents-file/agent.yaml
rename to demos/agents-md-file/agent.yaml
@@ -1,8 +1,8 @@
1	1	# Agent settings — Bob, a coding agent that follows the AGENTS.md of the
2	2	# project it works in (ticket 81). Run him FROM THE PROJECT directory:
3	3	#
4		-# cd demo-agents-file/project
5		-# ../../mm ../agent.yaml
	4	+# cd demos/agents-md-file/project
	5	+# ../../../mm ../agent.yaml
6	6	#
7	7	# The banner then shows: agents.md: …/project/AGENTS.md (~N tokens)
8	8	provider: llmman

  # Agent settings — Bob, a coding agent that follows the AGENTS.md of the
  # project it works in (ticket 81). Run him FROM THE PROJECT directory:
  #
--#   cd demo-agents-file/project
++#   cd demos/agents-md-file/project
--#   ../../mm ../agent.yaml
++#   ../../../mm ../agent.yaml
  #
  # The banner then shows: agents.md: …/project/AGENTS.md (~N tokens)
  provider: llmman

renamed demos/agents-md-file/project/AGENTS.md +0 -0 Viewed

similarity index 100%
rename from demo-agents-file/project/AGENTS.md
rename to demos/agents-md-file/project/AGENTS.md

similarity index 100%
rename from demo-agents-file/project/AGENTS.md
rename to demos/agents-md-file/project/AGENTS.md

renamed demos/agents-md-file/project/Makefile +0 -0 Viewed

similarity index 100%
rename from demo-agents-file/project/Makefile
rename to demos/agents-md-file/project/Makefile

similarity index 100%
rename from demo-agents-file/project/Makefile
rename to demos/agents-md-file/project/Makefile

renamed demos/agents-md-file/project/greet.sh +0 -0 Viewed

similarity index 100%
rename from demo-agents-file/project/greet.sh
rename to demos/agents-md-file/project/greet.sh

similarity index 100%
rename from demo-agents-file/project/greet.sh
rename to demos/agents-md-file/project/greet.sh

renamed demos/dmr/MCP-GITHUB-SBX.en.md +0 -0 Viewed

similarity index 100%
rename from demo-dmr/MCP-GITHUB-SBX.en.md
rename to demos/dmr/MCP-GITHUB-SBX.en.md

similarity index 100%
rename from demo-dmr/MCP-GITHUB-SBX.en.md
rename to demos/dmr/MCP-GITHUB-SBX.en.md

renamed demos/dmr/MCP-GITHUB-SBX.fr.md +0 -0 Viewed

similarity index 100%
rename from demo-dmr/MCP-GITHUB-SBX.md
rename to demos/dmr/MCP-GITHUB-SBX.fr.md

similarity index 100%
rename from demo-dmr/MCP-GITHUB-SBX.md
rename to demos/dmr/MCP-GITHUB-SBX.fr.md

renamed demos/dmr/MCP-GITHUB.en.md +0 -0 Viewed

similarity index 100%
rename from demo-dmr/MCP-GITHUB.en.md
rename to demos/dmr/MCP-GITHUB.en.md

similarity index 100%
rename from demo-dmr/MCP-GITHUB.en.md
rename to demos/dmr/MCP-GITHUB.en.md

renamed demos/dmr/MCP-GITHUB.fr.md +0 -0 Viewed

similarity index 100%
rename from demo-dmr/MCP-GITHUB.md
rename to demos/dmr/MCP-GITHUB.fr.md

similarity index 100%
rename from demo-dmr/MCP-GITHUB.md
rename to demos/dmr/MCP-GITHUB.fr.md

renamed demos/dmr/README.md +0 -3 Viewed

similarity index 96%
rename from demo-dmr/README.md
rename to demos/dmr/README.md
@@ -39,6 +39,3 @@ The `agent.dmr.mcp.yaml` file includes configuration for:
39	39	- Wikipedia MCP - Full Wikipedia access (no authentication required)
40	40	- DuckDuckGo MCP (HasData) - Web search via HasData (requires HASDATA_API_KEY, 1,000 free credits/month = 100 searches) - currently commented out
41	41
42		-## License
43		-
44		-This project is licensed under the WTF License.

  - **Wikipedia MCP** - Full Wikipedia access (no authentication required)
  - **DuckDuckGo MCP (HasData)** - Web search via HasData (requires HASDATA_API_KEY, 1,000 free credits/month = 100 searches) - *currently commented out*
--## License
--
--This project is licensed under the WTF License.

renamed demos/dmr/agent.dmr.2.yaml +0 -0 Viewed

similarity index 100%
rename from demo-dmr/agent.dmr.2.yaml
rename to demos/dmr/agent.dmr.2.yaml

similarity index 100%
rename from demo-dmr/agent.dmr.2.yaml
rename to demos/dmr/agent.dmr.2.yaml

renamed demos/dmr/agent.dmr.github-oauth.yaml +0 -0 Viewed

similarity index 100%
rename from demo-dmr/agent.dmr.github-oauth.yaml
rename to demos/dmr/agent.dmr.github-oauth.yaml

similarity index 100%
rename from demo-dmr/agent.dmr.github-oauth.yaml
rename to demos/dmr/agent.dmr.github-oauth.yaml

renamed demos/dmr/agent.dmr.mcp.yaml +0 -0 Viewed

similarity index 100%
rename from demo-dmr/agent.dmr.mcp.yaml
rename to demos/dmr/agent.dmr.mcp.yaml

similarity index 100%
rename from demo-dmr/agent.dmr.mcp.yaml
rename to demos/dmr/agent.dmr.mcp.yaml

renamed demos/dmr/agent.dmr.sbx.yaml +0 -0 Viewed

similarity index 100%
rename from demo-dmr/agent.dmr.sbx.yaml
rename to demos/dmr/agent.dmr.sbx.yaml

similarity index 100%
rename from demo-dmr/agent.dmr.sbx.yaml
rename to demos/dmr/agent.dmr.sbx.yaml

renamed demos/dmr/agent.dmr.yaml +0 -0 Viewed

similarity index 100%
rename from demo-dmr/agent.dmr.yaml
rename to demos/dmr/agent.dmr.yaml

similarity index 100%
rename from demo-dmr/agent.dmr.yaml
rename to demos/dmr/agent.dmr.yaml

renamed demos/dmr/agent.lsp.yaml +0 -0 Viewed

similarity index 100%
rename from demo-dmr/agent.lsp.yaml
rename to demos/dmr/agent.lsp.yaml

similarity index 100%
rename from demo-dmr/agent.lsp.yaml
rename to demos/dmr/agent.lsp.yaml

renamed demos/dmr/config_explanation.md +0 -0 Viewed

similarity index 100%
rename from demo-dmr/config_explanation.md
rename to demos/dmr/config_explanation.md

similarity index 100%
rename from demo-dmr/config_explanation.md
rename to demos/dmr/config_explanation.md

renamed demos/dmr/main.go +0 -0 Viewed

similarity index 100%
rename from demo-dmr/main.go
rename to demos/dmr/main.go

similarity index 100%
rename from demo-dmr/main.go
rename to demos/dmr/main.go

renamed demos/dmr/skills/README.md +0 -0 Viewed

similarity index 100%
rename from demo-dmr/skills/README.md
rename to demos/dmr/skills/README.md

similarity index 100%
rename from demo-dmr/skills/README.md
rename to demos/dmr/skills/README.md

renamed demos/dmr/skills/bg-jobs/SKILL.md +0 -0 Viewed

similarity index 100%
rename from demo-dmr/skills/bg-jobs/SKILL.md
rename to demos/dmr/skills/bg-jobs/SKILL.md

similarity index 100%
rename from demo-dmr/skills/bg-jobs/SKILL.md
rename to demos/dmr/skills/bg-jobs/SKILL.md

renamed demos/dmr/skills/greetings/SKILL.md +0 -0 Viewed

similarity index 100%
rename from demo-dmr/skills/greetings/SKILL.md
rename to demos/dmr/skills/greetings/SKILL.md

similarity index 100%
rename from demo-dmr/skills/greetings/SKILL.md
rename to demos/dmr/skills/greetings/SKILL.md

renamed demos/dmr/skills/lsp-navigation/SKILL.md +0 -0 Viewed

similarity index 100%
rename from demo-dmr/skills/lsp-navigation/SKILL.md
rename to demos/dmr/skills/lsp-navigation/SKILL.md

similarity index 100%
rename from demo-dmr/skills/lsp-navigation/SKILL.md
rename to demos/dmr/skills/lsp-navigation/SKILL.md

renamed demos/dmr/skills/vulcan-salute/SKILL.md +0 -0 Viewed

similarity index 100%
rename from demo-dmr/skills/vulcan-salute/SKILL.md
rename to demos/dmr/skills/vulcan-salute/SKILL.md

similarity index 100%
rename from demo-dmr/skills/vulcan-salute/SKILL.md
rename to demos/dmr/skills/vulcan-salute/SKILL.md

renamed demos/dmr/skills/what-time-is-it/SKILL.md +0 -0 Viewed

similarity index 100%
rename from demo-dmr/skills/what-time-is-it/SKILL.md
rename to demos/dmr/skills/what-time-is-it/SKILL.md

similarity index 100%
rename from demo-dmr/skills/what-time-is-it/SKILL.md
rename to demos/dmr/skills/what-time-is-it/SKILL.md

renamed demos/llmman/README.en.md +15 -15 Viewed

similarity index 84%
rename from demo-llmman/README.en.md
rename to demos/llmman/README.en.md
@@ -1,6 +1,6 @@
1	1	# mini-me + llmman demo: asking other agents
2	2
3		-This folder shows how one mini-me agent (Bob) can put questions to other mini-me agents — Jan, Lucy, a reviewer — each with its own model, served by [llmman](https://github.com/llmmanorg/llmman). Version française : [README.md](README.md).
	3	+This folder shows how one mini-me agent (Bob) can put questions to other mini-me agents — Jan, Lucy, a reviewer — each with its own model, served by [llmman](https://github.com/llmmanorg/llmman). Version française : [README.fr.md](README.fr.md).
4	4
5	5	## What is here
6	6
@@ -42,9 +42,9 @@ mmConfigs:
42	42	3. `mm` built at the repository root. Start it from this folder: the `mmConfigs` paths are relative to `agent.llmman.yaml`, and `skillsDir: skills` to the current directory.
43	43
44	44	```bash
45		- cd demo-llmman
46		- ../mm agent.llmman.yaml # line mode
47		- ../mm -tui agent.llmman.yaml # window mode
	45	+ cd demos/llmman
	46	+ ../../mm agent.llmman.yaml # line mode
	47	+ ../../mm -tui agent.llmman.yaml # window mode
48	48	```
49	49
50	50	## 1. Ask an agent from the conversation: `/ask`
@@ -77,18 +77,18 @@ The capital of France is Paris.
77	77	For a script, or to try an agent without opening a session:
78	78
79	79	```bash
80		-../mm agent.llmman.yaml --ask lucy -p "In one short sentence: what is the capital of Peru?"
	80	+../../mm agent.llmman.yaml --ask lucy -p "In one short sentence: what is the capital of Peru?"
81	81	# stdout: The capital of Peru is Lima.
82	82
83		-echo "In one sentence: are goroutines OS threads?" \| ../mm agent.llmman.yaml --ask reviewer
	83	+echo "In one sentence: are goroutines OS threads?" \| ../../mm agent.llmman.yaml --ask reviewer
84	84
85	85	printf 'User: My name is Philippe and I like Go.\nAssistant: Nice to meet you, Philippe.\n---\nWhat is my name and which language do I like? One sentence.\n' \
86		- \| ../mm agent.llmman.yaml --ask-with-context jan
	86	+ \| ../../mm agent.llmman.yaml --ask-with-context jan
87	87	# stdout: Your name is Philippe, and you like Go.
88	88	```
89	89
90	90	- The question comes from `-p`, or else from stdin. For `--ask-with-context`, stdin is the context; without `-p`, the context, a `---` line, then the question.
91		-- stdout holds the answer only (`answer=$(../mm agent.llmman.yaml --ask jan -p "…")` works); the label, the tool calls and errors go to stderr.
	91	+- stdout holds the answer only (`answer=$(../../mm agent.llmman.yaml --ask jan -p "…")` works); the label, the tool calls and errors go to stderr.
92	92	- Exit codes: `0` answered, `1` failed (reason on stderr, e.g. `[ask: unknown agent "spock" — agents in this config: jan, lucy, reviewer]`), `130` interrupted.
93	93	- The asked agent's tool calls follow its `mmConfigs` entry's `yolo` (Lucy: `true`, they run), else `agent.llmman.yaml`'s (`false`: rejected, nobody can answer). For an agent that should only answer, use `reviewer`.
94	94
@@ -102,7 +102,7 @@ Since `mmConfigs` is not empty, Bob has the built-in `ask_agent` tool. Its descr
102	102	\| "I think Go's goroutines are OS threads. Get a second opinion on that claim." \| `ask_agent` → `reviewer`, with `with_context` \|
103	103	\| "Ask Lucy to add a test for main.go and run it." \| `ask_agent` → `lucy`, whose writes and commands run without asking (`yolo: true` in her entry) \|
104	104
105		-Bob has `yolo: false`: you approve each hand-off first, with the prompt he wrote. In the window (`../mm -tui agent.llmman.yaml`), the asked agent is named while it works:
	105	+Bob has `yolo: false`: you approve each hand-off first, with the prompt he wrote. In the window (`../../mm -tui agent.llmman.yaml`), the asked agent is named while it works:
106	106
107	107	```text
108	108	mm [Jan (coding agent)] · Jan-nano:Q4_K_M @ llmman · asked by mm [Bob (coordinator)]
@@ -138,9 +138,9 @@ With `ask_agent`, only a long silence of the asked agent (its model loading, a l
138	138
139	139	## Going further
140	140
141		-- [How to ask another mm agent from your session](../docs/en/how-to/ask-another-agent.md)
142		-- [How to let your agent call other agents](../docs/en/how-to/let-the-agent-call-other-agents.md)
143		-- [How to ask another agent from a skill or a script](../docs/en/how-to/ask-another-agent-from-a-skill.md)
144		-- [Slash commands reference](../docs/en/reference/slash-commands.md#asking-another-agent) · [Command-line reference](../docs/en/reference/cli.md#ask-mode-specifics)
145		-- [Why it is built this way](../docs/en/explanation/asking-another-agent.md)
146		-- [Run mini-me on llmman](../docs/en/how-to/run-with-llmman.md)
	141	+- [How to ask another mm agent from your session](../../docs/en/how-to/ask-another-agent.md)
	142	+- [How to let your agent call other agents](../../docs/en/how-to/let-the-agent-call-other-agents.md)
	143	+- [How to ask another agent from a skill or a script](../../docs/en/how-to/ask-another-agent-from-a-skill.md)
	144	+- [Slash commands reference](../../docs/en/reference/slash-commands.md#asking-another-agent) · [Command-line reference](../../docs/en/reference/cli.md#ask-mode-specifics)
	145	+- [Why it is built this way](../../docs/en/explanation/asking-another-agent.md)
	146	+- [Run mini-me on llmman](../../docs/en/how-to/run-with-llmman.md)

  # mini-me + llmman demo: asking other agents
--This folder shows how one mini-me agent (Bob) can put questions to other mini-me agents — Jan, Lucy, a reviewer — each with its own model, served by [llmman](https://github.com/llmmanorg/llmman). Version française : [README.md](README.md).
++This folder shows how one mini-me agent (Bob) can put questions to other mini-me agents — Jan, Lucy, a reviewer — each with its own model, served by [llmman](https://github.com/llmmanorg/llmman). Version française : [README.fr.md](README.fr.md).
  ## What is here
 . `mm` built at the repository root. **Start it from this folder**: the `mmConfigs` paths are relative to `agent.llmman.yaml`, and `skillsDir: skills` to the current directory.
     ```bash
--   cd demo-llmman
++   cd demos/llmman
--   ../mm agent.llmman.yaml          # line mode
++   ../../mm agent.llmman.yaml          # line mode
--   ../mm -tui agent.llmman.yaml     # window mode
++   ../../mm -tui agent.llmman.yaml     # window mode
     ```
  ## 1. Ask an agent from the conversation: `/ask`
  For a script, or to try an agent without opening a session:
  ```bash
--../mm agent.llmman.yaml --ask lucy -p "In one short sentence: what is the capital of Peru?"
++../../mm agent.llmman.yaml --ask lucy -p "In one short sentence: what is the capital of Peru?"
  # stdout: The capital of Peru is Lima.
--echo "In one sentence: are goroutines OS threads?" | ../mm agent.llmman.yaml --ask reviewer
++echo "In one sentence: are goroutines OS threads?" | ../../mm agent.llmman.yaml --ask reviewer
  printf 'User: My name is Philippe and I like Go.\nAssistant: Nice to meet you, Philippe.\n---\nWhat is my name and which language do I like? One sentence.\n' \
--  | ../mm agent.llmman.yaml --ask-with-context jan
++  | ../../mm agent.llmman.yaml --ask-with-context jan
  # stdout: Your name is Philippe, and you like Go.
  ```
  - The question comes from `-p`, or else from stdin. For `--ask-with-context`, stdin is the context; without `-p`, the context, a `---` line, then the question.
--- **stdout holds the answer only** (`answer=$(../mm agent.llmman.yaml --ask jan -p "…")` works); the label, the tool calls and errors go to stderr.
++- **stdout holds the answer only** (`answer=$(../../mm agent.llmman.yaml --ask jan -p "…")` works); the label, the tool calls and errors go to stderr.
  - Exit codes: `0` answered, `1` failed (reason on stderr, e.g. `[ask: unknown agent "spock" — agents in this config: jan, lucy, reviewer]`), `130` interrupted.
  - The asked agent's tool calls follow its `mmConfigs` entry's `yolo` (Lucy: `true`, they run), else `agent.llmman.yaml`'s (`false`: rejected, nobody can answer). For an agent that should only answer, use `reviewer`.
  | "I think Go's goroutines are OS threads. Get a second opinion on that claim." | `ask_agent` → `reviewer`, with `with_context` |
  | "Ask Lucy to add a test for main.go and run it." | `ask_agent` → `lucy`, whose writes and commands run without asking (`yolo: true` in her entry) |
--Bob has `yolo: false`: you approve each hand-off first, with the prompt he wrote. In the window (`../mm -tui agent.llmman.yaml`), the asked agent is named while it works:
++Bob has `yolo: false`: you approve each hand-off first, with the prompt he wrote. In the window (`../../mm -tui agent.llmman.yaml`), the asked agent is named while it works:
  ```text
  mm [Jan (coding agent)] · Jan-nano:Q4_K_M @ llmman · asked by mm [Bob (coordinator)]
  ## Going further
--- [How to ask another mm agent from your session](../docs/en/how-to/ask-another-agent.md)
++- [How to ask another mm agent from your session](../../docs/en/how-to/ask-another-agent.md)
--- [How to let your agent call other agents](../docs/en/how-to/let-the-agent-call-other-agents.md)
++- [How to let your agent call other agents](../../docs/en/how-to/let-the-agent-call-other-agents.md)
--- [How to ask another agent from a skill or a script](../docs/en/how-to/ask-another-agent-from-a-skill.md)
++- [How to ask another agent from a skill or a script](../../docs/en/how-to/ask-another-agent-from-a-skill.md)
--- [Slash commands reference](../docs/en/reference/slash-commands.md#asking-another-agent) · [Command-line reference](../docs/en/reference/cli.md#ask-mode-specifics)
++- [Slash commands reference](../../docs/en/reference/slash-commands.md#asking-another-agent) · [Command-line reference](../../docs/en/reference/cli.md#ask-mode-specifics)
--- [Why it is built this way](../docs/en/explanation/asking-another-agent.md)
++- [Why it is built this way](../../docs/en/explanation/asking-another-agent.md)
--- [Run mini-me on llmman](../docs/en/how-to/run-with-llmman.md)
++- [Run mini-me on llmman](../../docs/en/how-to/run-with-llmman.md)

renamed demos/llmman/README.fr.md +14 -14 Viewed

similarity index 86%
rename from demo-llmman/README.md
rename to demos/llmman/README.fr.md
@@ -42,9 +42,9 @@ mmConfigs:
42	42	3. `mm` compilé à la racine du dépôt. Lancez-le depuis ce dossier : les chemins de `mmConfigs` sont relatifs à `agent.llmman.yaml`, et `skillsDir: skills` au dossier courant.
43	43
44	44	```bash
45		- cd demo-llmman
46		- ../mm agent.llmman.yaml # mode ligne
47		- ../mm -tui agent.llmman.yaml # mode fenêtre
	45	+ cd demos/llmman
	46	+ ../../mm agent.llmman.yaml # mode ligne
	47	+ ../../mm -tui agent.llmman.yaml # mode fenêtre
48	48	```
49	49
50	50	## 1. Interroger un agent depuis la conversation : `/ask`
@@ -77,18 +77,18 @@ The capital of France is Paris.
77	77	Pour un script, ou pour tester un agent sans ouvrir de session :
78	78
79	79	```bash
80		-../mm agent.llmman.yaml --ask lucy -p "In one short sentence: what is the capital of Peru?"
	80	+../../mm agent.llmman.yaml --ask lucy -p "In one short sentence: what is the capital of Peru?"
81	81	# stdout : The capital of Peru is Lima.
82	82
83		-echo "In one sentence: are goroutines OS threads?" \| ../mm agent.llmman.yaml --ask reviewer
	83	+echo "In one sentence: are goroutines OS threads?" \| ../../mm agent.llmman.yaml --ask reviewer
84	84
85	85	printf 'User: My name is Philippe and I like Go.\nAssistant: Nice to meet you, Philippe.\n---\nWhat is my name and which language do I like? One sentence.\n' \
86		- \| ../mm agent.llmman.yaml --ask-with-context jan
	86	+ \| ../../mm agent.llmman.yaml --ask-with-context jan
87	87	# stdout : Your name is Philippe, and you like Go.
88	88	```
89	89
90	90	- La question vient de `-p`, sinon de stdin. Pour `--ask-with-context`, stdin contient le contexte ; sans `-p`, le contexte, une ligne `---`, puis la question.
91		-- stdout ne contient que la réponse (`answer=$(../mm agent.llmman.yaml --ask jan -p "…")` marche) ; l'en-tête, les appels d'outils et les erreurs vont sur stderr.
	91	+- stdout ne contient que la réponse (`answer=$(../../mm agent.llmman.yaml --ask jan -p "…")` marche) ; l'en-tête, les appels d'outils et les erreurs vont sur stderr.
92	92	- Codes de sortie : `0` réponse obtenue, `1` échec (raison sur stderr, par exemple `[ask: unknown agent "spock" — agents in this config: jan, lucy, reviewer]`), `130` interrompu.
93	93	- Les appels d'outils de l'agent appelé suivent le `yolo` de son entrée dans `mmConfigs` (Lucy : `true`, ils s'exécutent), sinon celui de `agent.llmman.yaml` (`false` : refusés, personne ne peut répondre). Pour un agent qui doit seulement répondre, utilisez `reviewer`.
94	94
@@ -102,7 +102,7 @@ Comme `mmConfigs` n'est pas vide, Bob dispose de l'outil intégré `ask_agent`.
102	102	\| « I think Go's goroutines are OS threads. Get a second opinion on that claim. » \| `ask_agent` → `reviewer`, avec `with_context` \|
103	103	\| « Ask Lucy to add a test for main.go and run it. » \| `ask_agent` → `lucy`, dont les écritures et commandes s'exécutent sans demander (`yolo: true` dans son entrée) \|
104	104
105		-Bob a `yolo: false` : vous approuvez d'abord chaque passage de main, avec le prompt qu'il a écrit. Dans la fenêtre (`../mm -tui agent.llmman.yaml`), l'agent appelé est nommé pendant qu'il travaille :
	105	+Bob a `yolo: false` : vous approuvez d'abord chaque passage de main, avec le prompt qu'il a écrit. Dans la fenêtre (`../../mm -tui agent.llmman.yaml`), l'agent appelé est nommé pendant qu'il travaille :
106	106
107	107	```text
108	108	mm [Jan (coding agent)] · Jan-nano:Q4_K_M @ llmman · asked by mm [Bob (coordinator)]
@@ -138,9 +138,9 @@ Avec `ask_agent`, seul un long silence de l'agent appelé (le chargement de son
138	138
139	139	## Pour aller plus loin
140	140
141		-- [Comment interroger un autre agent mm depuis votre session](../docs/fr/how-to/ask-another-agent.md)
142		-- [Comment laisser votre agent appeler d'autres agents](../docs/fr/how-to/let-the-agent-call-other-agents.md)
143		-- [Comment interroger un autre agent depuis une skill ou un script](../docs/fr/how-to/ask-another-agent-from-a-skill.md)
144		-- [Référence des commandes slash](../docs/fr/reference/slash-commands.md#interroger-un-autre-agent) · [Référence de la ligne de commande](../docs/fr/reference/cli.md#spécificités-du-mode-ask)
145		-- [Pourquoi c'est construit ainsi](../docs/fr/explanation/asking-another-agent.md)
146		-- [Faire tourner mini-me sur llmman](../docs/fr/how-to/run-with-llmman.md)
	141	+- [Comment interroger un autre agent mm depuis votre session](../../docs/fr/how-to/ask-another-agent.md)
	142	+- [Comment laisser votre agent appeler d'autres agents](../../docs/fr/how-to/let-the-agent-call-other-agents.md)
	143	+- [Comment interroger un autre agent depuis une skill ou un script](../../docs/fr/how-to/ask-another-agent-from-a-skill.md)
	144	+- [Référence des commandes slash](../../docs/fr/reference/slash-commands.md#interroger-un-autre-agent) · [Référence de la ligne de commande](../../docs/fr/reference/cli.md#spécificités-du-mode-ask)
	145	+- [Pourquoi c'est construit ainsi](../../docs/fr/explanation/asking-another-agent.md)
	146	+- [Faire tourner mini-me sur llmman](../../docs/fr/how-to/run-with-llmman.md)

 . `mm` compilé à la racine du dépôt. **Lancez-le depuis ce dossier** : les chemins de `mmConfigs` sont relatifs à `agent.llmman.yaml`, et `skillsDir: skills` au dossier courant.
     ```bash
--   cd demo-llmman
++   cd demos/llmman
--   ../mm agent.llmman.yaml          # mode ligne
++   ../../mm agent.llmman.yaml          # mode ligne
--   ../mm -tui agent.llmman.yaml     # mode fenêtre
++   ../../mm -tui agent.llmman.yaml     # mode fenêtre
     ```
  ## 1. Interroger un agent depuis la conversation : `/ask`
  Pour un script, ou pour tester un agent sans ouvrir de session :
  ```bash
--../mm agent.llmman.yaml --ask lucy -p "In one short sentence: what is the capital of Peru?"
++../../mm agent.llmman.yaml --ask lucy -p "In one short sentence: what is the capital of Peru?"
  # stdout : The capital of Peru is Lima.
--echo "In one sentence: are goroutines OS threads?" | ../mm agent.llmman.yaml --ask reviewer
++echo "In one sentence: are goroutines OS threads?" | ../../mm agent.llmman.yaml --ask reviewer
  printf 'User: My name is Philippe and I like Go.\nAssistant: Nice to meet you, Philippe.\n---\nWhat is my name and which language do I like? One sentence.\n' \
--  | ../mm agent.llmman.yaml --ask-with-context jan
++  | ../../mm agent.llmman.yaml --ask-with-context jan
  # stdout : Your name is Philippe, and you like Go.
  ```
  - La question vient de `-p`, sinon de stdin. Pour `--ask-with-context`, stdin contient le contexte ; sans `-p`, le contexte, une ligne `---`, puis la question.
--- **stdout ne contient que la réponse** (`answer=$(../mm agent.llmman.yaml --ask jan -p "…")` marche) ; l'en-tête, les appels d'outils et les erreurs vont sur stderr.
++- **stdout ne contient que la réponse** (`answer=$(../../mm agent.llmman.yaml --ask jan -p "…")` marche) ; l'en-tête, les appels d'outils et les erreurs vont sur stderr.
  - Codes de sortie : `0` réponse obtenue, `1` échec (raison sur stderr, par exemple `[ask: unknown agent "spock" — agents in this config: jan, lucy, reviewer]`), `130` interrompu.
  - Les appels d'outils de l'agent appelé suivent le `yolo` de son entrée dans `mmConfigs` (Lucy : `true`, ils s'exécutent), sinon celui de `agent.llmman.yaml` (`false` : refusés, personne ne peut répondre). Pour un agent qui doit seulement répondre, utilisez `reviewer`.
  | « I think Go's goroutines are OS threads. Get a second opinion on that claim. » | `ask_agent` → `reviewer`, avec `with_context` |
  | « Ask Lucy to add a test for main.go and run it. » | `ask_agent` → `lucy`, dont les écritures et commandes s'exécutent sans demander (`yolo: true` dans son entrée) |
--Bob a `yolo: false` : vous approuvez d'abord chaque passage de main, avec le prompt qu'il a écrit. Dans la fenêtre (`../mm -tui agent.llmman.yaml`), l'agent appelé est nommé pendant qu'il travaille :
++Bob a `yolo: false` : vous approuvez d'abord chaque passage de main, avec le prompt qu'il a écrit. Dans la fenêtre (`../../mm -tui agent.llmman.yaml`), l'agent appelé est nommé pendant qu'il travaille :
  ```text
  mm [Jan (coding agent)] · Jan-nano:Q4_K_M @ llmman · asked by mm [Bob (coordinator)]
  ## Pour aller plus loin
--- [Comment interroger un autre agent mm depuis votre session](../docs/fr/how-to/ask-another-agent.md)
++- [Comment interroger un autre agent mm depuis votre session](../../docs/fr/how-to/ask-another-agent.md)
--- [Comment laisser votre agent appeler d'autres agents](../docs/fr/how-to/let-the-agent-call-other-agents.md)
++- [Comment laisser votre agent appeler d'autres agents](../../docs/fr/how-to/let-the-agent-call-other-agents.md)
--- [Comment interroger un autre agent depuis une skill ou un script](../docs/fr/how-to/ask-another-agent-from-a-skill.md)
++- [Comment interroger un autre agent depuis une skill ou un script](../../docs/fr/how-to/ask-another-agent-from-a-skill.md)
--- [Référence des commandes slash](../docs/fr/reference/slash-commands.md#interroger-un-autre-agent) · [Référence de la ligne de commande](../docs/fr/reference/cli.md#spécificités-du-mode-ask)
++- [Référence des commandes slash](../../docs/fr/reference/slash-commands.md#interroger-un-autre-agent) · [Référence de la ligne de commande](../../docs/fr/reference/cli.md#spécificités-du-mode-ask)
--- [Pourquoi c'est construit ainsi](../docs/fr/explanation/asking-another-agent.md)
++- [Pourquoi c'est construit ainsi](../../docs/fr/explanation/asking-another-agent.md)
--- [Faire tourner mini-me sur llmman](../docs/fr/how-to/run-with-llmman.md)
++- [Faire tourner mini-me sur llmman](../../docs/fr/how-to/run-with-llmman.md)

renamed demos/llmman/agent.jan-nano.yaml +2 -2 Viewed

similarity index 99%
rename from demo-llmman/agent.jan-nano.yaml
rename to demos/llmman/agent.jan-nano.yaml
@@ -76,8 +76,8 @@ maxOutput: 16000
76	76	maxTurns: 40
77	77
78	78	# Where the `read_skill` tool looks for its markdown procedures.
79		-# The path is relative to the CURRENT DIRECTORY: run the agent from demo-llmman/.
80		-skillsDir: ../skills
	79	+# The path is relative to the CURRENT DIRECTORY: run the agent from demos/llmman/.
	80	+skillsDir: skills
81	81
82	82	# Persistent sessions, per project.
83	83	# When enabled, every conversation is saved as one JSON file under `dir`.

  maxTurns: 40
  # Where the `read_skill` tool looks for its markdown procedures.
--# The path is relative to the CURRENT DIRECTORY: run the agent from demo-llmman/.
++# The path is relative to the CURRENT DIRECTORY: run the agent from demos/llmman/.
--skillsDir: ../skills
++skillsDir: skills
  # Persistent sessions, per project.
  # When enabled, every conversation is saved as one JSON file under `dir`.

renamed demos/llmman/agent.llmman.yaml +2 -2 Viewed

similarity index 99%
rename from demo-llmman/agent.llmman.yaml
rename to demos/llmman/agent.llmman.yaml
@@ -114,8 +114,8 @@ maxOutput: 16000
114	114	maxTurns: 40
115	115
116	116	# Where the `read_skill` tool looks for its markdown procedures.
117		-# The path is relative to the CURRENT DIRECTORY: run the agent from demo-llmman/.
118		-# demo-llmman/skills holds the /ask demo skills (delegate-to-jan, second-opinion,
	117	+# The path is relative to the CURRENT DIRECTORY: run the agent from demos/llmman/.
	118	+# demos/llmman/skills holds the /ask demo skills (delegate-to-jan, second-opinion,
119	119	# compare-agents) — they call this same mm back with "$MM_BIN" --ask — and bg-jobs.
120	120	skillsDir: skills
121	121

  maxTurns: 40
  # Where the `read_skill` tool looks for its markdown procedures.
--# The path is relative to the CURRENT DIRECTORY: run the agent from demo-llmman/.
++# The path is relative to the CURRENT DIRECTORY: run the agent from demos/llmman/.
--# demo-llmman/skills holds the /ask demo skills (delegate-to-jan, second-opinion,
++# demos/llmman/skills holds the /ask demo skills (delegate-to-jan, second-opinion,
  # compare-agents) — they call this same mm back with "$MM_BIN" --ask — and bg-jobs.
  skillsDir: skills

renamed demos/llmman/agent.lucy-reviewer.yaml +1 -1 Viewed

similarity index 99%
rename from demo-llmman/agent.lucy-reviewer.yaml
rename to demos/llmman/agent.lucy-reviewer.yaml
@@ -76,7 +76,7 @@ maxOutput: 16000
76	76	maxTurns: 40
77	77
78	78	# Where the `read_skill` tool looks for its markdown procedures.
79		-# The path is relative to the CURRENT DIRECTORY: run the agent from demo-llmman/.
	79	+# The path is relative to the CURRENT DIRECTORY: run the agent from demos/llmman/.
80	80	# No skills either: a directory that does not exist declares no read_skill tool.
81	81	skillsDir: no-skills-for-the-reviewer
82	82

  maxTurns: 40
  # Where the `read_skill` tool looks for its markdown procedures.
--# The path is relative to the CURRENT DIRECTORY: run the agent from demo-llmman/.
++# The path is relative to the CURRENT DIRECTORY: run the agent from demos/llmman/.
  # No skills either: a directory that does not exist declares no read_skill tool.
  skillsDir: no-skills-for-the-reviewer

renamed demos/llmman/agent.lucy.yaml +2 -2 Viewed

similarity index 99%
rename from demo-llmman/agent.lucy.yaml
rename to demos/llmman/agent.lucy.yaml
@@ -76,8 +76,8 @@ maxOutput: 16000
76	76	maxTurns: 40
77	77
78	78	# Where the `read_skill` tool looks for its markdown procedures.
79		-# The path is relative to the CURRENT DIRECTORY: run the agent from demo-llmman/.
80		-skillsDir: ../skills
	79	+# The path is relative to the CURRENT DIRECTORY: run the agent from demos/llmman/.
	80	+skillsDir: skills
81	81
82	82	# Persistent sessions, per project.
83	83	# When enabled, every conversation is saved as one JSON file under `dir`.

  maxTurns: 40
  # Where the `read_skill` tool looks for its markdown procedures.
--# The path is relative to the CURRENT DIRECTORY: run the agent from demo-llmman/.
++# The path is relative to the CURRENT DIRECTORY: run the agent from demos/llmman/.
--skillsDir: ../skills
++skillsDir: skills
  # Persistent sessions, per project.
  # When enabled, every conversation is saved as one JSON file under `dir`.

renamed demos/llmman/skills/bg-jobs/SKILL.md +0 -0 Viewed

similarity index 100%
rename from demo-llmman/skills/bg-jobs/SKILL.md
rename to demos/llmman/skills/bg-jobs/SKILL.md

similarity index 100%
rename from demo-llmman/skills/bg-jobs/SKILL.md
rename to demos/llmman/skills/bg-jobs/SKILL.md

renamed demos/mini-mes/gopher/README.en.md +2 -2 Viewed

similarity index 91%
rename from mini-mes/gopher/README.en.md
rename to demos/mini-mes/gopher/README.en.md
@@ -27,7 +27,7 @@ From the Go project to work on:
27	27
28	28	```bash
29	29	cd ~/src/my-go-project
30		-mm -config /path/to/mini-me/mini-mes/gopher/agent.gopher.yaml
	30	+mm -config /path/to/mini-me/demos/mini-mes/gopher/agent.gopher.yaml
31	31	```
32	32
33	33	`skillsDir` is an absolute path in the config: in the terminal, a relative path is resolved from the current directory (your project), not from this folder. Fix it if you move the repository.
@@ -45,4 +45,4 @@ mm -config /path/to/mini-me/mini-mes/gopher/agent.gopher.yaml
45	45
46	46	- Neither gopls nor `-race` was exercised in the sandbox used to build this (no gopls, no cgo).
47	47	- Speeds depend on your machine; the timeouts are generous on purpose.
48		-- See also: [Turn reasoning off or tune it](../../docs/en/how-to/turn-reasoning-off.md), [configuration reference](../../docs/en/reference/configuration.md), [skill format](../../docs/en/reference/skill-format.md).
	48	+- See also: [Turn reasoning off or tune it](../../../docs/en/how-to/turn-reasoning-off.md), [configuration reference](../../../docs/en/reference/configuration.md), [skill format](../../../docs/en/reference/skill-format.md).

  ```bash
  cd ~/src/my-go-project
--mm -config /path/to/mini-me/mini-mes/gopher/agent.gopher.yaml
++mm -config /path/to/mini-me/demos/mini-mes/gopher/agent.gopher.yaml
  ```
  `skillsDir` is an **absolute** path in the config: in the terminal, a relative path is resolved from the current directory (your project), not from this folder. Fix it if you move the repository.
  - Neither gopls nor `-race` was exercised in the sandbox used to build this (no gopls, no cgo).
  - Speeds depend on your machine; the timeouts are generous on purpose.
--- See also: [Turn reasoning off or tune it](../../docs/en/how-to/turn-reasoning-off.md), [configuration reference](../../docs/en/reference/configuration.md), [skill format](../../docs/en/reference/skill-format.md).
++- See also: [Turn reasoning off or tune it](../../../docs/en/how-to/turn-reasoning-off.md), [configuration reference](../../../docs/en/reference/configuration.md), [skill format](../../../docs/en/reference/skill-format.md).

renamed demos/mini-mes/gopher/README.md +2 -2 Viewed

similarity index 91%
rename from mini-mes/gopher/README.md
rename to demos/mini-mes/gopher/README.md
@@ -27,7 +27,7 @@ Depuis le projet Go sur lequel travailler :
27	27
28	28	```bash
29	29	cd ~/src/mon-projet-go
30		-mm -config /chemin/vers/mini-me/mini-mes/gopher/agent.gopher.yaml
	30	+mm -config /chemin/vers/mini-me/demos/mini-mes/gopher/agent.gopher.yaml
31	31	```
32	32
33	33	`skillsDir` est un chemin absolu dans la config : en mode terminal, un chemin relatif serait résolu depuis le répertoire courant (votre projet), pas depuis ce dossier. Si vous déplacez le dépôt, corrigez-le.
@@ -45,4 +45,4 @@ mm -config /chemin/vers/mini-me/mini-mes/gopher/agent.gopher.yaml
45	45
46	46	- Ni gopls ni `-race` n'ont été exercés dans la sandbox de mise au point (gopls absent, pas de cgo).
47	47	- Les vitesses dépendent de votre machine ; les délais sont larges exprès.
48		-- Voir aussi : [Couper ou régler le raisonnement](../../docs/fr/how-to/turn-reasoning-off.md), [référence de la configuration](../../docs/fr/reference/configuration.md), [format des skills](../../docs/fr/reference/skill-format.md).
	48	+- Voir aussi : [Couper ou régler le raisonnement](../../../docs/fr/how-to/turn-reasoning-off.md), [référence de la configuration](../../../docs/fr/reference/configuration.md), [format des skills](../../../docs/fr/reference/skill-format.md).

  ```bash
  cd ~/src/mon-projet-go
--mm -config /chemin/vers/mini-me/mini-mes/gopher/agent.gopher.yaml
++mm -config /chemin/vers/mini-me/demos/mini-mes/gopher/agent.gopher.yaml
  ```
  `skillsDir` est un chemin **absolu** dans la config : en mode terminal, un chemin relatif serait résolu depuis le répertoire courant (votre projet), pas depuis ce dossier. Si vous déplacez le dépôt, corrigez-le.
  - Ni gopls ni `-race` n'ont été exercés dans la sandbox de mise au point (gopls absent, pas de cgo).
  - Les vitesses dépendent de votre machine ; les délais sont larges exprès.
--- Voir aussi : [Couper ou régler le raisonnement](../../docs/fr/how-to/turn-reasoning-off.md), [référence de la configuration](../../docs/fr/reference/configuration.md), [format des skills](../../docs/fr/reference/skill-format.md).
++- Voir aussi : [Couper ou régler le raisonnement](../../../docs/fr/how-to/turn-reasoning-off.md), [référence de la configuration](../../../docs/fr/reference/configuration.md), [format des skills](../../../docs/fr/reference/skill-format.md).

renamed demos/mini-mes/gopher/agent.gopher.yaml +2 -2 Viewed

similarity index 98%
rename from mini-mes/gopher/agent.gopher.yaml
rename to demos/mini-mes/gopher/agent.gopher.yaml
@@ -12,7 +12,7 @@
12	12	# gopls all work in the current directory):
13	13	#
14	14	# cd ~/src/my-go-project
15		-# mm -config /path/to/mini-mes/gopher/agent.gopher.yaml
	15	+# mm -config /path/to/demos/mini-mes/gopher/agent.gopher.yaml
16	16	#
17	17	# Every key is optional: a key left out keeps mm's built-in default. Reference:
18	18	# docs/en/reference/configuration.md.
@@ -169,7 +169,7 @@ lsp:
169	169	# resolved from the directory mm is started in — your Go project, not this
170	170	# folder — so it is absolute here. Adjust it if you move the repository.
171	171	# (In an editor, through ACP, a relative path follows this file instead.)
172		-#skillsDir: /Users/k33g/kDrive/Rickub/bots-garden/mini-me/mini-mes/gopher/skills
	172	+#skillsDir: /Users/k33g/kDrive/Rickub/bots-garden/mini-me/demos/mini-mes/gopher/skills
173	173	skillsDir: skills
174	174
175	175	# ─── Memory ──────────────────────────────────────────────────────────────────

  # gopls all work in the current directory):
  #
  #   cd ~/src/my-go-project
--#   mm -config /path/to/mini-mes/gopher/agent.gopher.yaml
++#   mm -config /path/to/demos/mini-mes/gopher/agent.gopher.yaml
  #
  # Every key is optional: a key left out keeps mm's built-in default. Reference:
  # docs/en/reference/configuration.md.
  # resolved from the directory mm is started in — your Go project, not this
  # folder — so it is absolute here. Adjust it if you move the repository.
  # (In an editor, through ACP, a relative path follows this file instead.)
--#skillsDir: /Users/k33g/kDrive/Rickub/bots-garden/mini-me/mini-mes/gopher/skills
++#skillsDir: /Users/k33g/kDrive/Rickub/bots-garden/mini-me/demos/mini-mes/gopher/skills
  skillsDir: skills
  # ─── Memory ──────────────────────────────────────────────────────────────────

renamed demos/mini-mes/gopher/skills/bg-jobs/SKILL.md +0 -0 Viewed

similarity index 100%
rename from mini-mes/gopher/skills/bg-jobs/SKILL.md
rename to demos/mini-mes/gopher/skills/bg-jobs/SKILL.md

similarity index 100%
rename from mini-mes/gopher/skills/bg-jobs/SKILL.md
rename to demos/mini-mes/gopher/skills/bg-jobs/SKILL.md

renamed demos/mini-mes/gopher/skills/go-deps/SKILL.md +0 -0 Viewed

similarity index 100%
rename from mini-mes/gopher/skills/go-deps/SKILL.md
rename to demos/mini-mes/gopher/skills/go-deps/SKILL.md

similarity index 100%
rename from mini-mes/gopher/skills/go-deps/SKILL.md
rename to demos/mini-mes/gopher/skills/go-deps/SKILL.md

renamed demos/mini-mes/gopher/skills/go-fix/SKILL.md +0 -0 Viewed

similarity index 100%
rename from mini-mes/gopher/skills/go-fix/SKILL.md
rename to demos/mini-mes/gopher/skills/go-fix/SKILL.md

similarity index 100%
rename from mini-mes/gopher/skills/go-fix/SKILL.md
rename to demos/mini-mes/gopher/skills/go-fix/SKILL.md

renamed demos/mini-mes/gopher/skills/go-new-project/SKILL.md +0 -0 Viewed

similarity index 100%
rename from mini-mes/gopher/skills/go-new-project/SKILL.md
rename to demos/mini-mes/gopher/skills/go-new-project/SKILL.md

similarity index 100%
rename from mini-mes/gopher/skills/go-new-project/SKILL.md
rename to demos/mini-mes/gopher/skills/go-new-project/SKILL.md

renamed demos/mini-mes/gopher/skills/go-review/SKILL.md +0 -0 Viewed

similarity index 100%
rename from mini-mes/gopher/skills/go-review/SKILL.md
rename to demos/mini-mes/gopher/skills/go-review/SKILL.md

similarity index 100%
rename from mini-mes/gopher/skills/go-review/SKILL.md
rename to demos/mini-mes/gopher/skills/go-review/SKILL.md

renamed demos/mini-mes/gopher/skills/go-test-writing/SKILL.md +0 -0 Viewed

similarity index 100%
rename from mini-mes/gopher/skills/go-test-writing/SKILL.md
rename to demos/mini-mes/gopher/skills/go-test-writing/SKILL.md

similarity index 100%
rename from mini-mes/gopher/skills/go-test-writing/SKILL.md
rename to demos/mini-mes/gopher/skills/go-test-writing/SKILL.md

renamed demos/mini-mes/gopher/skills/go-verify/SKILL.md +0 -0 Viewed

similarity index 100%
rename from mini-mes/gopher/skills/go-verify/SKILL.md
rename to demos/mini-mes/gopher/skills/go-verify/SKILL.md

similarity index 100%
rename from mini-mes/gopher/skills/go-verify/SKILL.md
rename to demos/mini-mes/gopher/skills/go-verify/SKILL.md

renamed demos/mini-mes/gopher/skills/lsp-navigation/SKILL.md +0 -0 Viewed

similarity index 100%
rename from mini-mes/gopher/skills/lsp-navigation/SKILL.md
rename to demos/mini-mes/gopher/skills/lsp-navigation/SKILL.md

similarity index 100%
rename from mini-mes/gopher/skills/lsp-navigation/SKILL.md
rename to demos/mini-mes/gopher/skills/lsp-navigation/SKILL.md

renamed demos/mini-mes/riker/README.en.md +4 -4 Viewed

similarity index 91%
rename from mini-mes/riker/README.en.md
rename to demos/mini-mes/riker/README.en.md
@@ -28,7 +28,7 @@ From the project to work on:
28	28
29	29	```bash
30	30	cd ~/src/my-project
31		-mm -config /path/to/mini-me/mini-mes/riker/agent.riker.yaml
	31	+mm -config /path/to/mini-me/demos/mini-mes/riker/agent.riker.yaml
32	32	```
33	33
34	34	Then, for instance: "Create a Go CLI that converts temperatures", or "specify a CSV export of the orders".
@@ -53,6 +53,6 @@ You can also ask the agents yourself: `/ask-milo …`, `/ask-homer …` in riker
53	53
54	54	## See also
55	55
56		-- [Let your agent call other agents](../../docs/en/how-to/let-the-agent-call-other-agents.md)
57		-- [The `ask_agent` tool](../../docs/en/reference/tools.md#ask_agent)
58		-- [Asking another agent — explanation](../../docs/en/explanation/asking-another-agent.md)
	56	+- [Let your agent call other agents](../../../docs/en/how-to/let-the-agent-call-other-agents.md)
	57	+- [The `ask_agent` tool](../../../docs/en/reference/tools.md#ask_agent)
	58	+- [Asking another agent — explanation](../../../docs/en/explanation/asking-another-agent.md)

  ```bash
  cd ~/src/my-project
--mm -config /path/to/mini-me/mini-mes/riker/agent.riker.yaml
++mm -config /path/to/mini-me/demos/mini-mes/riker/agent.riker.yaml
  ```
  Then, for instance: *"Create a Go CLI that converts temperatures"*, or *"specify a CSV export of the orders"*.
  ## See also
--- [Let your agent call other agents](../../docs/en/how-to/let-the-agent-call-other-agents.md)
++- [Let your agent call other agents](../../../docs/en/how-to/let-the-agent-call-other-agents.md)
--- [The `ask_agent` tool](../../docs/en/reference/tools.md#ask_agent)
++- [The `ask_agent` tool](../../../docs/en/reference/tools.md#ask_agent)
--- [Asking another agent — explanation](../../docs/en/explanation/asking-another-agent.md)
++- [Asking another agent — explanation](../../../docs/en/explanation/asking-another-agent.md)

renamed demos/mini-mes/riker/README.fr.md +4 -4 Viewed

similarity index 92%
rename from mini-mes/riker/README.md
rename to demos/mini-mes/riker/README.fr.md
@@ -28,7 +28,7 @@ Depuis le projet sur lequel travailler :
28	28
29	29	```bash
30	30	cd ~/src/mon-projet
31		-mm -config /chemin/vers/mini-me/mini-mes/riker/agent.riker.yaml
	31	+mm -config /chemin/vers/mini-me/demos/mini-mes/riker/agent.riker.yaml
32	32	```
33	33
34	34	Puis, par exemple : « Crée un CLI Go qui convertit des températures », ou « spécifie un export CSV des commandes ».
@@ -53,6 +53,6 @@ Vous pouvez aussi interroger les agents vous-même : `/ask-milo …`, `/ask-home
53	53
54	54	## Voir aussi
55	55
56		-- [Laisser votre agent appeler d'autres agents](../../docs/fr/how-to/let-the-agent-call-other-agents.md)
57		-- [L'outil `ask_agent`](../../docs/fr/reference/tools.md#ask_agent)
58		-- [Interroger un autre agent — explication](../../docs/fr/explanation/asking-another-agent.md)
	56	+- [Laisser votre agent appeler d'autres agents](../../../docs/fr/how-to/let-the-agent-call-other-agents.md)
	57	+- [L'outil `ask_agent`](../../../docs/fr/reference/tools.md#ask_agent)
	58	+- [Interroger un autre agent — explication](../../../docs/fr/explanation/asking-another-agent.md)

  ```bash
  cd ~/src/mon-projet
--mm -config /chemin/vers/mini-me/mini-mes/riker/agent.riker.yaml
++mm -config /chemin/vers/mini-me/demos/mini-mes/riker/agent.riker.yaml
  ```
  Puis, par exemple : *« Crée un CLI Go qui convertit des températures »*, ou *« spécifie un export CSV des commandes »*.
  ## Voir aussi
--- [Laisser votre agent appeler d'autres agents](../../docs/fr/how-to/let-the-agent-call-other-agents.md)
++- [Laisser votre agent appeler d'autres agents](../../../docs/fr/how-to/let-the-agent-call-other-agents.md)
--- [L'outil `ask_agent`](../../docs/fr/reference/tools.md#ask_agent)
++- [L'outil `ask_agent`](../../../docs/fr/reference/tools.md#ask_agent)
--- [Interroger un autre agent — explication](../../docs/fr/explanation/asking-another-agent.md)
++- [Interroger un autre agent — explication](../../../docs/fr/explanation/asking-another-agent.md)

renamed demos/mini-mes/riker/agent.homer.yaml +1 -1 Viewed

similarity index 98%
rename from mini-mes/riker/agent.homer.yaml
rename to demos/mini-mes/riker/agent.homer.yaml
@@ -111,7 +111,7 @@ lsp:
111	111	# Absolute: a relative path would follow this
112	112	# file when riker asks (ACP mode) but the current directory when you run
113	113	# homer directly in a terminal. Adjust it if you move the repository.
114		-skillsDir: /Users/k33g/kDrive/Rickub/bots-garden/mini-me/mini-mes/riker/skills-homer
	114	+skillsDir: /Users/k33g/kDrive/Rickub/bots-garden/mini-me/demos/mini-mes/riker/skills-homer
115	115
116	116	# Asked agents never write sessions; this matters only for a direct start.
117	117	sessions:

  # Absolute: a relative path would follow this
  # file when riker asks (ACP mode) but the current directory when you run
  # homer directly in a terminal. Adjust it if you move the repository.
--skillsDir: /Users/k33g/kDrive/Rickub/bots-garden/mini-me/mini-mes/riker/skills-homer
++skillsDir: /Users/k33g/kDrive/Rickub/bots-garden/mini-me/demos/mini-mes/riker/skills-homer
  # Asked agents never write sessions; this matters only for a direct start.
  sessions:

renamed demos/mini-mes/riker/agent.milo.yaml +0 -0 Viewed

similarity index 100%
rename from mini-mes/riker/agent.milo.yaml
rename to demos/mini-mes/riker/agent.milo.yaml

similarity index 100%
rename from mini-mes/riker/agent.milo.yaml
rename to demos/mini-mes/riker/agent.milo.yaml

renamed demos/mini-mes/riker/agent.riker.yaml +1 -1 Viewed

similarity index 99%
rename from mini-mes/riker/agent.riker.yaml
rename to demos/mini-mes/riker/agent.riker.yaml
@@ -18,7 +18,7 @@
18	18	# riker was started in:
19	19	#
20	20	# cd ~/src/my-project
21		-# mm -config /path/to/mini-mes/riker/agent.riker.yaml
	21	+# mm -config /path/to/demos/mini-mes/riker/agent.riker.yaml
22	22	#
23	23	# Memory: up to three models loaded at once in llmman (~5 + ~16 + ~48 GB at
24	24	# Q4). llmman unloads a model after five idle minutes.

  # riker was started in:
  #
  #   cd ~/src/my-project
--#   mm -config /path/to/mini-mes/riker/agent.riker.yaml
++#   mm -config /path/to/demos/mini-mes/riker/agent.riker.yaml
  #
  # Memory: up to three models loaded at once in llmman (~5 + ~16 + ~48 GB at
  # Q4). llmman unloads a model after five idle minutes.

renamed demos/mini-mes/riker/skills-homer/implement-spec/SKILL.md +0 -0 Viewed

similarity index 100%
rename from mini-mes/riker/skills-homer/implement-spec/SKILL.md
rename to demos/mini-mes/riker/skills-homer/implement-spec/SKILL.md

similarity index 100%
rename from mini-mes/riker/skills-homer/implement-spec/SKILL.md
rename to demos/mini-mes/riker/skills-homer/implement-spec/SKILL.md

renamed demos/mini-mes/riker/skills-homer/lsp-navigation/SKILL.md +0 -0 Viewed

similarity index 100%
rename from mini-mes/riker/skills-homer/lsp-navigation/SKILL.md
rename to demos/mini-mes/riker/skills-homer/lsp-navigation/SKILL.md

similarity index 100%
rename from mini-mes/riker/skills-homer/lsp-navigation/SKILL.md
rename to demos/mini-mes/riker/skills-homer/lsp-navigation/SKILL.md

renamed demos/ollama/agent.ollama.yaml +2 -2 Viewed

similarity index 99%
rename from demo-ollama/agent.ollama.yaml
rename to demos/ollama/agent.ollama.yaml
@@ -78,8 +78,8 @@ maxOutput: 16000
78	78	maxTurns: 40
79	79
80	80	# Where the `read_skill` tool looks for its markdown procedures.
81		-# The path is relative to the CURRENT DIRECTORY: run the agent from demo-ollama/.
82		-skillsDir: ../skills
	81	+# The path is relative to the CURRENT DIRECTORY: run the agent from demos/ollama/.
	82	+skillsDir: ../../skills
83	83
84	84	# Persistent sessions, per project.
85	85	# When enabled, every conversation is saved as one JSON file under `dir`.

  maxTurns: 40
  # Where the `read_skill` tool looks for its markdown procedures.
--# The path is relative to the CURRENT DIRECTORY: run the agent from demo-ollama/.
++# The path is relative to the CURRENT DIRECTORY: run the agent from demos/ollama/.
--skillsDir: ../skills
++skillsDir: ../../skills
  # Persistent sessions, per project.
  # When enabled, every conversation is saved as one JSON file under `dir`.

renamed demos/structured-output/README.en.md +13 -13 Viewed

similarity index 83%
rename from demo-structured-output/README.en.md
rename to demos/structured-output/README.en.md
@@ -25,7 +25,7 @@ All three agents use `hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M`.
25	25	3. `mm` built at the repository root (`go build -o mm .`). Run it from this directory: the `mmConfigs` paths are relative to `agent.coordinator.yaml`, and `reports.txt` is read from the current directory.
26	26
27	27	```bash
28		- cd demo-structured-output
	28	+ cd demos/structured-output
29	29	```
30	30
31	31	4. `jq`, to read the JSON (optional).
@@ -66,13 +66,13 @@ A JSON agent has no tool at all (`bashTool`, `editTools`, `planTool` set to
66	66	## 1. A simple agent: one question, JSON back
67	67
68	68	```bash
69		-../mm agent.countries.yaml -p "languages spoken in France, Canada, Vietnam and the US" \| jq .
	69	+../../mm agent.countries.yaml -p "languages spoken in France, Canada, Vietnam and the US" \| jq .
70	70	```
71	71
72	72	With `-p`, stdout carries only the JSON (no 🤖, no statistics), and the exit status is 1 when the answer is missing or invalid. So it can be processed directly:
73	73
74	74	```bash
75		-../mm agent.countries.yaml -p "languages spoken in France, Canada, Vietnam and the US" \
	75	+../../mm agent.countries.yaml -p "languages spoken in France, Canada, Vietnam and the US" \
76	76	\| jq -c '.[] \| {name, capital, languages: [.languages[].name]}'
77	77	```
78	78
@@ -88,7 +88,7 @@ The minor languages may vary with the wording of the question; the name and the
88	88	The second agent, on the reports file:
89	89
90	90	```bash
91		-../mm agent.triage.yaml -p "$(cat reports.txt)" \| jq -c '.reports[] \| {severity, title, duplicate}'
	91	+../../mm agent.triage.yaml -p "$(cat reports.txt)" \| jq -c '.reports[] \| {severity, title, duplicate}'
92	92	```
93	93
94	94	```
@@ -98,7 +98,7 @@ The second agent, on the reports file:
98	98	{"severity":"high","title":"Export crashes on big projects","duplicate":1}
99	99	```
100	100
101		-In an interactive session (`../mm agent.countries.yaml`, or `../mm -tui agent.countries.yaml`), every answer is JSON, shown like any answer; the banner says `tools: none (structured output: JSON answers)`.
	101	+In an interactive session (`../../mm agent.countries.yaml`, or `../../mm -tui agent.countries.yaml`), every answer is JSON, shown like any answer; the banner says `tools: none (structured output: JSON answers)`.
102	102
103	103	## 2. Several agents: Bob uses the others' JSON
104	104
@@ -117,7 +117,7 @@ mmConfigs:
117	117	Read the reports, have them triaged, write a table:
118	118
119	119	```bash
120		-../mm agent.coordinator.yaml -p "Read reports.txt, have the reports triaged, then write triage.md: a Markdown table (title, severity, component, duplicate of) sorted by severity, high first."
	120	+../../mm agent.coordinator.yaml -p "Read reports.txt, have the reports triaged, then write triage.md: a Markdown table (title, severity, component, duplicate of) sorted by severity, high first."
121	121	```
122	122
123	123	```
@@ -130,17 +130,17 @@ Read the reports, have them triaged, write a table:
130	130	A factual question, which Bob hands to countries:
131	131
132	132	```bash
133		-../mm agent.coordinator.yaml -p "Which of Belgium and Switzerland has more official languages? Answer in one sentence."
	133	+../../mm agent.coordinator.yaml -p "Which of Belgium and Switzerland has more official languages? Answer in one sentence."
134	134	```
135	135
136		-Or in a session, to watch the agent work: `../mm -tui agent.coordinator.yaml`.
	136	+Or in a session, to watch the agent work: `../../mm -tui agent.coordinator.yaml`.
137	137
138	138	## 3. Ask a JSON agent from a shell, through Bob's config
139	139
140	140	`mm --ask` prints only the asked agent's answer — here, its JSON:
141	141
142	142	```bash
143		-../mm agent.coordinator.yaml --ask countries -p "capital and languages of Vietnam" \| jq .
	143	+../../mm agent.coordinator.yaml --ask countries -p "capital and languages of Vietnam" \| jq .
144	144	```
145	145
146	146	## Good to know
@@ -150,10 +150,10 @@ Or in a session, to watch the agent work: `../mm -tui agent.coordinator.yaml`.
150	150	- Reasoning: countries and triage turn it off (`chat_template_kwargs.enable_thinking: false`) — a lookup does not need it, and it is faster. Bob keeps it: without reasoning, the 4B model answered from memory and claimed it had asked countries.
151	151	- OpenAI hosted API: its strict mode demands an object at the root — use a struct, as `agent.triage.yaml` does.
152	152	- With tools: `structuredOutput cannot be used with tools — this agent declares: …`; turn the listed tools off.
153		-- To see the exact request (the `response_format` sent): `AGENT_TRACE=true ../mm agent.countries.yaml -p "…"`, then the files in `.mm/traces/`.
	153	+- To see the exact request (the `response_format` sent): `AGENT_TRACE=true ../../mm agent.countries.yaml -p "…"`, then the files in `.mm/traces/`.
154	154
155	155	## Further reading
156	156
157		-- [Get answers as JSON](../docs/en/how-to/get-json-answers.md)
158		-- [`structuredOutput` reference](../docs/en/reference/configuration.md#structuredoutput)
159		-- [Structured output — explanation](../docs/en/explanation/structured-output.md)
	157	+- [Get answers as JSON](../../docs/en/how-to/get-json-answers.md)
	158	+- [`structuredOutput` reference](../../docs/en/reference/configuration.md#structuredoutput)
	159	+- [Structured output — explanation](../../docs/en/explanation/structured-output.md)

 . `mm` built at the repository root (`go build -o mm .`). **Run it from this directory**: the `mmConfigs` paths are relative to `agent.coordinator.yaml`, and `reports.txt` is read from the current directory.
     ```bash
--   cd demo-structured-output
++   cd demos/structured-output
     ```
 . `jq`, to read the JSON (optional).
  ## 1. A simple agent: one question, JSON back
  ```bash
--../mm agent.countries.yaml -p "languages spoken in France, Canada, Vietnam and the US" | jq .
++../../mm agent.countries.yaml -p "languages spoken in France, Canada, Vietnam and the US" | jq .
  ```
  With `-p`, stdout carries **only the JSON** (no 🤖, no statistics), and the exit status is 1 when the answer is missing or invalid. So it can be processed directly:
  ```bash
--../mm agent.countries.yaml -p "languages spoken in France, Canada, Vietnam and the US" \
++../../mm agent.countries.yaml -p "languages spoken in France, Canada, Vietnam and the US" \
    | jq -c '.[] | {name, capital, languages: [.languages[].name]}'
  ```
  The second agent, on the reports file:
  ```bash
--../mm agent.triage.yaml -p "$(cat reports.txt)" | jq -c '.reports[] | {severity, title, duplicate}'
++../../mm agent.triage.yaml -p "$(cat reports.txt)" | jq -c '.reports[] | {severity, title, duplicate}'
  ```
  ```
  {"severity":"high","title":"Export crashes on big projects","duplicate":1}
  ```
--In an interactive session (`../mm agent.countries.yaml`, or `../mm -tui agent.countries.yaml`), every answer is JSON, shown like any answer; the banner says `tools: none (structured output: JSON answers)`.
++In an interactive session (`../../mm agent.countries.yaml`, or `../../mm -tui agent.countries.yaml`), every answer is JSON, shown like any answer; the banner says `tools: none (structured output: JSON answers)`.
  ## 2. Several agents: Bob uses the others' JSON
  Read the reports, have them triaged, write a table:
  ```bash
--../mm agent.coordinator.yaml -p "Read reports.txt, have the reports triaged, then write triage.md: a Markdown table (title, severity, component, duplicate of) sorted by severity, high first."
++../../mm agent.coordinator.yaml -p "Read reports.txt, have the reports triaged, then write triage.md: a Markdown table (title, severity, component, duplicate of) sorted by severity, high first."
  ```
  ```
  A factual question, which Bob hands to countries:
  ```bash
--../mm agent.coordinator.yaml -p "Which of Belgium and Switzerland has more official languages? Answer in one sentence."
++../../mm agent.coordinator.yaml -p "Which of Belgium and Switzerland has more official languages? Answer in one sentence."
  ```
--Or in a session, to watch the agent work: `../mm -tui agent.coordinator.yaml`.
++Or in a session, to watch the agent work: `../../mm -tui agent.coordinator.yaml`.
  ## 3. Ask a JSON agent from a shell, through Bob's config
  `mm --ask` prints only the asked agent's answer — here, its JSON:
  ```bash
--../mm agent.coordinator.yaml --ask countries -p "capital and languages of Vietnam" | jq .
++../../mm agent.coordinator.yaml --ask countries -p "capital and languages of Vietnam" | jq .
  ```
  ## Good to know
  - **Reasoning**: countries and triage turn it off (`chat_template_kwargs.enable_thinking: false`) — a lookup does not need it, and it is faster. Bob keeps it: without reasoning, the 4B model answered from memory and claimed it had asked countries.
  - **OpenAI hosted API**: its strict mode demands an object at the root — use a struct, as `agent.triage.yaml` does.
  - **With tools**: `structuredOutput cannot be used with tools — this agent declares: …`; turn the listed tools off.
--- To see the exact request (the `response_format` sent): `AGENT_TRACE=true ../mm agent.countries.yaml -p "…"`, then the files in `.mm/traces/`.
++- To see the exact request (the `response_format` sent): `AGENT_TRACE=true ../../mm agent.countries.yaml -p "…"`, then the files in `.mm/traces/`.
  ## Further reading
--- [Get answers as JSON](../docs/en/how-to/get-json-answers.md)
++- [Get answers as JSON](../../docs/en/how-to/get-json-answers.md)
--- [`structuredOutput` reference](../docs/en/reference/configuration.md#structuredoutput)
++- [`structuredOutput` reference](../../docs/en/reference/configuration.md#structuredoutput)
--- [Structured output — explanation](../docs/en/explanation/structured-output.md)
++- [Structured output — explanation](../../docs/en/explanation/structured-output.md)

renamed demos/structured-output/README.md +7 -7 Viewed

similarity index 91%
rename from demo-structured-output/README.md
rename to demos/structured-output/README.md
@@ -25,7 +25,7 @@ Les trois agents utilisent `hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M`.
25	25	3. `mm` compilé à la racine du dépôt (`go build -o mm .`). Lancez-le depuis ce dossier : les chemins de `mmConfigs` sont relatifs à `agent.coordinator.yaml`, et `reports.txt` est lu dans le dossier courant.
26	26
27	27	```bash
28		- cd demo-structured-output
	28	+ cd demos/structured-output
29	29	```
30	30
31	31	4. `jq`, pour lire le JSON (facultatif).
@@ -88,7 +88,7 @@ Les langues secondaires peuvent varier d'une formulation de la question à l'aut
88	88	Le deuxième agent, sur le fichier de rapports :
89	89
90	90	```bash
91		-../mm agent.triage.yaml -p "$(cat reports.txt)" \| jq -c '.reports[] \| {severity, title, duplicate}'
	91	+../../mm agent.triage.yaml -p "$(cat reports.txt)" \| jq -c '.reports[] \| {severity, title, duplicate}'
92	92	```
93	93
94	94	```
@@ -98,7 +98,7 @@ Le deuxième agent, sur le fichier de rapports :
98	98	{"severity":"high","title":"Export crashes on big projects","duplicate":1}
99	99	```
100	100
101		-En session interactive (`../mm agent.countries.yaml`, ou `../mm -tui agent.countries.yaml`), chaque réponse est du JSON, affiché comme n'importe quelle réponse ; la bannière indique `tools: none (structured output: JSON answers)`.
	101	+En session interactive (`../../mm agent.countries.yaml`, ou `../../mm -tui agent.countries.yaml`), chaque réponse est du JSON, affiché comme n'importe quelle réponse ; la bannière indique `tools: none (structured output: JSON answers)`.
102	102
103	103	## 2. Plusieurs agents : Bob exploite le JSON des autres
104	104
@@ -150,10 +150,10 @@ mm agent.coordinator.yaml --ask countries -p "capital and languages of Vietnam"
150	150	- Raisonnement : countries et triage l'ont coupé (`chat_template_kwargs.enable_thinking: false`) — une consultation n'en a pas besoin, et c'est plus rapide. Bob le garde : sans raisonnement, le modèle 4B répondait de mémoire en prétendant avoir demandé à countries.
151	151	- API OpenAI hébergée : son mode strict exige un objet à la racine — utilisez une struct, comme dans `agent.triage.yaml`.
152	152	- Avec des outils : `structuredOutput cannot be used with tools — this agent declares: …` ; désactivez les outils listés.
153		-- Pour voir la requête exacte (le `response_format` envoyé) : `AGENT_TRACE=true ../mm agent.countries.yaml -p "…"`, puis les fichiers de `.mm/traces/`.
	153	+- Pour voir la requête exacte (le `response_format` envoyé) : `AGENT_TRACE=true ../../mm agent.countries.yaml -p "…"`, puis les fichiers de `.mm/traces/`.
154	154
155	155	## Pour aller plus loin
156	156
157		-- [Obtenir des réponses en JSON](../docs/fr/how-to/get-json-answers.md)
158		-- [Référence de `structuredOutput`](../docs/fr/reference/configuration.md#structuredoutput)
159		-- [Sortie structurée — explication](../docs/fr/explanation/structured-output.md)
	157	+- [Obtenir des réponses en JSON](../../docs/fr/how-to/get-json-answers.md)
	158	+- [Référence de `structuredOutput`](../../docs/fr/reference/configuration.md#structuredoutput)
	159	+- [Sortie structurée — explication](../../docs/fr/explanation/structured-output.md)

 . `mm` compilé à la racine du dépôt (`go build -o mm .`). **Lancez-le depuis ce dossier** : les chemins de `mmConfigs` sont relatifs à `agent.coordinator.yaml`, et `reports.txt` est lu dans le dossier courant.
     ```bash
--   cd demo-structured-output
++   cd demos/structured-output
     ```
 . `jq`, pour lire le JSON (facultatif).
  Le deuxième agent, sur le fichier de rapports :
  ```bash
--../mm agent.triage.yaml -p "$(cat reports.txt)" | jq -c '.reports[] | {severity, title, duplicate}'
++../../mm agent.triage.yaml -p "$(cat reports.txt)" | jq -c '.reports[] | {severity, title, duplicate}'
  ```
  ```
  {"severity":"high","title":"Export crashes on big projects","duplicate":1}
  ```
--En session interactive (`../mm agent.countries.yaml`, ou `../mm -tui agent.countries.yaml`), chaque réponse est du JSON, affiché comme n'importe quelle réponse ; la bannière indique `tools: none (structured output: JSON answers)`.
++En session interactive (`../../mm agent.countries.yaml`, ou `../../mm -tui agent.countries.yaml`), chaque réponse est du JSON, affiché comme n'importe quelle réponse ; la bannière indique `tools: none (structured output: JSON answers)`.
  ## 2. Plusieurs agents : Bob exploite le JSON des autres
  - **Raisonnement** : countries et triage l'ont coupé (`chat_template_kwargs.enable_thinking: false`) — une consultation n'en a pas besoin, et c'est plus rapide. Bob le garde : sans raisonnement, le modèle 4B répondait de mémoire en prétendant avoir demandé à countries.
  - **API OpenAI hébergée** : son mode strict exige un objet à la racine — utilisez une struct, comme dans `agent.triage.yaml`.
  - **Avec des outils** : `structuredOutput cannot be used with tools — this agent declares: …` ; désactivez les outils listés.
--- Pour voir la requête exacte (le `response_format` envoyé) : `AGENT_TRACE=true ../mm agent.countries.yaml -p "…"`, puis les fichiers de `.mm/traces/`.
++- Pour voir la requête exacte (le `response_format` envoyé) : `AGENT_TRACE=true ../../mm agent.countries.yaml -p "…"`, puis les fichiers de `.mm/traces/`.
  ## Pour aller plus loin
--- [Obtenir des réponses en JSON](../docs/fr/how-to/get-json-answers.md)
++- [Obtenir des réponses en JSON](../../docs/fr/how-to/get-json-answers.md)
--- [Référence de `structuredOutput`](../docs/fr/reference/configuration.md#structuredoutput)
++- [Référence de `structuredOutput`](../../docs/fr/reference/configuration.md#structuredoutput)
--- [Sortie structurée — explication](../docs/fr/explanation/structured-output.md)
++- [Sortie structurée — explication](../../docs/fr/explanation/structured-output.md)

renamed demos/structured-output/agent.coordinator.yaml +0 -0 Viewed

similarity index 100%
rename from demo-structured-output/agent.coordinator.yaml
rename to demos/structured-output/agent.coordinator.yaml

similarity index 100%
rename from demo-structured-output/agent.coordinator.yaml
rename to demos/structured-output/agent.coordinator.yaml

renamed demos/structured-output/agent.countries.yaml +0 -0 Viewed

similarity index 100%
rename from demo-structured-output/agent.countries.yaml
rename to demos/structured-output/agent.countries.yaml

similarity index 100%
rename from demo-structured-output/agent.countries.yaml
rename to demos/structured-output/agent.countries.yaml

renamed demos/structured-output/agent.triage.yaml +0 -0 Viewed

similarity index 100%
rename from demo-structured-output/agent.triage.yaml
rename to demos/structured-output/agent.triage.yaml

similarity index 100%
rename from demo-structured-output/agent.triage.yaml
rename to demos/structured-output/agent.triage.yaml

renamed demos/structured-output/reports.txt +0 -0 Viewed

similarity index 100%
rename from demo-structured-output/reports.txt
rename to demos/structured-output/reports.txt

similarity index 100%
rename from demo-structured-output/reports.txt
rename to demos/structured-output/reports.txt

renamed demos/structured-output/triage.md +0 -0 Viewed

similarity index 100%
rename from demo-structured-output/triage.md
rename to demos/structured-output/triage.md

similarity index 100%
rename from demo-structured-output/triage.md
rename to demos/structured-output/triage.md

modified docs/en/README.md +3 -4 Viewed

@@ -11,8 +11,8 @@ This documentation is organised along the four [Diátaxis](https://diataxis.fr)
11	11	## How-to guides — get a task done
12	12
13	13	- [Run mini-me on llama.cpp instead of Docker Model Runner](how-to/run-with-llama-cpp.md)
14		-- [Run mini-me on llmman](how-to/run-with-llmman.md) — `provider: llmman`, the demo config in `demo-llmman/`
15		-- [Run mini-me on Ollama](how-to/run-with-ollama.md) — `provider: ollama`, the demo config in `demo-ollama/`
	14	+- [Run mini-me on llmman](how-to/run-with-llmman.md) — `provider: llmman`, the demo config in `demos/llmman/`
	15	+- [Run mini-me on Ollama](how-to/run-with-ollama.md) — `provider: ollama`, the demo config in `demos/ollama/`
16	16	- [Ask another mm agent from your session](how-to/ask-another-agent.md) — `mmConfigs`, `/ask-<name>`, `/ask-with-context-<name>`
17	17	- [See the JSON sent to the model and its answer](how-to/inspect-model-traffic.md) — `trace`, `AGENT_TRACE`, reading the files with jq
18	18	- [Give the agent your project's instructions](how-to/give-project-instructions.md) — `AGENTS.md`, read per conversation, `agentsMd` settings
@@ -22,8 +22,7 @@ This documentation is organised along the four [Diátaxis](https://diataxis.fr)
22	22	- [Use mini-me from an editor (ACP)](how-to/use-from-an-editor.md)
23	23	- [Turn a model's reasoning off](how-to/turn-reasoning-off.md) — `chat_template_kwargs` or `reasoning_effort` in `sampling`, per server
24	24	- [Confirm tool calls before they run](how-to/confirm-tool-calls.md) — `yolo: false`, the four answers, `AGENT_YOLO`, who decides with `mmConfigs`
25		-- [Run mini-me in a Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — the template and the two kits under `docker-sbx/`, window mode and editor
26		-- [Run mini-me with the v3 sandbox kits](how-to/run-with-sandbox-kits-v3.md) — the same two kits for the kit specification v3, under `docker-sbx-v3/`
	25	+- [Run mini-me in a Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — the `mini-me` kit from [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), the `go-toolchain` and `cli-tools` mixins under `sbx/`, window mode and editor
27	26	- [Add a skill](how-to/add-a-skill.md)
28	27	- [Measure whether the model picks the right skill](how-to/measure-skill-routing.md) — the routing eval: run it, read its table, use it as a before-and-after
29	28	- [Keep a long session inside the context window](how-to/manage-the-context-window.md)

  ## How-to guides — get a task done
  - [Run mini-me on llama.cpp instead of Docker Model Runner](how-to/run-with-llama-cpp.md)
--- [Run mini-me on llmman](how-to/run-with-llmman.md) — `provider: llmman`, the demo config in `demo-llmman/`
++- [Run mini-me on llmman](how-to/run-with-llmman.md) — `provider: llmman`, the demo config in `demos/llmman/`
--- [Run mini-me on Ollama](how-to/run-with-ollama.md) — `provider: ollama`, the demo config in `demo-ollama/`
++- [Run mini-me on Ollama](how-to/run-with-ollama.md) — `provider: ollama`, the demo config in `demos/ollama/`
  - [Ask another mm agent from your session](how-to/ask-another-agent.md) — `mmConfigs`, `/ask-<name>`, `/ask-with-context-<name>`
  - [See the JSON sent to the model and its answer](how-to/inspect-model-traffic.md) — `trace`, `AGENT_TRACE`, reading the files with jq
  - [Give the agent your project's instructions](how-to/give-project-instructions.md) — `AGENTS.md`, read per conversation, `agentsMd` settings
  - [Use mini-me from an editor (ACP)](how-to/use-from-an-editor.md)
  - [Turn a model's reasoning off](how-to/turn-reasoning-off.md) — `chat_template_kwargs` or `reasoning_effort` in `sampling`, per server
  - [Confirm tool calls before they run](how-to/confirm-tool-calls.md) — `yolo: false`, the four answers, `AGENT_YOLO`, who decides with `mmConfigs`
--- [Run mini-me in a Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — the template and the two kits under `docker-sbx/`, window mode and editor
++- [Run mini-me in a Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — the `mini-me` kit from [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), the `go-toolchain` and `cli-tools` mixins under `sbx/`, window mode and editor
--- [Run mini-me with the v3 sandbox kits](how-to/run-with-sandbox-kits-v3.md) — the same two kits for the kit specification v3, under `docker-sbx-v3/`
  - [Add a skill](how-to/add-a-skill.md)
  - [Measure whether the model picks the right skill](how-to/measure-skill-routing.md) — the routing eval: run it, read its table, use it as a before-and-after
  - [Keep a long session inside the context window](how-to/manage-the-context-window.md)

modified docs/en/how-to/ask-another-agent-from-a-skill.md +2 -2 Viewed

@@ -69,8 +69,8 @@ This guide shows how to make a skill — or any shell script — put a question
69	69
70	70	## Variants
71	71
72		-- From a terminal or a script, outside mm. Name the configuration: `mm -config demo-llmman/agent.llmman.yaml --ask lucy -p "…"`, or put the question on stdin. Check the exit code: 0 answered, 1 failed (the reason is on stderr), 130 interrupted.
73		-- An agent that should only answer. Give it a configuration with `bashTool: false`, `editTools: false`, `planTool: false` and no skills — `demo-llmman/agent.lucy-reviewer.yaml` is one. A small model with every tool tends to wander (read files, load skills) when it is only asked for an opinion.
	72	+- From a terminal or a script, outside mm. Name the configuration: `mm -config demos/llmman/agent.llmman.yaml --ask lucy -p "…"`, or put the question on stdin. Check the exit code: 0 answered, 1 failed (the reason is on stderr), 130 interrupted.
	73	+- An agent that should only answer. Give it a configuration with `bashTool: false`, `editTools: false`, `planTool: false` and no skills — `demos/llmman/agent.lucy-reviewer.yaml` is one. A small model with every tool tends to wander (read files, load skills) when it is only asked for an opinion.
74	74	- Capture the answer in a variable. `answer=$("$MM_BIN" --ask jan -p "…")` — stdout holds the answer alone.
75	75
76	76	## See also

  ## Variants
--- **From a terminal or a script, outside mm.** Name the configuration: `mm -config demo-llmman/agent.llmman.yaml --ask lucy -p "…"`, or put the question on stdin. Check the exit code: 0 answered, 1 failed (the reason is on stderr), 130 interrupted.
++- **From a terminal or a script, outside mm.** Name the configuration: `mm -config demos/llmman/agent.llmman.yaml --ask lucy -p "…"`, or put the question on stdin. Check the exit code: 0 answered, 1 failed (the reason is on stderr), 130 interrupted.
--- **An agent that should only answer.** Give it a configuration with `bashTool: false`, `editTools: false`, `planTool: false` and no skills — `demo-llmman/agent.lucy-reviewer.yaml` is one. A small model with every tool tends to wander (read files, load skills) when it is only asked for an opinion.
++- **An agent that should only answer.** Give it a configuration with `bashTool: false`, `editTools: false`, `planTool: false` and no skills — `demos/llmman/agent.lucy-reviewer.yaml` is one. A small model with every tool tends to wander (read files, load skills) when it is only asked for an opinion.
  - **Capture the answer in a variable.** `answer=$("$MM_BIN" --ask jan -p "…")` — stdout holds the answer alone.
  ## See also

modified docs/en/how-to/ask-another-agent.md +6 -6 Viewed

@@ -4,10 +4,10 @@ This guide shows how to put a question to another mm agent — another model, an
4	4
5	5	## Steps
6	6
7		-1. Write (or reuse) one configuration file per agent you want to ask. Each is an ordinary mm configuration; `demo-llmman/` ships two, for llmman:
	7	+1. Write (or reuse) one configuration file per agent you want to ask. Each is an ordinary mm configuration; `demos/llmman/` ships two, for llmman:
8	8
9		- - `demo-llmman/agent.jan-nano.yaml` — `hf.co/Menlo/Jan-nano-gguf:Q4_K_M`, named Jan;
10		- - `demo-llmman/agent.lucy.yaml` — `hf.co/Menlo/Lucy-gguf:Q4_K_M`, named Lucy.
	9	+ - `demos/llmman/agent.jan-nano.yaml` — `hf.co/Menlo/Jan-nano-gguf:Q4_K_M`, named Jan;
	10	+ - `demos/llmman/agent.lucy.yaml` — `hf.co/Menlo/Lucy-gguf:Q4_K_M`, named Lucy.
11	11
12	12	2. Declare them in YOUR configuration, under `mmConfigs`. Paths are relative to the directory of the file you write them in:
13	13
@@ -17,13 +17,13 @@ This guide shows how to put a question to another mm agent — another model, an
17	17	lucy: agent.lucy.yaml
18	18	```
19	19
20		- `demo-llmman/agent.llmman.yaml` already does this.
	20	+ `demos/llmman/agent.llmman.yaml` already does this.
21	21
22	22	3. Start `mm` with that configuration:
23	23
24	24	```bash
25		- cd demo-llmman
26		- ../mm agent.llmman.yaml
	25	+ cd demos/llmman
	26	+ ../../mm agent.llmman.yaml
27	27	```
28	28
29	29	An agent whose file is missing shows up as a `[warning: mmConfigs: …]` line; the others work.

  ## Steps
--1. Write (or reuse) one configuration file per agent you want to ask. Each is an ordinary mm configuration; `demo-llmman/` ships two, for llmman:
++1. Write (or reuse) one configuration file per agent you want to ask. Each is an ordinary mm configuration; `demos/llmman/` ships two, for llmman:
--   - `demo-llmman/agent.jan-nano.yaml` — `hf.co/Menlo/Jan-nano-gguf:Q4_K_M`, named Jan;
++   - `demos/llmman/agent.jan-nano.yaml` — `hf.co/Menlo/Jan-nano-gguf:Q4_K_M`, named Jan;
--   - `demo-llmman/agent.lucy.yaml` — `hf.co/Menlo/Lucy-gguf:Q4_K_M`, named Lucy.
++   - `demos/llmman/agent.lucy.yaml` — `hf.co/Menlo/Lucy-gguf:Q4_K_M`, named Lucy.
 . Declare them in YOUR configuration, under `mmConfigs`. Paths are relative to the directory of the file you write them in:
       lucy: agent.lucy.yaml
     ```
--   `demo-llmman/agent.llmman.yaml` already does this.
++   `demos/llmman/agent.llmman.yaml` already does this.
 . Start `mm` with that configuration:
     ```bash
--   cd demo-llmman
++   cd demos/llmman
--   ../mm agent.llmman.yaml
++   ../../mm agent.llmman.yaml
     ```
     An agent whose file is missing shows up as a `[warning: mmConfigs: …]` line; the others work.

modified docs/en/how-to/get-json-answers.md +2 -2 Viewed

@@ -1,6 +1,6 @@
1	1	# How to get answers as JSON (`structuredOutput`)
2	2
3		-This guide shows how to make an agent answer only with JSON of a shape you declare, so that a script, `jq` or another agent can use the answer. It assumes you already run `mm` with a configuration file, on a server that supports `response_format: json_schema` (llama.cpp, so `dmr`, `llamacpp`, `llmman`; Ollama; the OpenAI API). The `demo-structured-output/` directory holds the files used below.
	3	+This guide shows how to make an agent answer only with JSON of a shape you declare, so that a script, `jq` or another agent can use the answer. It assumes you already run `mm` with a configuration file, on a server that supports `response_format: json_schema` (llama.cpp, so `dmr`, `llamacpp`, `llmman`; Ollama; the OpenAI API). The `demos/structured-output/` directory holds the files used below.
4	4
5	5	## Steps
6	6
@@ -53,7 +53,7 @@ This guide shows how to make an agent answer only with JSON of a shape you decla
53	53
54	54	## Variants
55	55
56		-- Let another agent use the JSON. Give a coordinator — an agent with tools — the JSON agent in its `mmConfigs`; it calls it with `ask_agent` and gets the JSON as the tool's result. See [How to let your agent call other agents](let-the-agent-call-other-agents.md) and `demo-structured-output/agent.coordinator.yaml`. The coordinator itself cannot have a `structuredOutput`: it has tools.
	56	+- Let another agent use the JSON. Give a coordinator — an agent with tools — the JSON agent in its `mmConfigs`; it calls it with `ask_agent` and gets the JSON as the tool's result. See [How to let your agent call other agents](let-the-agent-call-other-agents.md) and `demos/structured-output/agent.coordinator.yaml`. The coordinator itself cannot have a `structuredOutput`: it has tools.
57	57	- Ask the JSON agent through the coordinator's config, from a shell: `mm agent.coordinator.yaml --ask countries -p "capital of Vietnam" \| jq .` (see [How to ask another agent from a skill or a script](ask-another-agent-from-a-skill.md)).
58	58	- In the terminal or the window, the agent answers each question with JSON, shown like any answer.
59	59	- For the OpenAI hosted API, make the root a struct (`var Answer = Triage{}`): its strict mode demands an object at the top. llama.cpp and Ollama accept an array.

  # How to get answers as JSON (`structuredOutput`)
--This guide shows how to make an agent answer only with JSON of a shape you declare, so that a script, `jq` or another agent can use the answer. It assumes you already run `mm` with a configuration file, on a server that supports `response_format: json_schema` (llama.cpp, so `dmr`, `llamacpp`, `llmman`; Ollama; the OpenAI API). The `demo-structured-output/` directory holds the files used below.
++This guide shows how to make an agent answer only with JSON of a shape you declare, so that a script, `jq` or another agent can use the answer. It assumes you already run `mm` with a configuration file, on a server that supports `response_format: json_schema` (llama.cpp, so `dmr`, `llamacpp`, `llmman`; Ollama; the OpenAI API). The `demos/structured-output/` directory holds the files used below.
  ## Steps
  ## Variants
--- **Let another agent use the JSON.** Give a coordinator — an agent with tools — the JSON agent in its `mmConfigs`; it calls it with `ask_agent` and gets the JSON as the tool's result. See [How to let your agent call other agents](let-the-agent-call-other-agents.md) and `demo-structured-output/agent.coordinator.yaml`. The coordinator itself cannot have a `structuredOutput`: it has tools.
++- **Let another agent use the JSON.** Give a coordinator — an agent with tools — the JSON agent in its `mmConfigs`; it calls it with `ask_agent` and gets the JSON as the tool's result. See [How to let your agent call other agents](let-the-agent-call-other-agents.md) and `demos/structured-output/agent.coordinator.yaml`. The coordinator itself cannot have a `structuredOutput`: it has tools.
  - **Ask the JSON agent through the coordinator's config**, from a shell: `mm agent.coordinator.yaml --ask countries -p "capital of Vietnam" | jq .` (see [How to ask another agent from a skill or a script](ask-another-agent-from-a-skill.md)).
  - **In the terminal or the window**, the agent answers each question with JSON, shown like any answer.
  - **For the OpenAI hosted API**, make the root a struct (`var Answer = Triage{}`): its strict mode demands an object at the top. llama.cpp and Ollama accept an array.

modified docs/en/how-to/let-the-agent-call-other-agents.md +1 -1 Viewed

@@ -64,7 +64,7 @@ This guide shows how to give your agent a team: other mm agents it hands work to
64	64	- Ask an agent yourself. `/ask-<name>` and `/ask-with-context-<name>` still work, and keep the exchange in the history. See [How to ask another mm agent](ask-another-agent.md).
65	65	- Long work. Each event the agent streams keeps your agent's watchdog alive, but a long silence — a large model loading, a long first prompt — does not: raise your `watchdogTimeout` to cover it (10m for a 48 GB model on a laptop).
66	66	- From a script. `mm --ask <name>` remains the way for a shell command. See [How to ask another agent from a skill or a script](ask-another-agent-from-a-skill.md).
67		-- Working examples. `demo-llmman/agent.llmman.yaml` (Bob with Jan, Lucy and a reviewer) and `mini-mes/riker/agent.riker.yaml` (a coordinator, a specifier and a coder).
	67	+- Working examples. `demos/llmman/agent.llmman.yaml` (Bob with Jan, Lucy and a reviewer) and `demos/mini-mes/riker/agent.riker.yaml` (a coordinator, a specifier and a coder).
68	68
69	69	## See also
70	70

  - **Ask an agent yourself.** `/ask-<name>` and `/ask-with-context-<name>` still work, and keep the exchange in the history. See [How to ask another mm agent](ask-another-agent.md).
  - **Long work.** Each event the agent streams keeps your agent's watchdog alive, but a long silence — a large model loading, a long first prompt — does not: raise your `watchdogTimeout` to cover it (10m for a 48 GB model on a laptop).
  - **From a script.** `mm --ask <name>` remains the way for a shell command. See [How to ask another agent from a skill or a script](ask-another-agent-from-a-skill.md).
--- **Working examples.** `demo-llmman/agent.llmman.yaml` (Bob with Jan, Lucy and a reviewer) and `mini-mes/riker/agent.riker.yaml` (a coordinator, a specifier and a coder).
++- **Working examples.** `demos/llmman/agent.llmman.yaml` (Bob with Jan, Lucy and a reviewer) and `demos/mini-mes/riker/agent.riker.yaml` (a coordinator, a specifier and a coder).
  ## See also

modified docs/en/how-to/run-in-a-docker-sandbox.md +70 -116 Viewed

@@ -1,90 +1,80 @@
1	1	# How to run mini-me in a Docker Sandbox
2	2
3		-This guide shows how to run `mm` inside a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/), so that every command the model runs and every file it edits happens in a container, on a mounted copy of your project. It covers the two ways of using it: the window mode in your terminal, and from an editor through the Agent Client Protocol. It assumes Docker Desktop with the `sbx` command, and a model server (Docker Model Runner or llama-server) running on your machine.
	3	+This guide shows how to run `mm` inside a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/), so that every command the model runs and every file it edits happens in a container, on a mounted copy of your project. It covers the window mode in your terminal and an editor through the Agent Client Protocol. It assumes Docker Desktop with the `sbx` command, and a model server running on your machine.
4	4
5		-> These are the v2 kits (`spec.yaml`). The same two kits also exist for the kit specification v3, under `docker-sbx-v3/`: see [Run mini-me with the v3 sandbox kits](run-with-sandbox-kits-v3.md).
	5	+Everything lives under [`sbx/`](../../../sbx/README.md) in the repository. The kits follow the [kit specification v3](https://github.com/docker/sandbox-kit-spec) (`schemaVersion: "3"`): one workload that runs `mm`, and mixins you add to it with `--kit`.
6	6
7		-Everything lives under [`docker-sbx/`](../../../docker-sbx/README.md) in the repository:
	7	+\| Piece \| Where \| What it is \|
	8	+\|---\|---\|---\|
	9	+\| `mini-me` \| [bots-garden/mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), directory `mini-me/` \| The workload: Docker's `shell` template (Ubuntu, user `agent`) with the `mm` binary of a release (`mm_version`, default `v0.3.0`), downloaded from mini-me's release page. Entry point `mm`, default arguments `-tui`. Versioned by its own tags (`v0.0.1`). \|
	10	+\| `go-toolchain` \| `sbx/kits/go-toolchain/` \| A mixin: Go (`go_version`, default `1.27.2`), `gofmt` and `gopls` (`gopls_version`, default `latest`). Allows the module hosts at runtime: `proxy.golang.org`, `sum.golang.org`, `github.com`, `golang.org`. \|
	11	+\| `cli-tools` \| `sbx/kits/cli-tools/` \| A mixin: `rg`, `bat` and `eza` as static binaries. No runtime network. \|
	12	+\| `agent.yaml`, `agent.lucy.yaml` \| `sbx/` \| Two `mm` configurations for llmman (Jan-nano, Lucy). \|
	13	+\| `AGENTS.md` \| `sbx/` \| Instructions for the agent working inside the sandbox (the tools installed, how to run Go): `mm` adds it to its system prompt when it runs in that directory — see [How to give the agent your project's instructions](give-project-instructions.md). \|
8	14
9		-\| Piece \| What it is \|
10		-\|---\|---\|
11		-\| `template/Dockerfile` \| The template: Docker Sandboxes' `shell` image with `mm` built from this checkout, plus the two entry points below. \|
12		-\| `kits/mm-tui/spec.yaml` \| A sandbox kit: `sbx run` on it opens `mm`'s window mode on the workspace. \|
13		-\| `kits/mm-acp/spec.yaml` \| A sandbox kit for an editor: created once with `sbx create`, the editor then runs `mm -acp` inside it. \|
14		-\| `build.sh` \| Builds the template image, `k33g/mm-sandbox:<version>`; `PUSH=1` builds it for linux/amd64 and linux/arm64 and pushes it. \|
15		-\| `sync-kits.sh`, `push-kits.sh` \| Point the kits at one image, and publish them to Docker Hub as OCI kit artifacts. \|
	15	+## Steps
16	16
17		-## Use the published kits
	17	+### 1. Allow the kit's source
18	18
19		-Every release publishes the image and both kits to Docker Hub at mm's version — `k33g/mm-sandbox:0.2.1`, `k33g/mm-tui:0.2.1`, `k33g/mm-acp:0.2.1` — so the shortest path needs no build at all. Docker Hub is an allowed kit source by default (`sbx settings get kit.allowedSources` shows `docker.io/`), and a reference with a `/` but no registry host is read as `docker.io/…`:
	19	+The `mini-me` kit is referenced by git URL, a tag and its directory. Its host must be an allowed kit source, once:
20	20
21	21	```bash
22		-cd /path/to/your/project
23		-sbx run k33g/mm-tui:0.2.1 . -- agent.dmr.yaml
	22	+sbx settings set kit.allowedSources '["docker.io/","git.rickub.com/bots-garden/"]'
24	23	```
25	24
26		-for the window mode, and for an editor:
27		-
28		-```bash
29		-sbx create --name mm-acp k33g/mm-acp:0.2.1 . --kit-arg config=agent.dmr.yaml
30		-```
	25	+### 2. Window mode in the terminal
31	26
32		-then the editor registration of step 3 below. No `--pull never`: the kit names `k33g/mm-sandbox:0.2.1` and sbx pulls it. `sbx kit inspect k33g/mm-tui:0.2.1` shows what a kit declares before you run it. The steps that follow build the same thing locally, for a work-in-progress mm.
33		-
34		-## Steps
35		-
36		-### 1. Build the template
37		-
38		-From the repository root:
	27	+From the directory you want `mm` to work on — `sbx/` itself, to use its configurations and its `AGENTS.md`:
39	28
40	29	```bash
41		-./docker-sbx/build.sh
	30	+cd sbx
	31	+RELEASE=v0.0.1
	32	+REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
	33	+sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me"
42	34	```
43	35
44		-This reads mm's tag from `release.env` (`v0.2.1`) and builds `k33g/mm-sandbox:0.2.1`: the image tag is the version without the `v`, like the release assets, and `mm` inside is stamped with the tag — `mm --version` is run in the image as proof. The script then rewrites the kits' default `tag` argument to `0.2.1`, so the kits and the image move together. `./docker-sbx/build.sh v0.1.5` builds another version; an earlier image stays reachable with `--kit-arg tag=0.1.4`.
45		-
46		-The image is in your local Docker image store: every `sbx run` or `sbx create` on these kits takes `--pull never` until the image is pushed (`docker push k33g/mm-sandbox:0.2.1`), or `sbx` tries to pull it and fails. If `sbx` runs on another machine, `EXPORT=1 ./docker-sbx/build.sh` also writes `tmp/mm-sandbox-0.2.1.tar`, to load there with `sbx template load`.
47		-
48		-### 2. Window mode in the terminal (kit `mm-tui`)
49		-
50		-From the project you want `mm` to work on:
	36	+The first run builds the kit, creates the sandbox, mounts the current directory as its workspace and runs `mm -tui`, which reads `./agent.yaml`. Add the mixins with `--kit`; what follows `--` replaces the default arguments, so it is `mm`'s whole command line:
51	37
52	38	```bash
53		-sbx run --pull never ./docker-sbx/kits/mm-tui . -- agent.dmr.yaml
	39	+sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" \
	40	+ --kit ./kits/go-toolchain --kit ./kits/cli-tools \
	41	+ -- -tui -config agent.lucy.yaml
54	42	```
55	43
56		-The first time, `sbx` creates the sandbox, mounts the current directory as its workspace and attaches; then it runs the kit's entry point with what follows `--` as arguments — here `mm -tui agent.dmr.yaml`, in the workspace. Any `mm` flag passes the same way: `-- -config other.yaml`.
	44	+The sandbox keeps its name; `sbx run --name mm-demo-remote` attaches to it again later. The window is the one described in [Use the window mode](use-the-window-mode.md). Sessions, when `sessions.enabled` is on, are written under the workspace's `.mm/sessions` — your host directory — so they survive the sandbox.
57	45
58		-Without anything after `--`, `mm` reads the kit's `config` argument, then `./agent.yaml` in the workspace, then its built-in defaults:
	46	+To work on the kit itself, clone [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) and run it from its `demo/` directory: `sbx run --name mm-demo ../mini-me`.
59	47
60		-```bash
61		-sbx run --pull never ./docker-sbx/kits/mm-tui . --kit-arg config=agent.dmr.yaml
62		-```
63		-
64		-\| `--kit-arg` \| Default \| Effect \|
65		-\|---\|---\|---\|
66		-\| `config=<path>` \| empty \| The configuration file, as `mm`'s `AGENT_CONFIG`: relative to the workspace, or absolute inside the sandbox. \|
67		-\| `tag=<version>` \| the version last built (`0.2.1`) \| Which `k33g/mm-sandbox:<version>` image the sandbox is made from. \|
	48	+### 3. From an editor (ACP)
68	49
69		-The sandbox keeps its name (`mm-tui-<directory>` unless you pass `--name`); `sbx run --name <name>` re-attaches to it later. Inside, the window is the one described in [Use the window mode](use-the-window-mode.md). Sessions, when `sessions.enabled` is on, are written under the workspace's `.mm/sessions` — that is your host directory, so they survive the sandbox.
	50	+An editor talks to `mm -acp` over raw stdin and stdout, which `sbx run` cannot carry (it always allocates a terminal). Create the sandbox once without attaching, then let the editor start `mm` inside it with `sbx exec -i`:
70	51
71		-### 3. From an editor (kit `mm-acp`)
	52	+1. From the project the editor will open, with the kit's remote reference:
72	53
73		-An editor talks to `mm -acp` over the agent's raw stdin and stdout. `sbx run` cannot carry that: it always allocates a terminal. So the sandbox is created once without attaching, and the editor starts `mm` inside it with `sbx exec -i`, which pipes stdin and stdout untouched.
	54	+ ```bash
	55	+ RELEASE=v0.0.1
	56	+ REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
	57	+ sbx create --name mm-acp "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" . \
	58	+ --kit /path/to/mini-me/sbx/kits/go-toolchain
	59	+ ```
74	60
75		-1. From the project the editor will open, create the sandbox with the configuration file baked in (`.` is the workspace, sbx makes it absolute; the kit path must be an explicit `./`, `../` or absolute path):
	61	+ or with a local clone of [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) (a kit path must start with `./`, `../` or `/`):
76	62
77	63	```bash
78		- cd /path/to/your/project
79		- sbx create --pull never --name mm-acp /path/to/mini-me/docker-sbx/kits/mm-acp . \
80		- --kit-arg config=agent.dmr.yaml
	64	+ git clone https://git.rickub.com/bots-garden/mini-me-kit.git /path/to/mini-me-kit
	65	+ sbx create --name mm-acp /path/to/mini-me-kit/mini-me . \
	66	+ --kit /path/to/mini-me/sbx/kits/go-toolchain
81	67	```
82	68
83		- A workspace path that does not exist on your machine makes sbx ask "The selected workspace does not exist. Would you like to create it?" — answer `N` and fix the path.
	69	+ The workspace (`.`) is fixed at creation: one sandbox per project, each with its own `--name`.
	70	+
	71	+2. Check it by hand:
84	72
85		- `--kit-arg config` becomes the container's `AGENT_CONFIG`, relative to the workspace because that is where `sbx exec` starts `mm`. The workspace is fixed at creation: one sandbox per project, each with its own `--name`.
	73	+ ```bash
	74	+ sbx exec -i mm-acp mm -acp -config agent.lucy.yaml
	75	+ ```
86	76
87		-2. Register it in the editor. In Zed's `settings.json`:
	77	+3. Register it in Zed's `settings.json`:
88	78
89	79	```json
90	80	{
@@ -92,91 +82,55 @@ An editor talks to `mm -acp` over the agent's raw stdin and stdout. `sbx run` ca
92	82	"mini-me (sandbox)": {
93	83	"type": "custom",
94	84	"command": "sbx",
95		- "args": ["exec", "-i", "mm-acp", "mm", "-acp"]
	85	+ "args": ["exec", "-i", "mm-acp", "mm", "-acp", "-config", "agent.lucy.yaml"]
96	86	}
97	87	}
98	88	}
99	89	```
100	90
101		- Compared with [the host-side setup](use-from-an-editor.md), the command is `sbx` and no `env` is needed: `AGENT_CONFIG` is already in the container. If the editor cannot find `sbx`, put the absolute path from `which sbx` in `"command"`.
102		-
103		-3. Open the agent panel and pick mini-me (sandbox). The editor starts `mm -acp` in the sandbox for every conversation; `sbx exec` starts the sandbox first when it is stopped. Tool calls, permission dialogs, `@file` mentions and the slash-command menu work as they do on the host — the difference is where the commands run.
104		-
105		-Attaching to this sandbox with `sbx run --name mm-acp` does not start `mm`: its entry point prints the wiring above with the sandbox's real name and paths, then opens a shell inside the sandbox. `sbx exec -it mm-acp bash` is the shorter way to that shell.
	91	+ If the editor cannot find `sbx`, put the absolute path from `which sbx` in `"command"`. Tool calls, permission dialogs, `@file` mentions and the slash-command menu work as on the host; the difference is where the commands run. See [Use mini-me from an editor](use-from-an-editor.md) for the host-side setup.
106	92
107	93	## The model server stays on the host
108	94
109		-Inside a sandbox `localhost` is the sandbox itself. Your model server keeps running on your machine and is reached through `host.docker.internal`, which the sandbox proxy maps to your host's `localhost`.
110		-
111		-- Docker Model Runner — nothing to change: `agent.dmr.yaml` already has `fallback: http://host.docker.internal:12434/engines/v1`, and `mm` switches to it when `localhost:12434` does not answer (the banner says which URL won).
112		-- llama-server — `agent.llamacpp.yaml` has no fallback. Either edit its `baseUrl` to `http://host.docker.internal:8080/v1`, or pass `--env AGENT_BASE_URL=http://host.docker.internal:8080/v1` to `sbx run` / `sbx create` (see [Run with llama.cpp](run-with-llama-cpp.md)).
113		-
114		-Both kits allow ports 12434 and 8080 on the host in the sandbox's network policy. For another port: `sbx policy allow network host.docker.internal:<port>`.
115		-
116		-## Publishing a version
117		-
118		-Publishing is a manual step, from a machine with Docker Desktop (buildx and the `sbx` CLI); the Release workflow builds only the binaries. One script builds the image for linux/amd64 and linux/arm64, pushes it, then validates and pushes the two kits, all at mm's tag:
119		-
120		-```bash
121		-export DOCKER_HANDLE=k33g # the Docker Hub account, also the image owner
122		-export DOCKER_PAT=dckr_pat_… # an access token with read/write scope
123		-./docker-sbx/publish.sh # TAG from release.env: v0.2.1 → k33g/mm-sandbox:0.2.1, k33g/mm-tui:0.2.1, k33g/mm-acp:0.2.1
124		-```
125		-
126		-With both variables set, the script logs in with them and logs out when it is done; with neither, it reuses your existing `docker login`. Its two halves run alone as `PUSH=1 ./docker-sbx/build.sh v0.2.1` (image) and `./docker-sbx/push-kits.sh v0.2.1` (kits, `SBX=/path/to/sbx` if the CLI is not on the PATH). Both call `sync-kits.sh` first, which rewrites the kits' `version`, default `tag` and image owner, so a published kit always names the image pushed with it — commit the two `spec.yaml` afterwards. `sbx kit push` talks to the registry directly and authenticates from the Docker credential store, no sandbox daemon involved. `IMAGE_OWNER=<handle>` publishes under another account.
	95	+Inside a sandbox `localhost` is the sandbox itself. Your model server keeps running on your machine and is reached through `host.docker.internal`, which the sandbox proxy maps to your host.
127	96
128		-## MCP servers through the sbx gateway (GitHub as the example)
	97	+- The `mini-me` kit's network policy allows `host.docker.internal:12434` (Docker Model Runner), `:11434` (Ollama) and `:17434` (llmman). `agent.dmr.yaml` already falls back to `http://host.docker.internal:12434/engines/v1`; the configurations shipped in `sbx/` use llmman (`fallback: http://host.docker.internal:17434/v1`).
	98	+- For another port — llama-server's `8080`, for instance — add it to the kit's `network-policy` capability, or allow it for one sandbox:
129	99
130		-Inside a sandbox, `mm` does not talk to MCP servers itself and holds no token. `sbx` starts one MCP gateway per sandbox, on the host. When it creates the sandbox, it bakes two variables into the container: `MCP_GATEWAY_URL` (`http://mcp-gateway.docker.internal/mcp`) and `MCP_SENTINEL_TOKEN_NAME`, a placeholder that the sandbox proxy swaps for the real credential. When `mm` finds `MCP_GATEWAY_URL` and `mcp.enabled: true`, it adds a server called `sbx-gateway`, and its tools show up as `sbx-gateway_<tool>`. The kit needs no network rule for it, because the proxy routes that host itself.
	100	+ ```bash
	101	+ sbx policy allow network host.docker.internal:8080
	102	+ ```
131	103
132		-1. Register GitHub's official server once, on the host, through `docker-sbx/mcp/github-mcp.sh`. The script starts `ghcr.io/github/github-mcp-server` in Docker with your token. sbx runs it as a child of sandboxd, which does not see your shell's variables. So store the token once in the macOS keychain under the service `github-mcp`. The script also accepts `GITHUB_PERSONAL_ACCESS_TOKEN`, `GITHUB_OAUTH_TOKEN` or a logged-in `gh`. sbx runs it on the host, so the token never enters the sandbox. By default it exposes a read-only set of 25 tools, including `get_me` and `get_teams`. Set `GITHUB_READ_ONLY=0` and a wider `GITHUB_TOOLSETS` in the script's environment for more.
	104	+ `sbx policy log` shows what was blocked.
133	105
134		- ```bash
135		- security add-generic-password -U -a "$USER" -s github-mcp -w # prompts for the token
136		- sbx mcp rm github 2>/dev/null # an earlier "github" is the ARCHIVED catalog server
137		- sbx mcp add github-mm --command "$PWD/docker-sbx/mcp/github-mcp.sh"
138		- sbx mcp ls # github-mm must be ready
139		- ```
140		-
141		- Do not use the name `github` alone. The Docker MCP catalog resolves it to "GitHub (Archived)", the old npm server, which has no `get_me` and returns other tools. The catalog's `github-official` does not help in sbx's local mode either. There, a catalog image is started as a bare `docker run` with no environment, so it would get no token.
142		-
143		-2. Create a new sandbox with that server in its fixed set. `--static-mcp` is an `sbx` flag: it goes before `--`, since everything after `--` goes to `mm`. It only applies at creation, so remove an older sandbox of the same name first:
144		-
145		- ```bash
146		- cd /path/to/project
147		- sbx rm mm-mcp-github 2>/dev/null
148		- sbx run --name mm-mcp-github --static-mcp github-mm k33g/mm-tui:<version> . -- agent.dmr.sbx.yaml
149		- ```
	106	+## Change a version
150	107
151		-3. The configuration only needs MCP turned on. `demo/agent.dmr.sbx.yaml` has:
	108	+- mm: the `default` of `mm_version` in `mini-me/mini-me.yaml` of the [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) repository — a release tag such as `v0.3.0`; the kit's own tag (`RELEASE` above) then names the new kit. The build downloads `https://rickub.com/bots-garden/mini-me/releases/download/<tag>/mm-<version>-linux-<arch>`; a tag with no such release fails the build.
	109	+- Go, gopls, rg, bat, eza: the `default` of the matching argument in the mixin's YAML (`go_version`, `gopls_version`, `rg_version`, `bat_version`, `eza_version`); each one has a `pattern` that refuses a malformed version.
152	110
153		- ```yaml
154		- mcp:
155		- enabled: true
156		- permissions: ask
157		- discoveryTimeout: 10s
158		- servers: [] # the gateway is added by mm when MCP_GATEWAY_URL is set
159		- ```
	111	+## MCP servers through the sbx gateway
160	112
161		- The banner then lists `sbx-gateway_get_me`, `sbx-gateway_list_issues`, and so on in `tools:`.
	113	+Inside a sandbox, `mm` does not talk to MCP servers itself and holds no token. `sbx` runs one MCP gateway per sandbox, on the host, and bakes `MCP_GATEWAY_URL` into the container. When `mm` finds `MCP_GATEWAY_URL` and `mcp.enabled: true`, it adds a server called `sbx-gateway`, and its tools show up as `sbx-gateway_<tool>`:
162	114
163		-A kit image built before this change cannot use the gateway. It discovers nothing and warns `method "tools/list" is invalid during session initialization`. The gateway follows MCP's Streamable HTTP transport strictly: it needs `initialize` first, then the `Mcp-Session-Id` it returns on every request. Older `mm` skipped both. That was harmless against `api.githubcopilot.com` but fatal here. Rebuild and publish the kit after upgrading.
164		-
165		-If the banner lists no `sbx-gateway_*` tools, check the registration with `sbx mcp inspect github-mm`, then read sbx's MCP log, `mcp/mcp.log` under its state directory. `github-mcp: no token` there means the script found no token: check the keychain item with `security find-generic-password -s github-mcp`. The remote endpoint `https://api.githubcopilot.com/mcp/` is another route, but only with a GitHub OAuth App. GitHub offers no dynamic client registration, so in local mode `sbx mcp add` refuses it without `--client-id`, even with an `Authorization` header.
	115	+```yaml
	116	+mcp:
	117	+ enabled: true
	118	+ permissions: ask
	119	+ discoveryTimeout: 10s
	120	+ servers: [] # the gateway is added by mm when MCP_GATEWAY_URL is set
	121	+```
166	122
167		-Name the repository in your requests, for example "list the open issues of k33g/my-repo". A small model given only "my organization" invents an owner and a repository, and every call comes back `Not Found`.
	123	+Register the server on the host (`sbx mcp add <name> --command <script>`), then create a new sandbox with it in its fixed set — `--static-mcp <name>` is an `sbx` flag and goes before `--`. If no `sbx-gateway_*` tool appears in the banner, `sbx mcp inspect <name>` and sbx's `mcp/mcp.log` say why.
168	124
169	125	## Variants
170	126
171		-- Another configuration for one editor session. Add `"-e", "AGENT_CONFIG=agent.lsp.yaml"` before the sandbox name in `"args"`; `sbx exec -e` overrides the baked-in value for that run only.
172		-- Skills. `skillsDir` is relative to the directory `mm` runs in, which is the workspace in both kits — the same rule as on the host.
173		-- Docker inside the sandbox. Build the template on the Docker-in-Docker shell instead: `SHELL_TEMPLATE=docker/sandbox-templates:shell-docker ./docker-sbx/build.sh`.
	127	+- Skills. `skillsDir` is relative to the directory `mm` runs in — the workspace — as on the host.
174	128	- Read the logs. In the window mode they are on screen; over ACP they go to stderr, which Zed shows under `dev: open acp logs`.
	129	+- A shell in the sandbox. `sbx exec -it mm-acp bash`.
175	130	- Remove a sandbox. `sbx rm mm-acp`. The project directory is a bind mount and is not touched.
176	131
177	132	## See also
178	133
179		-- The kit format these two files follow: the Docker Sandboxes kit specification (`schemaVersion: "2"`), bundled with the `sbx` sources.
180		-- The same kits for the kit specification v3: [Run mini-me with the v3 sandbox kits](run-with-sandbox-kits-v3.md).
	134	+- The kit format: [specification v3](https://github.com/docker/sandbox-kit-spec).
181	135	- What `mm -acp` exposes to the editor: [ACP reference](../reference/acp.md).
182	136	- The flags and environment variables `mm` reads: [command line reference](../reference/cli.md).

  # How to run mini-me in a Docker Sandbox
--This guide shows how to run `mm` inside a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/), so that every command the model runs and every file it edits happens in a container, on a mounted copy of your project. It covers the two ways of using it: the window mode in your terminal, and from an editor through the Agent Client Protocol. It assumes Docker Desktop with the `sbx` command, and a model server (Docker Model Runner or llama-server) running on your machine.
++This guide shows how to run `mm` inside a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/), so that every command the model runs and every file it edits happens in a container, on a mounted copy of your project. It covers the window mode in your terminal and an editor through the Agent Client Protocol. It assumes Docker Desktop with the `sbx` command, and a model server running on your machine.
--> These are the **v2** kits (`spec.yaml`). The same two kits also exist for the kit specification v3, under `docker-sbx-v3/`: see [Run mini-me with the v3 sandbox kits](run-with-sandbox-kits-v3.md).
++Everything lives under [`sbx/`](../../../sbx/README.md) in the repository. The kits follow the [kit specification v3](https://github.com/docker/sandbox-kit-spec) (`schemaVersion: "3"`): one **workload** that runs `mm`, and **mixins** you add to it with `--kit`.
--Everything lives under [`docker-sbx/`](../../../docker-sbx/README.md) in the repository:
++| Piece | Where | What it is |
++|---|---|---|
++| `mini-me` | [bots-garden/mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), directory `mini-me/` | The **workload**: Docker's `shell` template (Ubuntu, user `agent`) with the `mm` binary of a release (`mm_version`, default `v0.3.0`), downloaded from mini-me's release page. Entry point `mm`, default arguments `-tui`. Versioned by its own tags (`v0.0.1`). |
++| `go-toolchain` | `sbx/kits/go-toolchain/` | A **mixin**: Go (`go_version`, default `1.27.2`), `gofmt` and `gopls` (`gopls_version`, default `latest`). Allows the module hosts at runtime: `proxy.golang.org`, `sum.golang.org`, `github.com`, `golang.org`. |
++| `cli-tools` | `sbx/kits/cli-tools/` | A **mixin**: `rg`, `bat` and `eza` as static binaries. No runtime network. |
++| `agent.yaml`, `agent.lucy.yaml` | `sbx/` | Two `mm` configurations for llmman (Jan-nano, Lucy). |
++| `AGENTS.md` | `sbx/` | Instructions for the agent working inside the sandbox (the tools installed, how to run Go): `mm` adds it to its system prompt when it runs in that directory — see [How to give the agent your project's instructions](give-project-instructions.md). |
--| Piece | What it is |
++## Steps
--|---|---|
--| `template/Dockerfile` | The **template**: Docker Sandboxes' `shell` image with `mm` built from this checkout, plus the two entry points below. |
--| `kits/mm-tui/spec.yaml` | A **sandbox kit**: `sbx run` on it opens `mm`'s window mode on the workspace. |
--| `kits/mm-acp/spec.yaml` | A **sandbox kit** for an editor: created once with `sbx create`, the editor then runs `mm -acp` inside it. |
--| `build.sh` | Builds the template image, `k33g/mm-sandbox:<version>`; `PUSH=1` builds it for linux/amd64 and linux/arm64 and pushes it. |
--| `sync-kits.sh`, `push-kits.sh` | Point the kits at one image, and publish them to Docker Hub as OCI kit artifacts. |
--## Use the published kits
++### 1. Allow the kit's source
--Every release publishes the image and both kits to Docker Hub at mm's version — `k33g/mm-sandbox:0.2.1`, `k33g/mm-tui:0.2.1`, `k33g/mm-acp:0.2.1` — so the shortest path needs no build at all. Docker Hub is an allowed kit source by default (`sbx settings get kit.allowedSources` shows `docker.io/`), and a reference with a `/` but no registry host is read as `docker.io/…`:
++The `mini-me` kit is referenced by git URL, a tag and its directory. Its host must be an allowed kit source, once:
  ```bash
--cd /path/to/your/project
++sbx settings set kit.allowedSources '["docker.io/","git.rickub.com/bots-garden/"]'
--sbx run k33g/mm-tui:0.2.1 . -- agent.dmr.yaml
  ```
--for the window mode, and for an editor:
++### 2. Window mode in the terminal
--
--```bash
--sbx create --name mm-acp k33g/mm-acp:0.2.1 . --kit-arg config=agent.dmr.yaml
--```
--then the editor registration of step 3 below. No `--pull never`: the kit names `k33g/mm-sandbox:0.2.1` and sbx pulls it. `sbx kit inspect k33g/mm-tui:0.2.1` shows what a kit declares before you run it. The steps that follow build the same thing locally, for a work-in-progress mm.
++From the directory you want `mm` to work on — `sbx/` itself, to use its configurations and its `AGENTS.md`:
--
--## Steps
--
--### 1. Build the template
--
--From the repository root:
  ```bash
--./docker-sbx/build.sh
++cd sbx
++RELEASE=v0.0.1
++REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
++sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me"
  ```
--This reads mm's tag from `release.env` (`v0.2.1`) and builds `k33g/mm-sandbox:0.2.1`: the image tag is the version without the `v`, like the release assets, and `mm` inside is stamped with the tag — `mm --version` is run in the image as proof. The script then rewrites the kits' default `tag` argument to `0.2.1`, so the kits and the image move together. `./docker-sbx/build.sh v0.1.5` builds another version; an earlier image stays reachable with `--kit-arg tag=0.1.4`.
++The first run builds the kit, creates the sandbox, mounts the current directory as its workspace and runs `mm -tui`, which reads `./agent.yaml`. Add the mixins with `--kit`; what follows `--` replaces the default arguments, so it is `mm`'s whole command line:
--
--The image is in your local Docker image store: every `sbx run` or `sbx create` on these kits takes `--pull never` until the image is pushed (`docker push k33g/mm-sandbox:0.2.1`), or `sbx` tries to pull it and fails. If `sbx` runs on another machine, `EXPORT=1 ./docker-sbx/build.sh` also writes `tmp/mm-sandbox-0.2.1.tar`, to load there with `sbx template load`.
--
--### 2. Window mode in the terminal (kit `mm-tui`)
--
--From the project you want `mm` to work on:
  ```bash
--sbx run --pull never ./docker-sbx/kits/mm-tui . -- agent.dmr.yaml
++sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" \
++    --kit ./kits/go-toolchain --kit ./kits/cli-tools \
++    -- -tui -config agent.lucy.yaml
  ```
--The first time, `sbx` creates the sandbox, mounts the current directory as its workspace and attaches; then it runs the kit's entry point with what follows `--` as arguments — here `mm -tui agent.dmr.yaml`, in the workspace. Any `mm` flag passes the same way: `-- -config other.yaml`.
++The sandbox keeps its name; `sbx run --name mm-demo-remote` attaches to it again later. The window is the one described in [Use the window mode](use-the-window-mode.md). Sessions, when `sessions.enabled` is on, are written under the workspace's `.mm/sessions` — your host directory — so they survive the sandbox.
--Without anything after `--`, `mm` reads the kit's `config` argument, then `./agent.yaml` in the workspace, then its built-in defaults:
++To work on the kit itself, clone [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) and run it from its `demo/` directory: `sbx run --name mm-demo ../mini-me`.
--```bash
++### 3. From an editor (ACP)
--sbx run --pull never ./docker-sbx/kits/mm-tui . --kit-arg config=agent.dmr.yaml
--```
--
--| `--kit-arg` | Default | Effect |
--|---|---|---|
--| `config=<path>` | empty | The configuration file, as `mm`'s `AGENT_CONFIG`: relative to the workspace, or absolute inside the sandbox. |
--| `tag=<version>` | the version last built (`0.2.1`) | Which `k33g/mm-sandbox:<version>` image the sandbox is made from. |
--The sandbox keeps its name (`mm-tui-<directory>` unless you pass `--name`); `sbx run --name <name>` re-attaches to it later. Inside, the window is the one described in [Use the window mode](use-the-window-mode.md). Sessions, when `sessions.enabled` is on, are written under the workspace's `.mm/sessions` — that is your host directory, so they survive the sandbox.
++An editor talks to `mm -acp` over raw stdin and stdout, which `sbx run` cannot carry (it always allocates a terminal). Create the sandbox once without attaching, then let the editor start `mm` inside it with `sbx exec -i`:
--### 3. From an editor (kit `mm-acp`)
++1. From the project the editor will open, with the kit's remote reference:
--An editor talks to `mm -acp` over the agent's raw stdin and stdout. `sbx run` cannot carry that: it always allocates a terminal. So the sandbox is created once without attaching, and the editor starts `mm` inside it with `sbx exec -i`, which pipes stdin and stdout untouched.
++   ```bash
++   RELEASE=v0.0.1
++   REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
++   sbx create --name mm-acp "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" . \
++       --kit /path/to/mini-me/sbx/kits/go-toolchain
++   ```
--1. From the project the editor will open, create the sandbox with the configuration file baked in (`.` is the workspace, sbx makes it absolute; the kit path must be an explicit `./`, `../` or absolute path):
++   or with a local clone of [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) (a kit path must start with `./`, `../` or `/`):
     ```bash
--   cd /path/to/your/project
++   git clone https://git.rickub.com/bots-garden/mini-me-kit.git /path/to/mini-me-kit
--   sbx create --pull never --name mm-acp /path/to/mini-me/docker-sbx/kits/mm-acp . \
++   sbx create --name mm-acp /path/to/mini-me-kit/mini-me . \
--       --kit-arg config=agent.dmr.yaml
++       --kit /path/to/mini-me/sbx/kits/go-toolchain
     ```
--   A workspace path that does not exist on your machine makes sbx ask "The selected workspace does not exist. Would you like to create it?" — answer `N` and fix the path.
++   The workspace (`.`) is fixed at creation: one sandbox per project, each with its own `--name`.
++
++2. Check it by hand:
--   `--kit-arg config` becomes the container's `AGENT_CONFIG`, relative to the workspace because that is where `sbx exec` starts `mm`. The workspace is fixed at creation: one sandbox per project, each with its own `--name`.
++   ```bash
++   sbx exec -i mm-acp mm -acp -config agent.lucy.yaml
++   ```
--2. Register it in the editor. In Zed's `settings.json`:
++3. Register it in Zed's `settings.json`:
     ```json
     {
         "mini-me (sandbox)": {
           "type": "custom",
           "command": "sbx",
--         "args": ["exec", "-i", "mm-acp", "mm", "-acp"]
++         "args": ["exec", "-i", "mm-acp", "mm", "-acp", "-config", "agent.lucy.yaml"]
         }
       }
     }
     ```
--   Compared with [the host-side setup](use-from-an-editor.md), the command is `sbx` and no `env` is needed: `AGENT_CONFIG` is already in the container. If the editor cannot find `sbx`, put the absolute path from `which sbx` in `"command"`.
++   If the editor cannot find `sbx`, put the absolute path from `which sbx` in `"command"`. Tool calls, permission dialogs, `@file` mentions and the slash-command menu work as on the host; the difference is where the commands run. See [Use mini-me from an editor](use-from-an-editor.md) for the host-side setup.
--
--3. Open the agent panel and pick **mini-me (sandbox)**. The editor starts `mm -acp` in the sandbox for every conversation; `sbx exec` starts the sandbox first when it is stopped. Tool calls, permission dialogs, `@file` mentions and the slash-command menu work as they do on the host — the difference is where the commands run.
--
--Attaching to this sandbox with `sbx run --name mm-acp` does not start `mm`: its entry point prints the wiring above with the sandbox's real name and paths, then opens a shell inside the sandbox. `sbx exec -it mm-acp bash` is the shorter way to that shell.
  ## The model server stays on the host
--Inside a sandbox `localhost` is the sandbox itself. Your model server keeps running on your machine and is reached through `host.docker.internal`, which the sandbox proxy maps to your host's `localhost`.
++Inside a sandbox `localhost` is the sandbox itself. Your model server keeps running on your machine and is reached through `host.docker.internal`, which the sandbox proxy maps to your host.
--
--- **Docker Model Runner** — nothing to change: `agent.dmr.yaml` already has `fallback: http://host.docker.internal:12434/engines/v1`, and `mm` switches to it when `localhost:12434` does not answer (the banner says which URL won).
--- **llama-server** — `agent.llamacpp.yaml` has no fallback. Either edit its `baseUrl` to `http://host.docker.internal:8080/v1`, or pass `--env AGENT_BASE_URL=http://host.docker.internal:8080/v1` to `sbx run` / `sbx create` (see [Run with llama.cpp](run-with-llama-cpp.md)).
--
--Both kits allow ports 12434 and 8080 on the host in the sandbox's network policy. For another port: `sbx policy allow network host.docker.internal:<port>`.
--
--## Publishing a version
--
--Publishing is a manual step, from a machine with Docker Desktop (buildx and the `sbx` CLI); the Release workflow builds only the binaries. One script builds the image for linux/amd64 and linux/arm64, pushes it, then validates and pushes the two kits, all at mm's tag:
--
--```bash
--export DOCKER_HANDLE=k33g          # the Docker Hub account, also the image owner
--export DOCKER_PAT=dckr_pat_…       # an access token with read/write scope
--./docker-sbx/publish.sh            # TAG from release.env: v0.2.1 → k33g/mm-sandbox:0.2.1, k33g/mm-tui:0.2.1, k33g/mm-acp:0.2.1
--```
--
--With both variables set, the script logs in with them and logs out when it is done; with neither, it reuses your existing `docker login`. Its two halves run alone as `PUSH=1 ./docker-sbx/build.sh v0.2.1` (image) and `./docker-sbx/push-kits.sh v0.2.1` (kits, `SBX=/path/to/sbx` if the CLI is not on the PATH). Both call `sync-kits.sh` first, which rewrites the kits' `version`, default `tag` and image owner, so a published kit always names the image pushed with it — commit the two `spec.yaml` afterwards. `sbx kit push` talks to the registry directly and authenticates from the Docker credential store, no sandbox daemon involved. `IMAGE_OWNER=<handle>` publishes under another account.
--## MCP servers through the sbx gateway (GitHub as the example)
++- The `mini-me` kit's network policy allows **`host.docker.internal:12434`** (Docker Model Runner), **`:11434`** (Ollama) and **`:17434`** (llmman). `agent.dmr.yaml` already falls back to `http://host.docker.internal:12434/engines/v1`; the configurations shipped in `sbx/` use llmman (`fallback: http://host.docker.internal:17434/v1`).
++- For another port — llama-server's `8080`, for instance — add it to the kit's `network-policy` capability, or allow it for one sandbox:
--Inside a sandbox, `mm` does not talk to MCP servers itself and holds no token. `sbx` starts one MCP gateway per sandbox, on the host. When it creates the sandbox, it bakes two variables into the container: `MCP_GATEWAY_URL` (`http://mcp-gateway.docker.internal/mcp`) and `MCP_SENTINEL_TOKEN_NAME`, a placeholder that the sandbox proxy swaps for the real credential. When `mm` finds `MCP_GATEWAY_URL` and `mcp.enabled: true`, it adds a server called `sbx-gateway`, and its tools show up as `sbx-gateway_<tool>`. The kit needs no network rule for it, because the proxy routes that host itself.
++  ```bash
++  sbx policy allow network host.docker.internal:8080
++  ```
--1. Register GitHub's official server once, on the host, through `docker-sbx/mcp/github-mcp.sh`. The script starts `ghcr.io/github/github-mcp-server` in Docker with your token. sbx runs it as a child of sandboxd, which does not see your shell's variables. So store the token once in the macOS keychain under the service `github-mcp`. The script also accepts `GITHUB_PERSONAL_ACCESS_TOKEN`, `GITHUB_OAUTH_TOKEN` or a logged-in `gh`. sbx runs it on the host, so the token never enters the sandbox. By default it exposes a read-only set of 25 tools, including `get_me` and `get_teams`. Set `GITHUB_READ_ONLY=0` and a wider `GITHUB_TOOLSETS` in the script's environment for more.
++  `sbx policy log` shows what was blocked.
--   ```bash
++## Change a version
--   security add-generic-password -U -a "$USER" -s github-mcp -w   # prompts for the token
--   sbx mcp rm github 2>/dev/null               # an earlier "github" is the ARCHIVED catalog server
--   sbx mcp add github-mm --command "$PWD/docker-sbx/mcp/github-mcp.sh"
--   sbx mcp ls                                  # github-mm must be ready
--   ```
--
--   Do not use the name `github` alone. The Docker MCP catalog resolves it to "GitHub (Archived)", the old npm server, which has no `get_me` and returns other tools. The catalog's `github-official` does not help in sbx's local mode either. There, a catalog image is started as a bare `docker run` with no environment, so it would get no token.
--
--2. Create a **new** sandbox with that server in its fixed set. `--static-mcp` is an `sbx` flag: it goes **before** `--`, since everything after `--` goes to `mm`. It only applies at creation, so remove an older sandbox of the same name first:
--
--   ```bash
--   cd /path/to/project
--   sbx rm mm-mcp-github 2>/dev/null
--   sbx run --name mm-mcp-github --static-mcp github-mm k33g/mm-tui:<version> . -- agent.dmr.sbx.yaml
--   ```
--3. The configuration only needs MCP turned on. `demo/agent.dmr.sbx.yaml` has:
++- **mm**: the `default` of `mm_version` in `mini-me/mini-me.yaml` of the [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) repository — a release tag such as `v0.3.0`; the kit's own tag (`RELEASE` above) then names the new kit. The build downloads `https://rickub.com/bots-garden/mini-me/releases/download/<tag>/mm-<version>-linux-<arch>`; a tag with no such release fails the build.
++- **Go, gopls, rg, bat, eza**: the `default` of the matching argument in the mixin's YAML (`go_version`, `gopls_version`, `rg_version`, `bat_version`, `eza_version`); each one has a `pattern` that refuses a malformed version.
--   ```yaml
++## MCP servers through the sbx gateway
--   mcp:
--     enabled: true
--     permissions: ask
--     discoveryTimeout: 10s
--     servers: []        # the gateway is added by mm when MCP_GATEWAY_URL is set
--   ```
--   The banner then lists `sbx-gateway_get_me`, `sbx-gateway_list_issues`, and so on in `tools:`.
++Inside a sandbox, `mm` does not talk to MCP servers itself and holds no token. `sbx` runs one MCP gateway per sandbox, on the host, and bakes `MCP_GATEWAY_URL` into the container. When `mm` finds `MCP_GATEWAY_URL` and `mcp.enabled: true`, it adds a server called `sbx-gateway`, and its tools show up as `sbx-gateway_<tool>`:
--A kit image built before this change cannot use the gateway. It discovers nothing and warns `method "tools/list" is invalid during session initialization`. The gateway follows MCP's Streamable HTTP transport strictly: it needs `initialize` first, then the `Mcp-Session-Id` it returns on every request. Older `mm` skipped both. That was harmless against `api.githubcopilot.com` but fatal here. Rebuild and publish the kit after upgrading.
++```yaml
--
++mcp:
--If the banner lists no `sbx-gateway_*` tools, check the registration with `sbx mcp inspect github-mm`, then read sbx's MCP log, `mcp/mcp.log` under its state directory. `github-mcp: no token` there means the script found no token: check the keychain item with `security find-generic-password -s github-mcp`. The remote endpoint `https://api.githubcopilot.com/mcp/` is another route, but only with a GitHub OAuth App. GitHub offers no dynamic client registration, so in local mode `sbx mcp add` refuses it without `--client-id`, even with an `Authorization` header.
++  enabled: true
++  permissions: ask
++  discoveryTimeout: 10s
++  servers: []        # the gateway is added by mm when MCP_GATEWAY_URL is set
++```
--Name the repository in your requests, for example "list the open issues of k33g/my-repo". A small model given only "my organization" invents an owner and a repository, and every call comes back `Not Found`.
++Register the server on the host (`sbx mcp add <name> --command <script>`), then create a **new** sandbox with it in its fixed set — `--static-mcp <name>` is an `sbx` flag and goes before `--`. If no `sbx-gateway_*` tool appears in the banner, `sbx mcp inspect <name>` and sbx's `mcp/mcp.log` say why.
  ## Variants
--- **Another configuration for one editor session.** Add `"-e", "AGENT_CONFIG=agent.lsp.yaml"` before the sandbox name in `"args"`; `sbx exec -e` overrides the baked-in value for that run only.
++- **Skills.** `skillsDir` is relative to the directory `mm` runs in — the workspace — as on the host.
--- **Skills.** `skillsDir` is relative to the directory `mm` runs in, which is the workspace in both kits — the same rule as on the host.
--- **Docker inside the sandbox.** Build the template on the Docker-in-Docker shell instead: `SHELL_TEMPLATE=docker/sandbox-templates:shell-docker ./docker-sbx/build.sh`.
  - **Read the logs.** In the window mode they are on screen; over ACP they go to stderr, which Zed shows under `dev: open acp logs`.
++- **A shell in the sandbox.** `sbx exec -it mm-acp bash`.
  - **Remove a sandbox.** `sbx rm mm-acp`. The project directory is a bind mount and is not touched.
  ## See also
--- The kit format these two files follow: the Docker Sandboxes kit specification (`schemaVersion: "2"`), bundled with the `sbx` sources.
++- The kit format: [specification v3](https://github.com/docker/sandbox-kit-spec).
--- The same kits for the kit specification v3: [Run mini-me with the v3 sandbox kits](run-with-sandbox-kits-v3.md).
  - What `mm -acp` exposes to the editor: [ACP reference](../reference/acp.md).
  - The flags and environment variables `mm` reads: [command line reference](../reference/cli.md).

modified docs/en/how-to/run-with-llmman.md +2 -2 Viewed

@@ -19,8 +19,8 @@ This guide shows how to point `mm` at [llmman](https://github.com/llmmanorg/llmm
19	19	3. Run the demo configuration from its directory (its `skillsDir` is `../skills`):
20	20
21	21	```bash
22		- cd demo-llmman
23		- ../mm agent.llmman.yaml
	22	+ cd demos/llmman
	23	+ ../../mm agent.llmman.yaml
24	24	```
25	25
26	26	4. Check the banner. `provider: llmman` confirms the provider. `ctx: 262144 (/api/ps)` means the model was already loaded and `mm` read the window it is served with; `ctx: unknown` means it was not loaded yet — `mm` asks again before the next question and prints `ctx: … (/api/ps)` once it knows.

 . Run the demo configuration from its directory (its `skillsDir` is `../skills`):
     ```bash
--   cd demo-llmman
++   cd demos/llmman
--   ../mm agent.llmman.yaml
++   ../../mm agent.llmman.yaml
     ```
 . Check the banner. `provider: llmman` confirms the provider. `ctx: 262144 (/api/ps)` means the model was already loaded and `mm` read the window it is served with; `ctx: unknown` means it was not loaded yet — `mm` asks again before the next question and prints `ctx: … (/api/ps)` once it knows.

modified docs/en/how-to/run-with-ollama.md +2 -2 Viewed

@@ -15,8 +15,8 @@ This guide shows how to point `mm` at [Ollama](https://ollama.com) through its O
15	15	3. Run the demo configuration from its directory (its `skillsDir` is `../skills`):
16	16
17	17	```bash
18		- cd demo-ollama
19		- ../mm agent.ollama.yaml
	18	+ cd demos/ollama
	19	+ ../../mm agent.ollama.yaml
20	20	```
21	21
22	22	4. Check the banner. `provider: ollama` confirms the provider. `ctx: 32768 (/api/ps)` means the model was already loaded and `mm` read the window it is served with; `ctx: unknown` means it was not loaded yet — `mm` asks again before the next question.

 . Run the demo configuration from its directory (its `skillsDir` is `../skills`):
     ```bash
--   cd demo-ollama
++   cd demos/ollama
--   ../mm agent.ollama.yaml
++   ../../mm agent.ollama.yaml
     ```
 . Check the banner. `provider: ollama` confirms the provider. `ctx: 32768 (/api/ps)` means the model was already loaded and `mm` read the window it is served with; `ctx: unknown` means it was not loaded yet — `mm` asks again before the next question.

deleted docs/en/how-to/run-with-sandbox-kits-v3.md +0 -111 Viewed

deleted file mode 100644
@@ -1,111 +0,0 @@
1		-# How to run mini-me with the v3 sandbox kits
2		-
3		-This guide shows how to run `mm` in a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/) with the kits written for the [kit specification v3](https://github.com/docker/sandbox-kit-spec), under [`docker-sbx-v3/`](../../../docker-sbx-v3/README.md). They do the same job as the v2 kits of [Run mini-me in a Docker Sandbox](run-in-a-docker-sandbox.md) — the window mode with `mm-tui`, an editor with `mm-acp` — and the v2 kits keep working beside them. It assumes Docker Desktop with the `sbx` command, and a model server (Docker Model Runner or llama-server) running on your machine.
4		-
5		-> Status. The v3 kits build with the `docker/sandbox-kit:3` frontend and pass the specification's conformance check (`kit-tck validate`), but they have not yet been run with `sbx`, and they are not published yet. The kit specification itself is still marked experimental.
6		-
7		-\| Piece \| What it is \|
8		-\|---\|---\|
9		-\| `template/Dockerfile` \| The template image, `k33g/mm-sandbox:<version>` — the same image as v2. \|
10		-\| `kits/mm-tui/mm-tui.yaml` + `mm-tui.dockerfile` \| The window-mode kit: a descriptor (declarations) and a Dockerfile (content: `FROM` the template, `ENTRYPOINT ["mm-tui"]`). \|
11		-\| `kits/mm-acp/mm-acp.yaml` + `mm-acp.dockerfile` \| The editor kit, same shape, `ENTRYPOINT ["mm-acp-info"]`. \|
12		-\| `build.sh`, `sync-kits.sh` \| Build the template, and point the kits at it. \|
13		-\| `check-kits.sh` \| Builds the kits locally and checks them, with no `sbx` and no push. \|
14		-\| `push-kits.sh`, `publish.sh` \| Publish the kits (and the template) to Docker Hub with `docker buildx`. \|
15		-
16		-## Before you start: two differences with v2
17		-
18		-- The template image must be on a registry. A v3 kit is built on top of the template. When you run a kit from its directory, `sbx` builds it in its builder sandbox, and that sandbox's Docker engine pulls the template from the registry. An image that exists only in your local image store is not enough, and `--pull never` or `sbx template load` do not help. `k33g/mm-sandbox:0.2.1` is already on Docker Hub; for another version, push it first (step 1).
19		-- The workspace is `/home/agent/workspace`. The template's base image declares that working directory, and a v3 agent workload (`sbx@1`) is mounted there. Give `config` a path relative to the workspace (`agent.dmr.yaml`, `demo/agent.dmr.yaml`); an absolute path of your Mac (`/Users/…`) does not exist inside the sandbox.
20		-
21		-## Steps
22		-
23		-### 1. Make the template available
24		-
25		-For the version in `release.env` (`v0.2.1`), nothing to do: `k33g/mm-sandbox:0.2.1` is on Docker Hub. For a work-in-progress `mm`, build and push the template from the repository root:
26		-
27		-```bash
28		-PUSH=1 ./docker-sbx-v3/build.sh v0.2.2
29		-```
30		-
31		-The script builds `k33g/mm-sandbox:0.2.2` for linux/amd64 and linux/arm64, pushes it, then rewrites the kits' `image` and `tag` defaults so they name that image. `IMAGE_OWNER=<handle>` pushes under your own account instead.
32		-
33		-### 2. Check the kits (optional)
34		-
35		-```bash
36		-./docker-sbx-v3/check-kits.sh
37		-```
38		-
39		-Each kit is built with `docker buildx build -f <kit>.yaml`, which runs the kit frontend: it refuses an unknown key or an argument that does not match its pattern. The result goes to `tmp/kits-v3/<kit>/`. With [`kit-tck`](https://github.com/docker/sandbox-kit-spec) on the `PATH` (`go build ./cmd/kit-tck` in a clone of the specification), the script also runs the conformance check and prints `✓ conforms`.
40		-
41		-### 3. Window mode in the terminal (kit `mm-tui`)
42		-
43		-From the project you want `mm` to work on:
44		-
45		-```bash
46		-cd /path/to/your/project
47		-sbx run /path/to/mini-me/docker-sbx-v3/kits/mm-tui . -- agent.dmr.yaml
48		-```
49		-
50		-The first run builds the kit (a few seconds: one layer over the template), creates the sandbox, mounts the current directory and runs `mm -tui agent.dmr.yaml`. What follows `--` is `mm`'s own command line. Without it, `mm` reads the kit's `config` argument, then `./agent.yaml`, then its built-in defaults:
51		-
52		-```bash
53		-sbx run /path/to/mini-me/docker-sbx-v3/kits/mm-tui . --kit-arg config=agent.dmr.yaml
54		-```
55		-
56		-### 4. From an editor (kit `mm-acp`)
57		-
58		-1. Create the sandbox once, from the project the editor will open:
59		-
60		- ```bash
61		- cd /path/to/your/project
62		- sbx create --name mm-acp /path/to/mini-me/docker-sbx-v3/kits/mm-acp . \
63		- --kit-arg config=agent.dmr.yaml
64		- ```
65		-
66		-2. Register it in the editor. In Zed's `settings.json`:
67		-
68		- ```json
69		- {
70		- "agent_servers": {
71		- "mini-me (sandbox)": {
72		- "type": "custom",
73		- "command": "sbx",
74		- "args": ["exec", "-i", "mm-acp", "mm", "-acp"]
75		- }
76		- }
77		- }
78		- ```
79		-
80		-3. Open the agent panel and pick mini-me (sandbox). As with v2, the editor runs `sbx exec -i`, because an ACP client needs raw stdin and stdout and `sbx run` always allocates a terminal. `sbx run --name mm-acp` prints this wiring and opens a shell.
81		-
82		-### 5. Once the kits are published
83		-
84		-After `./docker-sbx-v3/publish.sh` (or `push-kits.sh`) has run for a version, the kits are ordinary images on Docker Hub, and no directory is needed:
85		-
86		-```bash
87		-sbx run k33g/sbx-kit-mm-tui:0.2.1 . -- agent.dmr.yaml
88		-sbx create --name mm-acp k33g/sbx-kit-mm-acp:0.2.1 . --kit-arg config=agent.dmr.yaml
89		-```
90		-
91		-The repositories are `sbx-kit-<kit>`, not the v2 `k33g/mm-tui` / `k33g/mm-acp`, so that publishing a v3 kit never replaces a v2 one.
92		-
93		-## Kit arguments
94		-
95		-\| `--kit-arg` \| Default \| When it applies \| Effect \|
96		-\|---\|---\|---\|---\|
97		-\| `config=<path>` \| empty \| at `sbx run` / `sbx create` \| `mm`'s `AGENT_CONFIG`: relative to the workspace, or absolute inside the sandbox. Empty: `./agent.yaml`, then the built-in defaults. \|
98		-\| `tag=<version>` \| mm's version (`0.2.1`) \| when the kit is built \| Which template tag the kit is built on; also the kit's version. No `v`. \|
99		-\| `image=<repository>` \| `k33g/mm-sandbox` \| when the kit is built \| Which template repository the kit is built on. \|
100		-
101		-`tag` and `image` are build-phase arguments: they are fixed in a published kit, which always names the image it was built on. To use another `mm` version, take the kit of that version.
102		-
103		-## The model server stays on the host
104		-
105		-Unchanged from v2: Docker Model Runner and llama-server run on your machine and are reached through `host.docker.internal`. `agent.dmr.yaml` already falls back to it; for llama-server see [the v2 guide](run-in-a-docker-sandbox.md#the-model-server-stays-on-the-host). Both kits allow ports 12434 and 8080 on the host; for another port, `sbx policy allow network host.docker.internal:<port>`.
106		-
107		-## See also
108		-
109		-- What changed from the v2 kits, field by field: [`docker-sbx-v3/README.md`](../../../docker-sbx-v3/README.md).
110		-- The v2 kits, the MCP gateway and the editor variants: [Run mini-me in a Docker Sandbox](run-in-a-docker-sandbox.md).
111		-- The kit format: [specification v3](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md).

--# How to run mini-me with the v3 sandbox kits
--
--This guide shows how to run `mm` in a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/) with the kits written for the [kit specification v3](https://github.com/docker/sandbox-kit-spec), under [`docker-sbx-v3/`](../../../docker-sbx-v3/README.md). They do the same job as the v2 kits of [Run mini-me in a Docker Sandbox](run-in-a-docker-sandbox.md) — the window mode with `mm-tui`, an editor with `mm-acp` — and the v2 kits keep working beside them. It assumes Docker Desktop with the `sbx` command, and a model server (Docker Model Runner or llama-server) running on your machine.
--
--> **Status.** The v3 kits build with the `docker/sandbox-kit:3` frontend and pass the specification's conformance check (`kit-tck validate`), but they have not yet been run with `sbx`, and they are not published yet. The kit specification itself is still marked experimental.
--
--| Piece | What it is |
--|---|---|
--| `template/Dockerfile` | The **template** image, `k33g/mm-sandbox:<version>` — the same image as v2. |
--| `kits/mm-tui/mm-tui.yaml` + `mm-tui.dockerfile` | The window-mode kit: a descriptor (declarations) and a Dockerfile (content: `FROM` the template, `ENTRYPOINT ["mm-tui"]`). |
--| `kits/mm-acp/mm-acp.yaml` + `mm-acp.dockerfile` | The editor kit, same shape, `ENTRYPOINT ["mm-acp-info"]`. |
--| `build.sh`, `sync-kits.sh` | Build the template, and point the kits at it. |
--| `check-kits.sh` | Builds the kits locally and checks them, with no `sbx` and no push. |
--| `push-kits.sh`, `publish.sh` | Publish the kits (and the template) to Docker Hub with `docker buildx`. |
--
--## Before you start: two differences with v2
--
--- **The template image must be on a registry.** A v3 kit is *built* on top of the template. When you run a kit from its directory, `sbx` builds it in its builder sandbox, and that sandbox's Docker engine pulls the template from the registry. An image that exists only in your local image store is not enough, and `--pull never` or `sbx template load` do not help. `k33g/mm-sandbox:0.2.1` is already on Docker Hub; for another version, push it first (step 1).
--- **The workspace is `/home/agent/workspace`.** The template's base image declares that working directory, and a v3 agent workload (`sbx@1`) is mounted there. Give `config` a path relative to the workspace (`agent.dmr.yaml`, `demo/agent.dmr.yaml`); an absolute path of your Mac (`/Users/…`) does not exist inside the sandbox.
--
--## Steps
--
--### 1. Make the template available
--
--For the version in `release.env` (`v0.2.1`), nothing to do: `k33g/mm-sandbox:0.2.1` is on Docker Hub. For a work-in-progress `mm`, build and push the template from the repository root:
--
--```bash
--PUSH=1 ./docker-sbx-v3/build.sh v0.2.2
--```
--
--The script builds `k33g/mm-sandbox:0.2.2` for linux/amd64 and linux/arm64, pushes it, then rewrites the kits' `image` and `tag` defaults so they name that image. `IMAGE_OWNER=<handle>` pushes under your own account instead.
--
--### 2. Check the kits (optional)
--
--```bash
--./docker-sbx-v3/check-kits.sh
--```
--
--Each kit is built with `docker buildx build -f <kit>.yaml`, which runs the kit frontend: it refuses an unknown key or an argument that does not match its pattern. The result goes to `tmp/kits-v3/<kit>/`. With [`kit-tck`](https://github.com/docker/sandbox-kit-spec) on the `PATH` (`go build ./cmd/kit-tck` in a clone of the specification), the script also runs the conformance check and prints `✓ conforms`.
--
--### 3. Window mode in the terminal (kit `mm-tui`)
--
--From the project you want `mm` to work on:
--
--```bash
--cd /path/to/your/project
--sbx run /path/to/mini-me/docker-sbx-v3/kits/mm-tui . -- agent.dmr.yaml
--```
--
--The first run builds the kit (a few seconds: one layer over the template), creates the sandbox, mounts the current directory and runs `mm -tui agent.dmr.yaml`. What follows `--` is `mm`'s own command line. Without it, `mm` reads the kit's `config` argument, then `./agent.yaml`, then its built-in defaults:
--
--```bash
--sbx run /path/to/mini-me/docker-sbx-v3/kits/mm-tui . --kit-arg config=agent.dmr.yaml
--```
--
--### 4. From an editor (kit `mm-acp`)
--
--1. Create the sandbox once, from the project the editor will open:
--
--   ```bash
--   cd /path/to/your/project
--   sbx create --name mm-acp /path/to/mini-me/docker-sbx-v3/kits/mm-acp . \
--       --kit-arg config=agent.dmr.yaml
--   ```
--
--2. Register it in the editor. In Zed's `settings.json`:
--
--   ```json
--   {
--     "agent_servers": {
--       "mini-me (sandbox)": {
--         "type": "custom",
--         "command": "sbx",
--         "args": ["exec", "-i", "mm-acp", "mm", "-acp"]
--       }
--     }
--   }
--   ```
--
--3. Open the agent panel and pick **mini-me (sandbox)**. As with v2, the editor runs `sbx exec -i`, because an ACP client needs raw stdin and stdout and `sbx run` always allocates a terminal. `sbx run --name mm-acp` prints this wiring and opens a shell.
--
--### 5. Once the kits are published
--
--After `./docker-sbx-v3/publish.sh` (or `push-kits.sh`) has run for a version, the kits are ordinary images on Docker Hub, and no directory is needed:
--
--```bash
--sbx run k33g/sbx-kit-mm-tui:0.2.1 . -- agent.dmr.yaml
--sbx create --name mm-acp k33g/sbx-kit-mm-acp:0.2.1 . --kit-arg config=agent.dmr.yaml
--```
--
--The repositories are `sbx-kit-<kit>`, not the v2 `k33g/mm-tui` / `k33g/mm-acp`, so that publishing a v3 kit never replaces a v2 one.
--
--## Kit arguments
--
--| `--kit-arg` | Default | When it applies | Effect |
--|---|---|---|---|
--| `config=<path>` | empty | at `sbx run` / `sbx create` | `mm`'s `AGENT_CONFIG`: relative to the workspace, or absolute inside the sandbox. Empty: `./agent.yaml`, then the built-in defaults. |
--| `tag=<version>` | mm's version (`0.2.1`) | when the kit is built | Which template tag the kit is built on; also the kit's version. No `v`. |
--| `image=<repository>` | `k33g/mm-sandbox` | when the kit is built | Which template repository the kit is built on. |
--
--`tag` and `image` are build-phase arguments: they are fixed in a published kit, which always names the image it was built on. To use another `mm` version, take the kit of that version.
--
--## The model server stays on the host
--
--Unchanged from v2: Docker Model Runner and llama-server run on your machine and are reached through `host.docker.internal`. `agent.dmr.yaml` already falls back to it; for llama-server see [the v2 guide](run-in-a-docker-sandbox.md#the-model-server-stays-on-the-host). Both kits allow ports 12434 and 8080 on the host; for another port, `sbx policy allow network host.docker.internal:<port>`.
--
--## See also
--
--- What changed from the v2 kits, field by field: [`docker-sbx-v3/README.md`](../../../docker-sbx-v3/README.md).
--- The v2 kits, the MCP gateway and the editor variants: [Run mini-me in a Docker Sandbox](run-in-a-docker-sandbox.md).
--- The kit format: [specification v3](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md).

modified docs/fr/README.md +3 -4 Viewed

@@ -11,8 +11,8 @@ Cette documentation est organisée selon les quatre quadrants [Diátaxis](https:
11	11	## Guides pratiques — accomplir une tâche
12	12
13	13	- [Faire tourner mini-me sur llama.cpp plutôt que Docker Model Runner](how-to/run-with-llama-cpp.md)
14		-- [Faire tourner mini-me sur llmman](how-to/run-with-llmman.md) — `provider: llmman`, la config de démo dans `demo-llmman/`
15		-- [Faire tourner mini-me sur Ollama](how-to/run-with-ollama.md) — `provider: ollama`, la config de démo dans `demo-ollama/`
	14	+- [Faire tourner mini-me sur llmman](how-to/run-with-llmman.md) — `provider: llmman`, la config de démo dans `demos/llmman/`
	15	+- [Faire tourner mini-me sur Ollama](how-to/run-with-ollama.md) — `provider: ollama`, la config de démo dans `demos/ollama/`
16	16	- [Interroger un autre agent mm depuis votre session](how-to/ask-another-agent.md) — `mmConfigs`, `/ask-<nom>`, `/ask-with-context-<nom>`
17	17	- [Voir le JSON envoyé au modèle et sa réponse](how-to/inspect-model-traffic.md) — `trace`, `AGENT_TRACE`, lire les fichiers avec jq
18	18	- [Donner à l'agent les consignes de votre projet](how-to/give-project-instructions.md) — `AGENTS.md`, lu à chaque conversation, réglages `agentsMd`
@@ -22,8 +22,7 @@ Cette documentation est organisée selon les quatre quadrants [Diátaxis](https:
22	22	- [Utiliser mini-me depuis un éditeur (ACP)](how-to/use-from-an-editor.md)
23	23	- [Couper le raisonnement d'un modèle](how-to/turn-reasoning-off.md) — `chat_template_kwargs` ou `reasoning_effort` dans `sampling`, selon le serveur
24	24	- [Confirmer les appels d'outils avant leur exécution](how-to/confirm-tool-calls.md) — `yolo: false`, les quatre réponses, `AGENT_YOLO`, qui décide avec `mmConfigs`
25		-- [Faire tourner mini-me dans un Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — le template et les deux kits sous `docker-sbx/`, mode fenêtre et éditeur
26		-- [Faire tourner mini-me avec les kits sandbox v3](how-to/run-with-sandbox-kits-v3.md) — les deux mêmes kits pour la spécification de kit v3, sous `docker-sbx-v3/`
	25	+- [Faire tourner mini-me dans un Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — le kit `mini-me` de [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), les mixins `go-toolchain` et `cli-tools` sous `sbx/`, mode fenêtre et éditeur
27	26	- [Ajouter un skill](how-to/add-a-skill.md)
28	27	- [Mesurer si le modèle choisit le bon skill](how-to/measure-skill-routing.md) — l'eval de routage : le lancer, lire son tableau, s'en servir en avant/après
29	28	- [Garder une longue session dans la fenêtre de contexte](how-to/manage-the-context-window.md)

  ## Guides pratiques — accomplir une tâche
  - [Faire tourner mini-me sur llama.cpp plutôt que Docker Model Runner](how-to/run-with-llama-cpp.md)
--- [Faire tourner mini-me sur llmman](how-to/run-with-llmman.md) — `provider: llmman`, la config de démo dans `demo-llmman/`
++- [Faire tourner mini-me sur llmman](how-to/run-with-llmman.md) — `provider: llmman`, la config de démo dans `demos/llmman/`
--- [Faire tourner mini-me sur Ollama](how-to/run-with-ollama.md) — `provider: ollama`, la config de démo dans `demo-ollama/`
++- [Faire tourner mini-me sur Ollama](how-to/run-with-ollama.md) — `provider: ollama`, la config de démo dans `demos/ollama/`
  - [Interroger un autre agent mm depuis votre session](how-to/ask-another-agent.md) — `mmConfigs`, `/ask-<nom>`, `/ask-with-context-<nom>`
  - [Voir le JSON envoyé au modèle et sa réponse](how-to/inspect-model-traffic.md) — `trace`, `AGENT_TRACE`, lire les fichiers avec jq
  - [Donner à l'agent les consignes de votre projet](how-to/give-project-instructions.md) — `AGENTS.md`, lu à chaque conversation, réglages `agentsMd`
  - [Utiliser mini-me depuis un éditeur (ACP)](how-to/use-from-an-editor.md)
  - [Couper le raisonnement d'un modèle](how-to/turn-reasoning-off.md) — `chat_template_kwargs` ou `reasoning_effort` dans `sampling`, selon le serveur
  - [Confirmer les appels d'outils avant leur exécution](how-to/confirm-tool-calls.md) — `yolo: false`, les quatre réponses, `AGENT_YOLO`, qui décide avec `mmConfigs`
--- [Faire tourner mini-me dans un Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — le template et les deux kits sous `docker-sbx/`, mode fenêtre et éditeur
++- [Faire tourner mini-me dans un Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — le kit `mini-me` de [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), les mixins `go-toolchain` et `cli-tools` sous `sbx/`, mode fenêtre et éditeur
--- [Faire tourner mini-me avec les kits sandbox v3](how-to/run-with-sandbox-kits-v3.md) — les deux mêmes kits pour la spécification de kit v3, sous `docker-sbx-v3/`
  - [Ajouter un skill](how-to/add-a-skill.md)
  - [Mesurer si le modèle choisit le bon skill](how-to/measure-skill-routing.md) — l'eval de routage : le lancer, lire son tableau, s'en servir en avant/après
  - [Garder une longue session dans la fenêtre de contexte](how-to/manage-the-context-window.md)

modified docs/fr/how-to/ask-another-agent-from-a-skill.md +2 -2 Viewed

@@ -69,8 +69,8 @@ Ce guide montre comment faire poser une question à un autre agent mm par une sk
69	69
70	70	## Variantes
71	71
72		-- Depuis un terminal ou un script, hors de mm. Nommez la configuration : `mm -config demo-llmman/agent.llmman.yaml --ask lucy -p "…"`, ou mettez la question sur stdin. Vérifiez le code de sortie : 0 réponse obtenue, 1 échec (la raison est sur stderr), 130 interrompu.
73		-- Un agent qui doit seulement répondre. Donnez-lui une configuration avec `bashTool: false`, `editTools: false`, `planTool: false` et sans skills — `demo-llmman/agent.lucy-reviewer.yaml` en est une. Un petit modèle doté de tous ses outils a tendance à s'égarer (lire des fichiers, charger des skills) quand on lui demande seulement son avis.
	72	+- Depuis un terminal ou un script, hors de mm. Nommez la configuration : `mm -config demos/llmman/agent.llmman.yaml --ask lucy -p "…"`, ou mettez la question sur stdin. Vérifiez le code de sortie : 0 réponse obtenue, 1 échec (la raison est sur stderr), 130 interrompu.
	73	+- Un agent qui doit seulement répondre. Donnez-lui une configuration avec `bashTool: false`, `editTools: false`, `planTool: false` et sans skills — `demos/llmman/agent.lucy-reviewer.yaml` en est une. Un petit modèle doté de tous ses outils a tendance à s'égarer (lire des fichiers, charger des skills) quand on lui demande seulement son avis.
74	74	- Récupérer la réponse dans une variable. `answer=$("$MM_BIN" --ask jan -p "…")` — stdout ne contient que la réponse.
75	75
76	76	## Voir aussi

  ## Variantes
--- **Depuis un terminal ou un script, hors de mm.** Nommez la configuration : `mm -config demo-llmman/agent.llmman.yaml --ask lucy -p "…"`, ou mettez la question sur stdin. Vérifiez le code de sortie : 0 réponse obtenue, 1 échec (la raison est sur stderr), 130 interrompu.
++- **Depuis un terminal ou un script, hors de mm.** Nommez la configuration : `mm -config demos/llmman/agent.llmman.yaml --ask lucy -p "…"`, ou mettez la question sur stdin. Vérifiez le code de sortie : 0 réponse obtenue, 1 échec (la raison est sur stderr), 130 interrompu.
--- **Un agent qui doit seulement répondre.** Donnez-lui une configuration avec `bashTool: false`, `editTools: false`, `planTool: false` et sans skills — `demo-llmman/agent.lucy-reviewer.yaml` en est une. Un petit modèle doté de tous ses outils a tendance à s'égarer (lire des fichiers, charger des skills) quand on lui demande seulement son avis.
++- **Un agent qui doit seulement répondre.** Donnez-lui une configuration avec `bashTool: false`, `editTools: false`, `planTool: false` et sans skills — `demos/llmman/agent.lucy-reviewer.yaml` en est une. Un petit modèle doté de tous ses outils a tendance à s'égarer (lire des fichiers, charger des skills) quand on lui demande seulement son avis.
  - **Récupérer la réponse dans une variable.** `answer=$("$MM_BIN" --ask jan -p "…")` — stdout ne contient que la réponse.
  ## Voir aussi

modified docs/fr/how-to/ask-another-agent.md +6 -6 Viewed

@@ -4,10 +4,10 @@ Ce guide montre comment poser une question à un autre agent mm — un autre mod
4	4
5	5	## Étapes
6	6
7		-1. Écrivez (ou réutilisez) un fichier de configuration par agent à interroger. Chacun est une configuration mm ordinaire ; `demo-llmman/` en fournit deux, pour llmman :
	7	+1. Écrivez (ou réutilisez) un fichier de configuration par agent à interroger. Chacun est une configuration mm ordinaire ; `demos/llmman/` en fournit deux, pour llmman :
8	8
9		- - `demo-llmman/agent.jan-nano.yaml` — `hf.co/Menlo/Jan-nano-gguf:Q4_K_M`, nommé Jan ;
10		- - `demo-llmman/agent.lucy.yaml` — `hf.co/Menlo/Lucy-gguf:Q4_K_M`, nommée Lucy.
	9	+ - `demos/llmman/agent.jan-nano.yaml` — `hf.co/Menlo/Jan-nano-gguf:Q4_K_M`, nommé Jan ;
	10	+ - `demos/llmman/agent.lucy.yaml` — `hf.co/Menlo/Lucy-gguf:Q4_K_M`, nommée Lucy.
11	11
12	12	2. Déclarez-les dans VOTRE configuration, sous `mmConfigs`. Les chemins sont relatifs au dossier du fichier où vous les écrivez :
13	13
@@ -17,13 +17,13 @@ Ce guide montre comment poser une question à un autre agent mm — un autre mod
17	17	lucy: agent.lucy.yaml
18	18	```
19	19
20		- `demo-llmman/agent.llmman.yaml` le fait déjà.
	20	+ `demos/llmman/agent.llmman.yaml` le fait déjà.
21	21
22	22	3. Lancez `mm` avec cette configuration :
23	23
24	24	```bash
25		- cd demo-llmman
26		- ../mm agent.llmman.yaml
	25	+ cd demos/llmman
	26	+ ../../mm agent.llmman.yaml
27	27	```
28	28
29	29	Un agent dont le fichier manque apparaît sur une ligne `[warning: mmConfigs: …]` ; les autres fonctionnent.

  ## Étapes
--1. Écrivez (ou réutilisez) un fichier de configuration par agent à interroger. Chacun est une configuration mm ordinaire ; `demo-llmman/` en fournit deux, pour llmman :
++1. Écrivez (ou réutilisez) un fichier de configuration par agent à interroger. Chacun est une configuration mm ordinaire ; `demos/llmman/` en fournit deux, pour llmman :
--   - `demo-llmman/agent.jan-nano.yaml` — `hf.co/Menlo/Jan-nano-gguf:Q4_K_M`, nommé Jan ;
++   - `demos/llmman/agent.jan-nano.yaml` — `hf.co/Menlo/Jan-nano-gguf:Q4_K_M`, nommé Jan ;
--   - `demo-llmman/agent.lucy.yaml` — `hf.co/Menlo/Lucy-gguf:Q4_K_M`, nommée Lucy.
++   - `demos/llmman/agent.lucy.yaml` — `hf.co/Menlo/Lucy-gguf:Q4_K_M`, nommée Lucy.
 . Déclarez-les dans VOTRE configuration, sous `mmConfigs`. Les chemins sont relatifs au dossier du fichier où vous les écrivez :
       lucy: agent.lucy.yaml
     ```
--   `demo-llmman/agent.llmman.yaml` le fait déjà.
++   `demos/llmman/agent.llmman.yaml` le fait déjà.
 . Lancez `mm` avec cette configuration :
     ```bash
--   cd demo-llmman
++   cd demos/llmman
--   ../mm agent.llmman.yaml
++   ../../mm agent.llmman.yaml
     ```
     Un agent dont le fichier manque apparaît sur une ligne `[warning: mmConfigs: …]` ; les autres fonctionnent.

modified docs/fr/how-to/get-json-answers.md +2 -2 Viewed

@@ -1,6 +1,6 @@
1	1	# Comment obtenir des réponses en JSON (`structuredOutput`)
2	2
3		-Ce guide montre comment faire répondre un agent uniquement en JSON, selon une forme que vous déclarez, pour qu'un script, `jq` ou un autre agent puisse exploiter la réponse. Il suppose que vous lancez déjà `mm` avec un fichier de configuration, sur un serveur qui accepte `response_format: json_schema` (llama.cpp, donc `dmr`, `llamacpp`, `llmman` ; Ollama ; l'API OpenAI). Le dossier `demo-structured-output/` contient les fichiers utilisés ci-dessous.
	3	+Ce guide montre comment faire répondre un agent uniquement en JSON, selon une forme que vous déclarez, pour qu'un script, `jq` ou un autre agent puisse exploiter la réponse. Il suppose que vous lancez déjà `mm` avec un fichier de configuration, sur un serveur qui accepte `response_format: json_schema` (llama.cpp, donc `dmr`, `llamacpp`, `llmman` ; Ollama ; l'API OpenAI). Le dossier `demos/structured-output/` contient les fichiers utilisés ci-dessous.
4	4
5	5	## Étapes
6	6
@@ -53,7 +53,7 @@ Ce guide montre comment faire répondre un agent uniquement en JSON, selon une f
53	53
54	54	## Variantes
55	55
56		-- Faire exploiter le JSON par un autre agent. Déclarez l'agent JSON dans les `mmConfigs` d'un coordinateur — un agent qui a des outils — ; il l'appelle avec `ask_agent` et reçoit le JSON comme résultat de l'outil. Voir [Comment laisser votre agent appeler d'autres agents](let-the-agent-call-other-agents.md) et `demo-structured-output/agent.coordinator.yaml`. Le coordinateur, lui, ne peut pas avoir de `structuredOutput` : il a des outils.
	56	+- Faire exploiter le JSON par un autre agent. Déclarez l'agent JSON dans les `mmConfigs` d'un coordinateur — un agent qui a des outils — ; il l'appelle avec `ask_agent` et reçoit le JSON comme résultat de l'outil. Voir [Comment laisser votre agent appeler d'autres agents](let-the-agent-call-other-agents.md) et `demos/structured-output/agent.coordinator.yaml`. Le coordinateur, lui, ne peut pas avoir de `structuredOutput` : il a des outils.
57	57	- Interroger l'agent JSON par la config du coordinateur, depuis un shell : `mm agent.coordinator.yaml --ask countries -p "capitale du Vietnam" \| jq .` (voir [Comment interroger un autre agent depuis un skill ou un script](ask-another-agent-from-a-skill.md)).
58	58	- Dans le terminal ou la fenêtre, l'agent répond à chaque question en JSON, affiché comme n'importe quelle réponse.
59	59	- Pour l'API hébergée d'OpenAI, faites de la racine une struct (`var Answer = Triage{}`) : son mode strict exige un objet au sommet. llama.cpp et Ollama acceptent un tableau.

  # Comment obtenir des réponses en JSON (`structuredOutput`)
--Ce guide montre comment faire répondre un agent uniquement en JSON, selon une forme que vous déclarez, pour qu'un script, `jq` ou un autre agent puisse exploiter la réponse. Il suppose que vous lancez déjà `mm` avec un fichier de configuration, sur un serveur qui accepte `response_format: json_schema` (llama.cpp, donc `dmr`, `llamacpp`, `llmman` ; Ollama ; l'API OpenAI). Le dossier `demo-structured-output/` contient les fichiers utilisés ci-dessous.
++Ce guide montre comment faire répondre un agent uniquement en JSON, selon une forme que vous déclarez, pour qu'un script, `jq` ou un autre agent puisse exploiter la réponse. Il suppose que vous lancez déjà `mm` avec un fichier de configuration, sur un serveur qui accepte `response_format: json_schema` (llama.cpp, donc `dmr`, `llamacpp`, `llmman` ; Ollama ; l'API OpenAI). Le dossier `demos/structured-output/` contient les fichiers utilisés ci-dessous.
  ## Étapes
  ## Variantes
--- **Faire exploiter le JSON par un autre agent.** Déclarez l'agent JSON dans les `mmConfigs` d'un coordinateur — un agent qui a des outils — ; il l'appelle avec `ask_agent` et reçoit le JSON comme résultat de l'outil. Voir [Comment laisser votre agent appeler d'autres agents](let-the-agent-call-other-agents.md) et `demo-structured-output/agent.coordinator.yaml`. Le coordinateur, lui, ne peut pas avoir de `structuredOutput` : il a des outils.
++- **Faire exploiter le JSON par un autre agent.** Déclarez l'agent JSON dans les `mmConfigs` d'un coordinateur — un agent qui a des outils — ; il l'appelle avec `ask_agent` et reçoit le JSON comme résultat de l'outil. Voir [Comment laisser votre agent appeler d'autres agents](let-the-agent-call-other-agents.md) et `demos/structured-output/agent.coordinator.yaml`. Le coordinateur, lui, ne peut pas avoir de `structuredOutput` : il a des outils.
  - **Interroger l'agent JSON par la config du coordinateur**, depuis un shell : `mm agent.coordinator.yaml --ask countries -p "capitale du Vietnam" | jq .` (voir [Comment interroger un autre agent depuis un skill ou un script](ask-another-agent-from-a-skill.md)).
  - **Dans le terminal ou la fenêtre**, l'agent répond à chaque question en JSON, affiché comme n'importe quelle réponse.
  - **Pour l'API hébergée d'OpenAI**, faites de la racine une struct (`var Answer = Triage{}`) : son mode strict exige un objet au sommet. llama.cpp et Ollama acceptent un tableau.

modified docs/fr/how-to/let-the-agent-call-other-agents.md +1 -1 Viewed

@@ -64,7 +64,7 @@ Ce guide montre comment donner une équipe à votre agent : d'autres agents mm a
64	64	- Interroger un agent vous-même. `/ask-<nom>` et `/ask-with-context-<nom>` marchent toujours, et gardent l'échange dans l'historique. Voir [Interroger un autre agent mm](ask-another-agent.md).
65	65	- Travail long. Chaque événement diffusé par l'agent maintient en vie le watchdog de votre agent, mais pas un long silence — un gros modèle qui se charge, un long premier prompt : relevez votre `watchdogTimeout` pour le couvrir (10m pour un modèle de 48 Go sur un portable).
66	66	- Depuis un script. `mm --ask <nom>` reste la voie pour une commande shell. Voir [Interroger un autre agent depuis une skill ou un script](ask-another-agent-from-a-skill.md).
67		-- Exemples complets. `demo-llmman/agent.llmman.yaml` (Bob avec Jan, Lucy et un relecteur) et `mini-mes/riker/agent.riker.yaml` (un coordinateur, un spécificateur et un codeur).
	67	+- Exemples complets. `demos/llmman/agent.llmman.yaml` (Bob avec Jan, Lucy et un relecteur) et `demos/mini-mes/riker/agent.riker.yaml` (un coordinateur, un spécificateur et un codeur).
68	68
69	69	## Voir aussi
70	70

  - **Interroger un agent vous-même.** `/ask-<nom>` et `/ask-with-context-<nom>` marchent toujours, et gardent l'échange dans l'historique. Voir [Interroger un autre agent mm](ask-another-agent.md).
  - **Travail long.** Chaque événement diffusé par l'agent maintient en vie le watchdog de votre agent, mais pas un long silence — un gros modèle qui se charge, un long premier prompt : relevez votre `watchdogTimeout` pour le couvrir (10m pour un modèle de 48 Go sur un portable).
  - **Depuis un script.** `mm --ask <nom>` reste la voie pour une commande shell. Voir [Interroger un autre agent depuis une skill ou un script](ask-another-agent-from-a-skill.md).
--- **Exemples complets.** `demo-llmman/agent.llmman.yaml` (Bob avec Jan, Lucy et un relecteur) et `mini-mes/riker/agent.riker.yaml` (un coordinateur, un spécificateur et un codeur).
++- **Exemples complets.** `demos/llmman/agent.llmman.yaml` (Bob avec Jan, Lucy et un relecteur) et `demos/mini-mes/riker/agent.riker.yaml` (un coordinateur, un spécificateur et un codeur).
  ## Voir aussi

modified docs/fr/how-to/run-in-a-docker-sandbox.md +74 -120 Viewed

@@ -1,90 +1,80 @@
1		-# Faire tourner mini-me dans un Docker Sandbox
	1	+# Comment faire tourner mini-me dans un Docker Sandbox
2	2
3		-Ce guide montre comment exécuter `mm` dans un [Docker Sandbox](https://docs.docker.com/ai/sandboxes/), pour que chaque commande lancée par le modèle et chaque fichier qu'il modifie le soient dans un conteneur, sur votre projet monté. Il couvre les deux usages : le mode fenêtre dans votre terminal, et depuis un éditeur via l'Agent Client Protocol. Il suppose Docker Desktop avec la commande `sbx`, et un serveur de modèles (Docker Model Runner ou llama-server) qui tourne sur votre machine.
	3	+Ce guide montre comment lancer `mm` dans un [Docker Sandbox](https://docs.docker.com/ai/sandboxes/), pour que chaque commande lancée par le modèle et chaque fichier qu'il modifie le soient dans un conteneur, sur une copie montée de votre projet. Il couvre le mode fenêtre dans votre terminal et un éditeur via l'Agent Client Protocol. Il suppose Docker Desktop avec la commande `sbx`, et un serveur de modèles qui tourne sur votre machine.
4	4
5		-> Ce sont les kits v2 (`spec.yaml`). Les deux mêmes kits existent aussi pour la spécification de kit v3, sous `docker-sbx-v3/` : voir [Faire tourner mini-me avec les kits sandbox v3](run-with-sandbox-kits-v3.md).
	5	+Tout se trouve sous [`sbx/`](../../../sbx/README.md) dans le dépôt. Les kits suivent la [spécification des kits v3](https://github.com/docker/sandbox-kit-spec) (`schemaVersion: "3"`) : un workload qui lance `mm`, et des mixins qu'on lui ajoute avec `--kit`.
6	6
7		-Tout est sous [`docker-sbx/`](../../../docker-sbx/README.md) dans le dépôt :
	7	+\| Élément \| Où \| Ce que c'est \|
	8	+\|---\|---\|---\|
	9	+\| `mini-me` \| [bots-garden/mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), dossier `mini-me/` \| Le workload : le template `shell` de Docker (Ubuntu, utilisateur `agent`) avec le binaire `mm` d'une release (`mm_version`, `v0.3.0` par défaut), téléchargé depuis la page de release de mini-me. Point d'entrée `mm`, arguments par défaut `-tui`. Versionné par ses propres tags (`v0.0.1`). \|
	10	+\| `go-toolchain` \| `sbx/kits/go-toolchain/` \| Un mixin : Go (`go_version`, `1.27.2` par défaut), `gofmt` et `gopls` (`gopls_version`, `latest` par défaut). Autorise à l'exécution les hôtes des modules : `proxy.golang.org`, `sum.golang.org`, `github.com`, `golang.org`. \|
	11	+\| `cli-tools` \| `sbx/kits/cli-tools/` \| Un mixin : `rg`, `bat` et `eza` en binaires statiques. Pas de réseau à l'exécution. \|
	12	+\| `agent.yaml`, `agent.lucy.yaml` \| `sbx/` \| Deux configurations `mm` pour llmman (Jan-nano, Lucy). \|
	13	+\| `AGENTS.md` \| `sbx/` \| Les consignes de l'agent qui travaille dans le sandbox (les outils installés, comment lancer Go) : `mm` les ajoute à son prompt système quand il tourne dans ce dossier — voir [Comment donner à l'agent les consignes de votre projet](give-project-instructions.md). \|
8	14
9		-\| Élément \| Ce que c'est \|
10		-\|---\|---\|
11		-\| `template/Dockerfile` \| Le template : l'image `shell` de Docker Sandboxes avec `mm` compilé depuis ce dépôt, plus les deux points d'entrée ci-dessous. \|
12		-\| `kits/mm-tui/spec.yaml` \| Un kit sandbox : `sbx run` dessus ouvre le mode fenêtre de `mm` sur l'espace de travail. \|
13		-\| `kits/mm-acp/spec.yaml` \| Un kit sandbox pour un éditeur : créé une fois avec `sbx create`, l'éditeur y lance ensuite `mm -acp`. \|
14		-\| `build.sh` \| Construit l'image du template, `k33g/mm-sandbox:<version>` ; `PUSH=1` la construit pour linux/amd64 et linux/arm64 et la pousse. \|
15		-\| `sync-kits.sh`, `push-kits.sh` \| Alignent les kits sur une image, et les publient sur Docker Hub comme artefacts OCI de kit. \|
	15	+## Étapes
16	16
17		-## Utiliser les kits publiés
	17	+### 1. Autoriser la source du kit
18	18
19		-Chaque release publie l'image et les deux kits sur Docker Hub à la version de mm — `k33g/mm-sandbox:0.2.1`, `k33g/mm-tui:0.2.1`, `k33g/mm-acp:0.2.1` — le chemin le plus court ne demande donc aucune construction. Docker Hub est une source de kits autorisée par défaut (`sbx settings get kit.allowedSources` montre `docker.io/`), et une référence avec un `/` mais sans hôte de registre est lue comme `docker.io/…` :
	19	+Le kit `mini-me` est désigné par son URL git, un tag et son dossier. Son hôte doit être une source de kits autorisée, une fois pour toutes :
20	20
21	21	```bash
22		-cd /chemin/de/votre/projet
23		-sbx run k33g/mm-tui:0.2.1 . -- agent.dmr.yaml
	22	+sbx settings set kit.allowedSources '["docker.io/","git.rickub.com/bots-garden/"]'
24	23	```
25	24
26		-pour le mode fenêtre, et pour un éditeur :
27		-
28		-```bash
29		-sbx create --name mm-acp k33g/mm-acp:0.2.1 . --kit-arg config=agent.dmr.yaml
30		-```
	25	+### 2. Mode fenêtre dans le terminal
31	26
32		-puis la déclaration dans l'éditeur de l'étape 3 ci-dessous. Pas de `--pull never` : le kit nomme `k33g/mm-sandbox:0.2.1` et sbx la télécharge. `sbx kit inspect k33g/mm-tui:0.2.1` montre ce qu'un kit déclare avant de le lancer. Les étapes qui suivent construisent la même chose en local, pour un mm en cours de travail.
33		-
34		-## Étapes
35		-
36		-### 1. Construire le template
37		-
38		-Depuis la racine du dépôt :
	27	+Depuis le dossier sur lequel `mm` doit travailler — `sbx/` lui-même, pour utiliser ses configurations et son `AGENTS.md` :
39	28
40	29	```bash
41		-./docker-sbx/build.sh
	30	+cd sbx
	31	+RELEASE=v0.0.1
	32	+REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
	33	+sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me"
42	34	```
43	35
44		-Cela lit le tag de mm dans `release.env` (`v0.2.1`) et construit `k33g/mm-sandbox:0.2.1` : le tag de l'image est la version sans le `v`, comme les binaires de release, et le `mm` à l'intérieur est estampillé avec le tag — `mm --version` est exécuté dans l'image comme preuve. Le script réécrit ensuite la valeur par défaut de l'argument `tag` des kits à `0.2.1`, pour que kits et image avancent ensemble. `./docker-sbx/build.sh v0.1.5` construit une autre version ; une image antérieure reste joignable avec `--kit-arg tag=0.1.4`.
45		-
46		-L'image est dans votre store d'images Docker local : chaque `sbx run` ou `sbx create` sur ces kits prend `--pull never` tant qu'elle n'est pas poussée (`docker push k33g/mm-sandbox:0.2.1`), sinon `sbx` tente de la télécharger et échoue. Si `sbx` tourne sur une autre machine, `EXPORT=1 ./docker-sbx/build.sh` écrit aussi `tmp/mm-sandbox-0.2.1.tar`, à charger là-bas avec `sbx template load`.
47		-
48		-### 2. Mode fenêtre dans le terminal (kit `mm-tui`)
49		-
50		-Depuis le projet sur lequel `mm` doit travailler :
	36	+Le premier lancement construit le kit, crée le sandbox, monte le dossier courant comme espace de travail et lance `mm -tui`, qui lit `./agent.yaml`. Ajoutez les mixins avec `--kit` ; ce qui suit `--` remplace les arguments par défaut : c'est toute la ligne de commande de `mm` :
51	37
52	38	```bash
53		-sbx run --pull never ./docker-sbx/kits/mm-tui . -- agent.dmr.yaml
	39	+sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" \
	40	+ --kit ./kits/go-toolchain --kit ./kits/cli-tools \
	41	+ -- -tui -config agent.lucy.yaml
54	42	```
55	43
56		-La première fois, `sbx` crée le sandbox, monte le répertoire courant comme espace de travail et s'y attache ; puis il lance le point d'entrée du kit avec ce qui suit `--` en arguments — ici `mm -tui agent.dmr.yaml`, dans l'espace de travail. N'importe quel drapeau de `mm` passe de la même façon : `-- -config autre.yaml`.
	44	+Le sandbox garde son nom ; `sbx run --name mm-demo-remote` s'y rattache plus tard. La fenêtre est celle décrite dans [Utiliser le mode fenêtre](use-the-window-mode.md). Les sessions, quand `sessions.enabled` est actif, sont écrites sous `.mm/sessions` de l'espace de travail — votre dossier sur la machine hôte — et survivent donc au sandbox.
57	45
58		-Sans rien après `--`, `mm` lit l'argument `config` du kit, puis `./agent.yaml` dans l'espace de travail, puis ses valeurs par défaut :
	46	+Pour travailler sur le kit lui-même, clonez [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) et lancez-le depuis son dossier `demo/` : `sbx run --name mm-demo ../mini-me`.
59	47
60		-```bash
61		-sbx run --pull never ./docker-sbx/kits/mm-tui . --kit-arg config=agent.dmr.yaml
62		-```
63		-
64		-\| `--kit-arg` \| Défaut \| Effet \|
65		-\|---\|---\|---\|
66		-\| `config=<chemin>` \| vide \| Le fichier de configuration, comme `AGENT_CONFIG` de `mm` : relatif à l'espace de travail, ou absolu dans le sandbox. \|
67		-\| `tag=<version>` \| la dernière version construite (`0.2.1`) \| L'image `k33g/mm-sandbox:<version>` dont le sandbox est fait. \|
	48	+### 3. Depuis un éditeur (ACP)
68	49
69		-Le sandbox garde son nom (`mm-tui-<répertoire>` sauf `--name`) ; `sbx run --name <nom>` s'y rattache plus tard. À l'intérieur, la fenêtre est celle décrite dans [Utiliser le mode fenêtre](use-the-window-mode.md). Les sessions, quand `sessions.enabled` est actif, sont écrites sous `.mm/sessions` dans l'espace de travail — c'est votre répertoire hôte, elles survivent donc au sandbox.
	50	+Un éditeur parle à `mm -acp` par stdin et stdout bruts, ce que `sbx run` ne peut pas transporter (il alloue toujours un terminal). Créez le sandbox une fois, sans vous y attacher, puis laissez l'éditeur lancer `mm` dedans avec `sbx exec -i` :
70	51
71		-### 3. Depuis un éditeur (kit `mm-acp`)
	52	+1. Depuis le projet que l'éditeur ouvrira, avec la référence distante du kit :
72	53
73		-Un éditeur parle à `mm -acp` sur l'entrée et la sortie standard brutes de l'agent. `sbx run` ne peut pas porter cela : il alloue toujours un terminal. Le sandbox est donc créé une fois sans s'y attacher, et l'éditeur y lance `mm` avec `sbx exec -i`, qui transmet stdin et stdout tels quels.
	54	+ ```bash
	55	+ RELEASE=v0.0.1
	56	+ REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
	57	+ sbx create --name mm-acp "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" . \
	58	+ --kit /chemin/vers/mini-me/sbx/kits/go-toolchain
	59	+ ```
74	60
75		-1. Depuis le projet que l'éditeur ouvrira, créez le sandbox avec le fichier de configuration intégré (`.` est l'espace de travail, sbx le rend absolu ; le chemin du kit doit être explicite : `./`, `../` ou absolu) :
	61	+ ou avec un clone local de [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) (un chemin de kit doit commencer par `./`, `../` ou `/`) :
76	62
77	63	```bash
78		- cd /chemin/de/votre/projet
79		- sbx create --pull never --name mm-acp /chemin/de/mini-me/docker-sbx/kits/mm-acp . \
80		- --kit-arg config=agent.dmr.yaml
	64	+ git clone https://git.rickub.com/bots-garden/mini-me-kit.git /chemin/vers/mini-me-kit
	65	+ sbx create --name mm-acp /chemin/vers/mini-me-kit/mini-me . \
	66	+ --kit /chemin/vers/mini-me/sbx/kits/go-toolchain
81	67	```
82	68
83		- Un chemin d'espace de travail qui n'existe pas sur votre machine fait demander à sbx « The selected workspace does not exist. Would you like to create it? » — répondez `N` et corrigez le chemin.
	69	+ L'espace de travail (`.`) est fixé à la création : un sandbox par projet, chacun avec son propre `--name`.
	70	+
	71	+2. Vérifiez à la main :
84	72
85		- `--kit-arg config` devient l'`AGENT_CONFIG` du conteneur, relatif à l'espace de travail parce que c'est là que `sbx exec` démarre `mm`. L'espace de travail est fixé à la création : un sandbox par projet, chacun avec son `--name`.
	73	+ ```bash
	74	+ sbx exec -i mm-acp mm -acp -config agent.lucy.yaml
	75	+ ```
86	76
87		-2. Déclarez-le dans l'éditeur. Dans le `settings.json` de Zed :
	77	+3. Déclarez-le dans le `settings.json` de Zed :
88	78
89	79	```json
90	80	{
@@ -92,91 +82,55 @@ Un éditeur parle à `mm -acp` sur l'entrée et la sortie standard brutes de l'a
92	82	"mini-me (sandbox)": {
93	83	"type": "custom",
94	84	"command": "sbx",
95		- "args": ["exec", "-i", "mm-acp", "mm", "-acp"]
	85	+ "args": ["exec", "-i", "mm-acp", "mm", "-acp", "-config", "agent.lucy.yaml"]
96	86	}
97	87	}
98	88	}
99	89	```
100	90
101		- Par rapport à [la configuration côté hôte](use-from-an-editor.md), la commande est `sbx` et aucun `env` n'est nécessaire : `AGENT_CONFIG` est déjà dans le conteneur. Si l'éditeur ne trouve pas `sbx`, mettez le chemin absolu donné par `which sbx` dans `"command"`.
102		-
103		-3. Ouvrez le panneau agent et choisissez mini-me (sandbox). L'éditeur lance `mm -acp` dans le sandbox à chaque conversation ; `sbx exec` démarre d'abord le sandbox s'il est arrêté. Appels d'outils, dialogues de permission, mentions `@fichier` et menu des commandes fonctionnent comme sur l'hôte — la différence est l'endroit où les commandes s'exécutent.
104		-
105		-S'attacher à ce sandbox avec `sbx run --name mm-acp` ne lance pas `mm` : son point d'entrée affiche le câblage ci-dessus avec le vrai nom et les vrais chemins du sandbox, puis ouvre un shell à l'intérieur. `sbx exec -it mm-acp bash` est le chemin le plus court vers ce shell.
	91	+ Si l'éditeur ne trouve pas `sbx`, mettez le chemin absolu donné par `which sbx` dans `"command"`. Les appels d'outils, les demandes de permission, les mentions `@fichier` et le menu des commandes slash fonctionnent comme sur l'hôte ; la différence est l'endroit où les commandes s'exécutent. Voir [Utiliser mini-me depuis un éditeur](use-from-an-editor.md) pour l'installation côté hôte.
106	92
107	93	## Le serveur de modèles reste sur l'hôte
108	94
109		-Dans un sandbox, `localhost` est le sandbox lui-même. Votre serveur de modèles continue de tourner sur votre machine et se joint par `host.docker.internal`, que le proxy du sandbox fait pointer vers le `localhost` de l'hôte.
110		-
111		-- Docker Model Runner — rien à changer : `agent.dmr.yaml` a déjà `fallback: http://host.docker.internal:12434/engines/v1`, et `mm` bascule dessus quand `localhost:12434` ne répond pas (la bannière dit quelle URL a gagné).
112		-- llama-server — `agent.llamacpp.yaml` n'a pas de fallback. Soit vous changez son `baseUrl` en `http://host.docker.internal:8080/v1`, soit vous passez `--env AGENT_BASE_URL=http://host.docker.internal:8080/v1` à `sbx run` / `sbx create` (voir [Faire tourner sur llama.cpp](run-with-llama-cpp.md)).
113		-
114		-Les deux kits autorisent les ports 12434 et 8080 de l'hôte dans la politique réseau du sandbox. Pour un autre port : `sbx policy allow network host.docker.internal:<port>`.
115		-
116		-## Publier une version
117		-
118		-La publication est une étape manuelle, depuis une machine avec Docker Desktop (buildx et la CLI `sbx`) ; le workflow Release ne construit que les binaires. Un script construit l'image pour linux/amd64 et linux/arm64, la pousse, puis valide et pousse les deux kits, le tout au tag de mm :
119		-
120		-```bash
121		-export DOCKER_HANDLE=k33g # le compte Docker Hub, aussi propriétaire de l'image
122		-export DOCKER_PAT=dckr_pat_… # un jeton d'accès en lecture/écriture
123		-./docker-sbx/publish.sh # TAG depuis release.env : v0.2.1 → k33g/mm-sandbox:0.2.1, k33g/mm-tui:0.2.1, k33g/mm-acp:0.2.1
124		-```
125		-
126		-Avec les deux variables, le script se connecte avec elles et se déconnecte à la fin ; sans elles, il réutilise votre `docker login` existant. Ses deux moitiés se lancent seules : `PUSH=1 ./docker-sbx/build.sh v0.2.1` (l'image) et `./docker-sbx/push-kits.sh v0.2.1` (les kits, `SBX=/chemin/vers/sbx` si la CLI n'est pas sur le PATH). Les deux appellent d'abord `sync-kits.sh`, qui réécrit `version`, le `tag` par défaut et le propriétaire de l'image des kits, de sorte qu'un kit publié nomme toujours l'image poussée avec lui — commitez ensuite les deux `spec.yaml`. `sbx kit push` parle directement au registre et s'authentifie depuis le magasin d'identifiants Docker, sans démon sandbox. `IMAGE_OWNER=<compte>` publie sous un autre compte.
	95	+Dans un sandbox, `localhost` est le sandbox lui-même. Votre serveur de modèles continue de tourner sur votre machine et se joint par `host.docker.internal`, que le proxy du sandbox redirige vers votre machine.
127	96
128		-## Serveurs MCP via la passerelle sbx (exemple : GitHub)
	97	+- La politique réseau du kit `mini-me` autorise `host.docker.internal:12434` (Docker Model Runner), `:11434` (Ollama) et `:17434` (llmman). `agent.dmr.yaml` se replie déjà sur `http://host.docker.internal:12434/engines/v1` ; les configurations livrées dans `sbx/` utilisent llmman (`fallback: http://host.docker.internal:17434/v1`).
	98	+- Pour un autre port — le `8080` de llama-server, par exemple — ajoutez-le à la capacité `network-policy` du kit, ou autorisez-le pour un seul sandbox :
129	99
130		-Dans un sandbox, `mm` ne parle pas lui-même aux serveurs MCP et ne détient aucun jeton. `sbx` démarre une passerelle MCP par sandbox, sur l'hôte. À la création du sandbox, il inscrit deux variables dans le conteneur : `MCP_GATEWAY_URL` (`http://mcp-gateway.docker.internal/mcp`) et `MCP_SENTINEL_TOKEN_NAME`, un substitut que le proxy du sandbox remplace par le vrai identifiant. Quand `mm` trouve `MCP_GATEWAY_URL` et `mcp.enabled: true`, il ajoute un serveur nommé `sbx-gateway`, dont les outils apparaissent sous la forme `sbx-gateway_<outil>`. Le kit n'a besoin d'aucune règle réseau pour cela, car le proxy route cet hôte lui-même.
	100	+ ```bash
	101	+ sbx policy allow network host.docker.internal:8080
	102	+ ```
131	103
132		-1. Enregistrez une fois, sur l'hôte, le serveur officiel de GitHub via `docker-sbx/mcp/github-mcp.sh`. Le script lance `ghcr.io/github/github-mcp-server` dans Docker avec votre jeton. sbx l'exécute comme enfant de sandboxd, qui ne voit pas les variables de votre shell. Rangez donc le jeton une fois dans le trousseau macOS, sous le service `github-mcp`. Le script accepte aussi `GITHUB_PERSONAL_ACCESS_TOKEN`, `GITHUB_OAUTH_TOKEN` ou un `gh` connecté. sbx l'exécute sur l'hôte, donc le jeton n'entre jamais dans le sandbox. Par défaut, il expose 25 outils en lecture seule, dont `get_me` et `get_teams`. Pour en avoir plus, définissez `GITHUB_READ_ONLY=0` et un `GITHUB_TOOLSETS` plus large dans l'environnement du script.
	104	+ `sbx policy log` montre ce qui a été bloqué.
133	105
134		- ```bash
135		- security add-generic-password -U -a "$USER" -s github-mcp -w # demande le jeton
136		- sbx mcp rm github 2>/dev/null # un ancien "github" est le serveur ARCHIVÉ du catalogue
137		- sbx mcp add github-mm --command "$PWD/docker-sbx/mcp/github-mcp.sh"
138		- sbx mcp ls # github-mm doit être prêt
139		- ```
140		-
141		- N'utilisez pas le nom `github` seul. Le catalogue Docker MCP le résout en « GitHub (Archived) », l'ancien serveur npm, qui n'a pas `get_me` et propose d'autres outils. L'entrée `github-official` du catalogue ne convient pas non plus en mode local. Là, une image du catalogue est lancée par un simple `docker run`, sans environnement, donc sans jeton.
142		-
143		-2. Créez un nouveau sandbox avec ce serveur dans son ensemble fixe. `--static-mcp` est une option de `sbx` : elle se place avant `--`, car tout ce qui suit `--` va à `mm`. Elle ne s'applique qu'à la création, donc supprimez d'abord un ancien sandbox du même nom :
144		-
145		- ```bash
146		- cd /chemin/du/projet
147		- sbx rm mm-mcp-github 2>/dev/null
148		- sbx run --name mm-mcp-github --static-mcp github-mm k33g/mm-tui:<version> . -- agent.dmr.sbx.yaml
149		- ```
	106	+## Changer une version
150	107
151		-3. La configuration doit seulement activer MCP. `demo/agent.dmr.sbx.yaml` contient :
	108	+- mm : le `default` de `mm_version` dans `mini-me/mini-me.yaml` du dépôt [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) — un tag de release comme `v0.3.0` ; le tag du kit lui-même (`RELEASE` ci-dessus) désigne alors le nouveau kit. La construction télécharge `https://rickub.com/bots-garden/mini-me/releases/download/<tag>/mm-<version>-linux-<arch>` ; un tag sans release correspondante fait échouer la construction.
	109	+- Go, gopls, rg, bat, eza : le `default` de l'argument correspondant dans le YAML du mixin (`go_version`, `gopls_version`, `rg_version`, `bat_version`, `eza_version`) ; chacun a un `pattern` qui refuse une version mal formée.
152	110
153		- ```yaml
154		- mcp:
155		- enabled: true
156		- permissions: ask
157		- discoveryTimeout: 10s
158		- servers: [] # mm ajoute la passerelle quand MCP_GATEWAY_URL est défini
159		- ```
	111	+## Des serveurs MCP via la passerelle de sbx
160	112
161		- La bannière liste alors `sbx-gateway_get_me`, `sbx-gateway_list_issues`, etc. dans `tools:`.
	113	+Dans un sandbox, `mm` ne parle pas lui-même aux serveurs MCP et ne détient aucun jeton. `sbx` lance une passerelle MCP par sandbox, sur l'hôte, et inscrit `MCP_GATEWAY_URL` dans le conteneur. Quand `mm` trouve `MCP_GATEWAY_URL` et `mcp.enabled: true`, il ajoute un serveur nommé `sbx-gateway`, dont les outils apparaissent sous la forme `sbx-gateway_<outil>` :
162	114
163		-Une image de kit construite avant ce changement ne peut pas utiliser la passerelle. Elle ne découvre rien et affiche `method "tools/list" is invalid during session initialization`. La passerelle suit strictement le transport Streamable HTTP de MCP : elle exige d'abord `initialize`, puis le `Mcp-Session-Id` renvoyé sur chaque requête. L'ancien `mm` sautait les deux. C'était sans effet face à `api.githubcopilot.com`, mais bloquant ici. Reconstruisez et republiez le kit après la mise à jour.
164		-
165		-Si la bannière ne liste aucun outil `sbx-gateway_*`, vérifiez l'enregistrement avec `sbx mcp inspect github-mm`, puis lisez le journal MCP de sbx, `mcp/mcp.log` dans son répertoire d'état. `github-mcp: no token` dans ce journal signifie que le script n'a trouvé aucun jeton : vérifiez l'entrée du trousseau avec `security find-generic-password -s github-mcp`. L'endpoint distant `https://api.githubcopilot.com/mcp/` est une autre voie, mais seulement avec une OAuth App GitHub. GitHub ne propose pas l'enregistrement dynamique de client, donc en mode local `sbx mcp add` le refuse sans `--client-id`, même avec un en-tête `Authorization`.
	115	+```yaml
	116	+mcp:
	117	+ enabled: true
	118	+ permissions: ask
	119	+ discoveryTimeout: 10s
	120	+ servers: [] # la passerelle est ajoutée par mm quand MCP_GATEWAY_URL est défini
	121	+```
166	122
167		-Nommez le dépôt dans vos demandes, par exemple « liste les issues ouvertes de k33g/mon-depot ». Un petit modèle à qui l'on dit seulement « mon organisation » invente un propriétaire et un dépôt, et chaque appel revient en `Not Found`.
	123	+Déclarez le serveur sur l'hôte (`sbx mcp add <nom> --command <script>`), puis créez un nouveau sandbox qui l'a dans son ensemble fixe — `--static-mcp <nom>` est une option de `sbx` et se place avant `--`. Si aucun outil `sbx-gateway_*` n'apparaît dans la bannière, `sbx mcp inspect <nom>` et le fichier `mcp/mcp.log` de sbx disent pourquoi.
168	124
169	125	## Variantes
170	126
171		-- Une autre configuration pour une session d'éditeur. Ajoutez `"-e", "AGENT_CONFIG=agent.lsp.yaml"` avant le nom du sandbox dans `"args"` ; `sbx exec -e` remplace la valeur intégrée pour cette exécution seulement.
172		-- Skills. `skillsDir` est relatif au répertoire où `mm` tourne, c'est-à-dire l'espace de travail dans les deux kits — la même règle que sur l'hôte.
173		-- Docker dans le sandbox. Construisez le template sur le shell Docker-in-Docker : `SHELL_TEMPLATE=docker/sandbox-templates:shell-docker ./docker-sbx/build.sh`.
174		-- Lire les logs. En mode fenêtre ils sont à l'écran ; en ACP ils vont sur stderr, que Zed montre sous `dev: open acp logs`.
175		-- Supprimer un sandbox. `sbx rm mm-acp`. Le répertoire du projet est un montage et n'est pas touché.
	127	+- Skills. `skillsDir` est relatif au dossier où tourne `mm` — l'espace de travail — comme sur l'hôte.
	128	+- Lire les journaux. En mode fenêtre, ils sont à l'écran ; en ACP, ils vont sur stderr, que Zed affiche sous `dev: open acp logs`.
	129	+- Un shell dans le sandbox. `sbx exec -it mm-acp bash`.
	130	+- Supprimer un sandbox. `sbx rm mm-acp`. Le dossier du projet est un montage et n'est pas touché.
176	131
177	132	## Voir aussi
178	133
179		-- Le format suivi par ces deux fichiers : la spécification des kits de Docker Sandboxes (`schemaVersion: "2"`), livrée avec les sources de `sbx`.
180		-- Les mêmes kits pour la spécification de kit v3 : [Faire tourner mini-me avec les kits sandbox v3](run-with-sandbox-kits-v3.md).
	134	+- Le format des kits : [spécification v3](https://github.com/docker/sandbox-kit-spec).
181	135	- Ce que `mm -acp` expose à l'éditeur : [référence ACP](../reference/acp.md).
182		-- Les drapeaux et variables d'environnement que `mm` lit : [référence de la ligne de commande](../reference/cli.md).
	136	+- Les options et variables d'environnement que lit `mm` : [référence de la ligne de commande](../reference/cli.md).

--# Faire tourner mini-me dans un Docker Sandbox
++# Comment faire tourner mini-me dans un Docker Sandbox
--Ce guide montre comment exécuter `mm` dans un [Docker Sandbox](https://docs.docker.com/ai/sandboxes/), pour que chaque commande lancée par le modèle et chaque fichier qu'il modifie le soient dans un conteneur, sur votre projet monté. Il couvre les deux usages : le mode fenêtre dans votre terminal, et depuis un éditeur via l'Agent Client Protocol. Il suppose Docker Desktop avec la commande `sbx`, et un serveur de modèles (Docker Model Runner ou llama-server) qui tourne sur votre machine.
++Ce guide montre comment lancer `mm` dans un [Docker Sandbox](https://docs.docker.com/ai/sandboxes/), pour que chaque commande lancée par le modèle et chaque fichier qu'il modifie le soient dans un conteneur, sur une copie montée de votre projet. Il couvre le mode fenêtre dans votre terminal et un éditeur via l'Agent Client Protocol. Il suppose Docker Desktop avec la commande `sbx`, et un serveur de modèles qui tourne sur votre machine.
--> Ce sont les kits **v2** (`spec.yaml`). Les deux mêmes kits existent aussi pour la spécification de kit v3, sous `docker-sbx-v3/` : voir [Faire tourner mini-me avec les kits sandbox v3](run-with-sandbox-kits-v3.md).
++Tout se trouve sous [`sbx/`](../../../sbx/README.md) dans le dépôt. Les kits suivent la [spécification des kits v3](https://github.com/docker/sandbox-kit-spec) (`schemaVersion: "3"`) : un **workload** qui lance `mm`, et des **mixins** qu'on lui ajoute avec `--kit`.
--Tout est sous [`docker-sbx/`](../../../docker-sbx/README.md) dans le dépôt :
++| Élément | Où | Ce que c'est |
++|---|---|---|
++| `mini-me` | [bots-garden/mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), dossier `mini-me/` | Le **workload** : le template `shell` de Docker (Ubuntu, utilisateur `agent`) avec le binaire `mm` d'une release (`mm_version`, `v0.3.0` par défaut), téléchargé depuis la page de release de mini-me. Point d'entrée `mm`, arguments par défaut `-tui`. Versionné par ses propres tags (`v0.0.1`). |
++| `go-toolchain` | `sbx/kits/go-toolchain/` | Un **mixin** : Go (`go_version`, `1.27.2` par défaut), `gofmt` et `gopls` (`gopls_version`, `latest` par défaut). Autorise à l'exécution les hôtes des modules : `proxy.golang.org`, `sum.golang.org`, `github.com`, `golang.org`. |
++| `cli-tools` | `sbx/kits/cli-tools/` | Un **mixin** : `rg`, `bat` et `eza` en binaires statiques. Pas de réseau à l'exécution. |
++| `agent.yaml`, `agent.lucy.yaml` | `sbx/` | Deux configurations `mm` pour llmman (Jan-nano, Lucy). |
++| `AGENTS.md` | `sbx/` | Les consignes de l'agent qui travaille dans le sandbox (les outils installés, comment lancer Go) : `mm` les ajoute à son prompt système quand il tourne dans ce dossier — voir [Comment donner à l'agent les consignes de votre projet](give-project-instructions.md). |
--| Élément | Ce que c'est |
++## Étapes
--|---|---|
--| `template/Dockerfile` | Le **template** : l'image `shell` de Docker Sandboxes avec `mm` compilé depuis ce dépôt, plus les deux points d'entrée ci-dessous. |
--| `kits/mm-tui/spec.yaml` | Un **kit sandbox** : `sbx run` dessus ouvre le mode fenêtre de `mm` sur l'espace de travail. |
--| `kits/mm-acp/spec.yaml` | Un **kit sandbox** pour un éditeur : créé une fois avec `sbx create`, l'éditeur y lance ensuite `mm -acp`. |
--| `build.sh` | Construit l'image du template, `k33g/mm-sandbox:<version>` ; `PUSH=1` la construit pour linux/amd64 et linux/arm64 et la pousse. |
--| `sync-kits.sh`, `push-kits.sh` | Alignent les kits sur une image, et les publient sur Docker Hub comme artefacts OCI de kit. |
--## Utiliser les kits publiés
++### 1. Autoriser la source du kit
--Chaque release publie l'image et les deux kits sur Docker Hub à la version de mm — `k33g/mm-sandbox:0.2.1`, `k33g/mm-tui:0.2.1`, `k33g/mm-acp:0.2.1` — le chemin le plus court ne demande donc aucune construction. Docker Hub est une source de kits autorisée par défaut (`sbx settings get kit.allowedSources` montre `docker.io/`), et une référence avec un `/` mais sans hôte de registre est lue comme `docker.io/…` :
++Le kit `mini-me` est désigné par son URL git, un tag et son dossier. Son hôte doit être une source de kits autorisée, une fois pour toutes :
  ```bash
--cd /chemin/de/votre/projet
++sbx settings set kit.allowedSources '["docker.io/","git.rickub.com/bots-garden/"]'
--sbx run k33g/mm-tui:0.2.1 . -- agent.dmr.yaml
  ```
--pour le mode fenêtre, et pour un éditeur :
++### 2. Mode fenêtre dans le terminal
--
--```bash
--sbx create --name mm-acp k33g/mm-acp:0.2.1 . --kit-arg config=agent.dmr.yaml
--```
--puis la déclaration dans l'éditeur de l'étape 3 ci-dessous. Pas de `--pull never` : le kit nomme `k33g/mm-sandbox:0.2.1` et sbx la télécharge. `sbx kit inspect k33g/mm-tui:0.2.1` montre ce qu'un kit déclare avant de le lancer. Les étapes qui suivent construisent la même chose en local, pour un mm en cours de travail.
++Depuis le dossier sur lequel `mm` doit travailler — `sbx/` lui-même, pour utiliser ses configurations et son `AGENTS.md` :
--
--## Étapes
--
--### 1. Construire le template
--
--Depuis la racine du dépôt :
  ```bash
--./docker-sbx/build.sh
++cd sbx
++RELEASE=v0.0.1
++REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
++sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me"
  ```
--Cela lit le tag de mm dans `release.env` (`v0.2.1`) et construit `k33g/mm-sandbox:0.2.1` : le tag de l'image est la version sans le `v`, comme les binaires de release, et le `mm` à l'intérieur est estampillé avec le tag — `mm --version` est exécuté dans l'image comme preuve. Le script réécrit ensuite la valeur par défaut de l'argument `tag` des kits à `0.2.1`, pour que kits et image avancent ensemble. `./docker-sbx/build.sh v0.1.5` construit une autre version ; une image antérieure reste joignable avec `--kit-arg tag=0.1.4`.
++Le premier lancement construit le kit, crée le sandbox, monte le dossier courant comme espace de travail et lance `mm -tui`, qui lit `./agent.yaml`. Ajoutez les mixins avec `--kit` ; ce qui suit `--` remplace les arguments par défaut : c'est toute la ligne de commande de `mm` :
--
--L'image est dans votre store d'images Docker local : chaque `sbx run` ou `sbx create` sur ces kits prend `--pull never` tant qu'elle n'est pas poussée (`docker push k33g/mm-sandbox:0.2.1`), sinon `sbx` tente de la télécharger et échoue. Si `sbx` tourne sur une autre machine, `EXPORT=1 ./docker-sbx/build.sh` écrit aussi `tmp/mm-sandbox-0.2.1.tar`, à charger là-bas avec `sbx template load`.
--
--### 2. Mode fenêtre dans le terminal (kit `mm-tui`)
--
--Depuis le projet sur lequel `mm` doit travailler :
  ```bash
--sbx run --pull never ./docker-sbx/kits/mm-tui . -- agent.dmr.yaml
++sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" \
++    --kit ./kits/go-toolchain --kit ./kits/cli-tools \
++    -- -tui -config agent.lucy.yaml
  ```
--La première fois, `sbx` crée le sandbox, monte le répertoire courant comme espace de travail et s'y attache ; puis il lance le point d'entrée du kit avec ce qui suit `--` en arguments — ici `mm -tui agent.dmr.yaml`, dans l'espace de travail. N'importe quel drapeau de `mm` passe de la même façon : `-- -config autre.yaml`.
++Le sandbox garde son nom ; `sbx run --name mm-demo-remote` s'y rattache plus tard. La fenêtre est celle décrite dans [Utiliser le mode fenêtre](use-the-window-mode.md). Les sessions, quand `sessions.enabled` est actif, sont écrites sous `.mm/sessions` de l'espace de travail — votre dossier sur la machine hôte — et survivent donc au sandbox.
--Sans rien après `--`, `mm` lit l'argument `config` du kit, puis `./agent.yaml` dans l'espace de travail, puis ses valeurs par défaut :
++Pour travailler sur le kit lui-même, clonez [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) et lancez-le depuis son dossier `demo/` : `sbx run --name mm-demo ../mini-me`.
--```bash
++### 3. Depuis un éditeur (ACP)
--sbx run --pull never ./docker-sbx/kits/mm-tui . --kit-arg config=agent.dmr.yaml
--```
--
--| `--kit-arg` | Défaut | Effet |
--|---|---|---|
--| `config=<chemin>` | vide | Le fichier de configuration, comme `AGENT_CONFIG` de `mm` : relatif à l'espace de travail, ou absolu dans le sandbox. |
--| `tag=<version>` | la dernière version construite (`0.2.1`) | L'image `k33g/mm-sandbox:<version>` dont le sandbox est fait. |
--Le sandbox garde son nom (`mm-tui-<répertoire>` sauf `--name`) ; `sbx run --name <nom>` s'y rattache plus tard. À l'intérieur, la fenêtre est celle décrite dans [Utiliser le mode fenêtre](use-the-window-mode.md). Les sessions, quand `sessions.enabled` est actif, sont écrites sous `.mm/sessions` dans l'espace de travail — c'est votre répertoire hôte, elles survivent donc au sandbox.
++Un éditeur parle à `mm -acp` par stdin et stdout bruts, ce que `sbx run` ne peut pas transporter (il alloue toujours un terminal). Créez le sandbox une fois, sans vous y attacher, puis laissez l'éditeur lancer `mm` dedans avec `sbx exec -i` :
--### 3. Depuis un éditeur (kit `mm-acp`)
++1. Depuis le projet que l'éditeur ouvrira, avec la référence distante du kit :
--Un éditeur parle à `mm -acp` sur l'entrée et la sortie standard brutes de l'agent. `sbx run` ne peut pas porter cela : il alloue toujours un terminal. Le sandbox est donc créé une fois sans s'y attacher, et l'éditeur y lance `mm` avec `sbx exec -i`, qui transmet stdin et stdout tels quels.
++   ```bash
++   RELEASE=v0.0.1
++   REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
++   sbx create --name mm-acp "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" . \
++       --kit /chemin/vers/mini-me/sbx/kits/go-toolchain
++   ```
--1. Depuis le projet que l'éditeur ouvrira, créez le sandbox avec le fichier de configuration intégré (`.` est l'espace de travail, sbx le rend absolu ; le chemin du kit doit être explicite : `./`, `../` ou absolu) :
++   ou avec un clone local de [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) (un chemin de kit doit commencer par `./`, `../` ou `/`) :
     ```bash
--   cd /chemin/de/votre/projet
++   git clone https://git.rickub.com/bots-garden/mini-me-kit.git /chemin/vers/mini-me-kit
--   sbx create --pull never --name mm-acp /chemin/de/mini-me/docker-sbx/kits/mm-acp . \
++   sbx create --name mm-acp /chemin/vers/mini-me-kit/mini-me . \
--       --kit-arg config=agent.dmr.yaml
++       --kit /chemin/vers/mini-me/sbx/kits/go-toolchain
     ```
--   Un chemin d'espace de travail qui n'existe pas sur votre machine fait demander à sbx « The selected workspace does not exist. Would you like to create it? » — répondez `N` et corrigez le chemin.
++   L'espace de travail (`.`) est fixé à la création : un sandbox par projet, chacun avec son propre `--name`.
++
++2. Vérifiez à la main :
--   `--kit-arg config` devient l'`AGENT_CONFIG` du conteneur, relatif à l'espace de travail parce que c'est là que `sbx exec` démarre `mm`. L'espace de travail est fixé à la création : un sandbox par projet, chacun avec son `--name`.
++   ```bash
++   sbx exec -i mm-acp mm -acp -config agent.lucy.yaml
++   ```
--2. Déclarez-le dans l'éditeur. Dans le `settings.json` de Zed :
++3. Déclarez-le dans le `settings.json` de Zed :
     ```json
     {
         "mini-me (sandbox)": {
           "type": "custom",
           "command": "sbx",
--         "args": ["exec", "-i", "mm-acp", "mm", "-acp"]
++         "args": ["exec", "-i", "mm-acp", "mm", "-acp", "-config", "agent.lucy.yaml"]
         }
       }
     }
     ```
--   Par rapport à [la configuration côté hôte](use-from-an-editor.md), la commande est `sbx` et aucun `env` n'est nécessaire : `AGENT_CONFIG` est déjà dans le conteneur. Si l'éditeur ne trouve pas `sbx`, mettez le chemin absolu donné par `which sbx` dans `"command"`.
++   Si l'éditeur ne trouve pas `sbx`, mettez le chemin absolu donné par `which sbx` dans `"command"`. Les appels d'outils, les demandes de permission, les mentions `@fichier` et le menu des commandes slash fonctionnent comme sur l'hôte ; la différence est l'endroit où les commandes s'exécutent. Voir [Utiliser mini-me depuis un éditeur](use-from-an-editor.md) pour l'installation côté hôte.
--
--3. Ouvrez le panneau agent et choisissez **mini-me (sandbox)**. L'éditeur lance `mm -acp` dans le sandbox à chaque conversation ; `sbx exec` démarre d'abord le sandbox s'il est arrêté. Appels d'outils, dialogues de permission, mentions `@fichier` et menu des commandes fonctionnent comme sur l'hôte — la différence est l'endroit où les commandes s'exécutent.
--
--S'attacher à ce sandbox avec `sbx run --name mm-acp` ne lance pas `mm` : son point d'entrée affiche le câblage ci-dessus avec le vrai nom et les vrais chemins du sandbox, puis ouvre un shell à l'intérieur. `sbx exec -it mm-acp bash` est le chemin le plus court vers ce shell.
  ## Le serveur de modèles reste sur l'hôte
--Dans un sandbox, `localhost` est le sandbox lui-même. Votre serveur de modèles continue de tourner sur votre machine et se joint par `host.docker.internal`, que le proxy du sandbox fait pointer vers le `localhost` de l'hôte.
++Dans un sandbox, `localhost` est le sandbox lui-même. Votre serveur de modèles continue de tourner sur votre machine et se joint par `host.docker.internal`, que le proxy du sandbox redirige vers votre machine.
--
--- **Docker Model Runner** — rien à changer : `agent.dmr.yaml` a déjà `fallback: http://host.docker.internal:12434/engines/v1`, et `mm` bascule dessus quand `localhost:12434` ne répond pas (la bannière dit quelle URL a gagné).
--- **llama-server** — `agent.llamacpp.yaml` n'a pas de fallback. Soit vous changez son `baseUrl` en `http://host.docker.internal:8080/v1`, soit vous passez `--env AGENT_BASE_URL=http://host.docker.internal:8080/v1` à `sbx run` / `sbx create` (voir [Faire tourner sur llama.cpp](run-with-llama-cpp.md)).
--
--Les deux kits autorisent les ports 12434 et 8080 de l'hôte dans la politique réseau du sandbox. Pour un autre port : `sbx policy allow network host.docker.internal:<port>`.
--
--## Publier une version
--
--La publication est une étape manuelle, depuis une machine avec Docker Desktop (buildx et la CLI `sbx`) ; le workflow Release ne construit que les binaires. Un script construit l'image pour linux/amd64 et linux/arm64, la pousse, puis valide et pousse les deux kits, le tout au tag de mm :
--
--```bash
--export DOCKER_HANDLE=k33g          # le compte Docker Hub, aussi propriétaire de l'image
--export DOCKER_PAT=dckr_pat_…       # un jeton d'accès en lecture/écriture
--./docker-sbx/publish.sh            # TAG depuis release.env : v0.2.1 → k33g/mm-sandbox:0.2.1, k33g/mm-tui:0.2.1, k33g/mm-acp:0.2.1
--```
--
--Avec les deux variables, le script se connecte avec elles et se déconnecte à la fin ; sans elles, il réutilise votre `docker login` existant. Ses deux moitiés se lancent seules : `PUSH=1 ./docker-sbx/build.sh v0.2.1` (l'image) et `./docker-sbx/push-kits.sh v0.2.1` (les kits, `SBX=/chemin/vers/sbx` si la CLI n'est pas sur le PATH). Les deux appellent d'abord `sync-kits.sh`, qui réécrit `version`, le `tag` par défaut et le propriétaire de l'image des kits, de sorte qu'un kit publié nomme toujours l'image poussée avec lui — commitez ensuite les deux `spec.yaml`. `sbx kit push` parle directement au registre et s'authentifie depuis le magasin d'identifiants Docker, sans démon sandbox. `IMAGE_OWNER=<compte>` publie sous un autre compte.
--## Serveurs MCP via la passerelle sbx (exemple : GitHub)
++- La politique réseau du kit `mini-me` autorise **`host.docker.internal:12434`** (Docker Model Runner), **`:11434`** (Ollama) et **`:17434`** (llmman). `agent.dmr.yaml` se replie déjà sur `http://host.docker.internal:12434/engines/v1` ; les configurations livrées dans `sbx/` utilisent llmman (`fallback: http://host.docker.internal:17434/v1`).
++- Pour un autre port — le `8080` de llama-server, par exemple — ajoutez-le à la capacité `network-policy` du kit, ou autorisez-le pour un seul sandbox :
--Dans un sandbox, `mm` ne parle pas lui-même aux serveurs MCP et ne détient aucun jeton. `sbx` démarre une passerelle MCP par sandbox, sur l'hôte. À la création du sandbox, il inscrit deux variables dans le conteneur : `MCP_GATEWAY_URL` (`http://mcp-gateway.docker.internal/mcp`) et `MCP_SENTINEL_TOKEN_NAME`, un substitut que le proxy du sandbox remplace par le vrai identifiant. Quand `mm` trouve `MCP_GATEWAY_URL` et `mcp.enabled: true`, il ajoute un serveur nommé `sbx-gateway`, dont les outils apparaissent sous la forme `sbx-gateway_<outil>`. Le kit n'a besoin d'aucune règle réseau pour cela, car le proxy route cet hôte lui-même.
++  ```bash
++  sbx policy allow network host.docker.internal:8080
++  ```
--1. Enregistrez une fois, sur l'hôte, le serveur officiel de GitHub via `docker-sbx/mcp/github-mcp.sh`. Le script lance `ghcr.io/github/github-mcp-server` dans Docker avec votre jeton. sbx l'exécute comme enfant de sandboxd, qui ne voit pas les variables de votre shell. Rangez donc le jeton une fois dans le trousseau macOS, sous le service `github-mcp`. Le script accepte aussi `GITHUB_PERSONAL_ACCESS_TOKEN`, `GITHUB_OAUTH_TOKEN` ou un `gh` connecté. sbx l'exécute sur l'hôte, donc le jeton n'entre jamais dans le sandbox. Par défaut, il expose 25 outils en lecture seule, dont `get_me` et `get_teams`. Pour en avoir plus, définissez `GITHUB_READ_ONLY=0` et un `GITHUB_TOOLSETS` plus large dans l'environnement du script.
++  `sbx policy log` montre ce qui a été bloqué.
--   ```bash
++## Changer une version
--   security add-generic-password -U -a "$USER" -s github-mcp -w   # demande le jeton
--   sbx mcp rm github 2>/dev/null               # un ancien "github" est le serveur ARCHIVÉ du catalogue
--   sbx mcp add github-mm --command "$PWD/docker-sbx/mcp/github-mcp.sh"
--   sbx mcp ls                                  # github-mm doit être prêt
--   ```
--
--   N'utilisez pas le nom `github` seul. Le catalogue Docker MCP le résout en « GitHub (Archived) », l'ancien serveur npm, qui n'a pas `get_me` et propose d'autres outils. L'entrée `github-official` du catalogue ne convient pas non plus en mode local. Là, une image du catalogue est lancée par un simple `docker run`, sans environnement, donc sans jeton.
--
--2. Créez un **nouveau** sandbox avec ce serveur dans son ensemble fixe. `--static-mcp` est une option de `sbx` : elle se place **avant** `--`, car tout ce qui suit `--` va à `mm`. Elle ne s'applique qu'à la création, donc supprimez d'abord un ancien sandbox du même nom :
--
--   ```bash
--   cd /chemin/du/projet
--   sbx rm mm-mcp-github 2>/dev/null
--   sbx run --name mm-mcp-github --static-mcp github-mm k33g/mm-tui:<version> . -- agent.dmr.sbx.yaml
--   ```
--3. La configuration doit seulement activer MCP. `demo/agent.dmr.sbx.yaml` contient :
++- **mm** : le `default` de `mm_version` dans `mini-me/mini-me.yaml` du dépôt [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) — un tag de release comme `v0.3.0` ; le tag du kit lui-même (`RELEASE` ci-dessus) désigne alors le nouveau kit. La construction télécharge `https://rickub.com/bots-garden/mini-me/releases/download/<tag>/mm-<version>-linux-<arch>` ; un tag sans release correspondante fait échouer la construction.
++- **Go, gopls, rg, bat, eza** : le `default` de l'argument correspondant dans le YAML du mixin (`go_version`, `gopls_version`, `rg_version`, `bat_version`, `eza_version`) ; chacun a un `pattern` qui refuse une version mal formée.
--   ```yaml
++## Des serveurs MCP via la passerelle de sbx
--   mcp:
--     enabled: true
--     permissions: ask
--     discoveryTimeout: 10s
--     servers: []        # mm ajoute la passerelle quand MCP_GATEWAY_URL est défini
--   ```
--   La bannière liste alors `sbx-gateway_get_me`, `sbx-gateway_list_issues`, etc. dans `tools:`.
++Dans un sandbox, `mm` ne parle pas lui-même aux serveurs MCP et ne détient aucun jeton. `sbx` lance une passerelle MCP par sandbox, sur l'hôte, et inscrit `MCP_GATEWAY_URL` dans le conteneur. Quand `mm` trouve `MCP_GATEWAY_URL` et `mcp.enabled: true`, il ajoute un serveur nommé `sbx-gateway`, dont les outils apparaissent sous la forme `sbx-gateway_<outil>` :
--Une image de kit construite avant ce changement ne peut pas utiliser la passerelle. Elle ne découvre rien et affiche `method "tools/list" is invalid during session initialization`. La passerelle suit strictement le transport Streamable HTTP de MCP : elle exige d'abord `initialize`, puis le `Mcp-Session-Id` renvoyé sur chaque requête. L'ancien `mm` sautait les deux. C'était sans effet face à `api.githubcopilot.com`, mais bloquant ici. Reconstruisez et republiez le kit après la mise à jour.
++```yaml
--
++mcp:
--Si la bannière ne liste aucun outil `sbx-gateway_*`, vérifiez l'enregistrement avec `sbx mcp inspect github-mm`, puis lisez le journal MCP de sbx, `mcp/mcp.log` dans son répertoire d'état. `github-mcp: no token` dans ce journal signifie que le script n'a trouvé aucun jeton : vérifiez l'entrée du trousseau avec `security find-generic-password -s github-mcp`. L'endpoint distant `https://api.githubcopilot.com/mcp/` est une autre voie, mais seulement avec une OAuth App GitHub. GitHub ne propose pas l'enregistrement dynamique de client, donc en mode local `sbx mcp add` le refuse sans `--client-id`, même avec un en-tête `Authorization`.
++  enabled: true
++  permissions: ask
++  discoveryTimeout: 10s
++  servers: []        # la passerelle est ajoutée par mm quand MCP_GATEWAY_URL est défini
++```
--Nommez le dépôt dans vos demandes, par exemple « liste les issues ouvertes de k33g/mon-depot ». Un petit modèle à qui l'on dit seulement « mon organisation » invente un propriétaire et un dépôt, et chaque appel revient en `Not Found`.
++Déclarez le serveur sur l'hôte (`sbx mcp add <nom> --command <script>`), puis créez un **nouveau** sandbox qui l'a dans son ensemble fixe — `--static-mcp <nom>` est une option de `sbx` et se place avant `--`. Si aucun outil `sbx-gateway_*` n'apparaît dans la bannière, `sbx mcp inspect <nom>` et le fichier `mcp/mcp.log` de sbx disent pourquoi.
  ## Variantes
--- **Une autre configuration pour une session d'éditeur.** Ajoutez `"-e", "AGENT_CONFIG=agent.lsp.yaml"` avant le nom du sandbox dans `"args"` ; `sbx exec -e` remplace la valeur intégrée pour cette exécution seulement.
++- **Skills.** `skillsDir` est relatif au dossier où tourne `mm` — l'espace de travail — comme sur l'hôte.
--- **Skills.** `skillsDir` est relatif au répertoire où `mm` tourne, c'est-à-dire l'espace de travail dans les deux kits — la même règle que sur l'hôte.
++- **Lire les journaux.** En mode fenêtre, ils sont à l'écran ; en ACP, ils vont sur stderr, que Zed affiche sous `dev: open acp logs`.
--- **Docker dans le sandbox.** Construisez le template sur le shell Docker-in-Docker : `SHELL_TEMPLATE=docker/sandbox-templates:shell-docker ./docker-sbx/build.sh`.
++- **Un shell dans le sandbox.** `sbx exec -it mm-acp bash`.
--- **Lire les logs.** En mode fenêtre ils sont à l'écran ; en ACP ils vont sur stderr, que Zed montre sous `dev: open acp logs`.
++- **Supprimer un sandbox.** `sbx rm mm-acp`. Le dossier du projet est un montage et n'est pas touché.
--- **Supprimer un sandbox.** `sbx rm mm-acp`. Le répertoire du projet est un montage et n'est pas touché.
  ## Voir aussi
--- Le format suivi par ces deux fichiers : la spécification des kits de Docker Sandboxes (`schemaVersion: "2"`), livrée avec les sources de `sbx`.
++- Le format des kits : [spécification v3](https://github.com/docker/sandbox-kit-spec).
--- Les mêmes kits pour la spécification de kit v3 : [Faire tourner mini-me avec les kits sandbox v3](run-with-sandbox-kits-v3.md).
  - Ce que `mm -acp` expose à l'éditeur : [référence ACP](../reference/acp.md).
--- Les drapeaux et variables d'environnement que `mm` lit : [référence de la ligne de commande](../reference/cli.md).
++- Les options et variables d'environnement que lit `mm` : [référence de la ligne de commande](../reference/cli.md).

modified docs/fr/how-to/run-with-llmman.md +2 -2 Viewed

@@ -19,8 +19,8 @@ Ce guide montre comment brancher `mm` sur [llmman](https://github.com/llmmanorg/
19	19	3. Lancez la configuration de démo depuis son dossier (son `skillsDir` vaut `../skills`) :
20	20
21	21	```bash
22		- cd demo-llmman
23		- ../mm agent.llmman.yaml
	22	+ cd demos/llmman
	23	+ ../../mm agent.llmman.yaml
24	24	```
25	25
26	26	4. Vérifiez la bannière. `provider: llmman` confirme le fournisseur. `ctx: 262144 (/api/ps)` signifie que le modèle était déjà chargé et que `mm` a lu la fenêtre avec laquelle il est servi ; `ctx: unknown` signifie qu'il ne l'était pas encore — `mm` redemande avant la question suivante et affiche `ctx: … (/api/ps)` dès qu'il la connaît.

 . Lancez la configuration de démo depuis son dossier (son `skillsDir` vaut `../skills`) :
     ```bash
--   cd demo-llmman
++   cd demos/llmman
--   ../mm agent.llmman.yaml
++   ../../mm agent.llmman.yaml
     ```
 . Vérifiez la bannière. `provider: llmman` confirme le fournisseur. `ctx: 262144 (/api/ps)` signifie que le modèle était déjà chargé et que `mm` a lu la fenêtre avec laquelle il est servi ; `ctx: unknown` signifie qu'il ne l'était pas encore — `mm` redemande avant la question suivante et affiche `ctx: … (/api/ps)` dès qu'il la connaît.

modified docs/fr/how-to/run-with-ollama.md +2 -2 Viewed

@@ -15,8 +15,8 @@ Ce guide montre comment brancher `mm` sur [Ollama](https://ollama.com) via son p
15	15	3. Lancez la configuration de démo depuis son dossier (son `skillsDir` vaut `../skills`) :
16	16
17	17	```bash
18		- cd demo-ollama
19		- ../mm agent.ollama.yaml
	18	+ cd demos/ollama
	19	+ ../../mm agent.ollama.yaml
20	20	```
21	21
22	22	4. Vérifiez la bannière. `provider: ollama` confirme le fournisseur. `ctx: 32768 (/api/ps)` signifie que le modèle était déjà chargé et que `mm` a lu la fenêtre avec laquelle il est servi ; `ctx: unknown` signifie qu'il ne l'était pas encore — `mm` redemande avant la question suivante.

 . Lancez la configuration de démo depuis son dossier (son `skillsDir` vaut `../skills`) :
     ```bash
--   cd demo-ollama
++   cd demos/ollama
--   ../mm agent.ollama.yaml
++   ../../mm agent.ollama.yaml
     ```
 . Vérifiez la bannière. `provider: ollama` confirme le fournisseur. `ctx: 32768 (/api/ps)` signifie que le modèle était déjà chargé et que `mm` a lu la fenêtre avec laquelle il est servi ; `ctx: unknown` signifie qu'il ne l'était pas encore — `mm` redemande avant la question suivante.

deleted docs/fr/how-to/run-with-sandbox-kits-v3.md +0 -111 Viewed

deleted file mode 100644
@@ -1,111 +0,0 @@
1		-# Faire tourner mini-me avec les kits sandbox v3
2		-
3		-Ce guide montre comment exécuter `mm` dans un [Docker Sandbox](https://docs.docker.com/ai/sandboxes/) avec les kits écrits pour la [spécification de kit v3](https://github.com/docker/sandbox-kit-spec), sous [`docker-sbx-v3/`](../../../docker-sbx-v3/README.md). Ils font le même travail que les kits v2 de [Faire tourner mini-me dans un Docker Sandbox](run-in-a-docker-sandbox.md) — le mode fenêtre avec `mm-tui`, un éditeur avec `mm-acp` — et les kits v2 continuent de fonctionner à côté. Il suppose Docker Desktop avec la commande `sbx`, et un serveur de modèles (Docker Model Runner ou llama-server) qui tourne sur votre machine.
4		-
5		-> État. Les kits v3 se construisent avec le frontend `docker/sandbox-kit:3` et passent le contrôle de conformité de la spécification (`kit-tck validate`), mais ils n'ont pas encore été lancés avec `sbx`, et ne sont pas encore publiés. La spécification de kit elle-même est encore marquée expérimentale.
6		-
7		-\| Élément \| Ce que c'est \|
8		-\|---\|---\|
9		-\| `template/Dockerfile` \| L'image template, `k33g/mm-sandbox:<version>` — la même image qu'en v2. \|
10		-\| `kits/mm-tui/mm-tui.yaml` + `mm-tui.dockerfile` \| Le kit du mode fenêtre : un descripteur (les déclarations) et un Dockerfile (le contenu : `FROM` le template, `ENTRYPOINT ["mm-tui"]`). \|
11		-\| `kits/mm-acp/mm-acp.yaml` + `mm-acp.dockerfile` \| Le kit pour un éditeur, même forme, `ENTRYPOINT ["mm-acp-info"]`. \|
12		-\| `build.sh`, `sync-kits.sh` \| Construisent le template, et alignent les kits dessus. \|
13		-\| `check-kits.sh` \| Construit les kits en local et les vérifie, sans `sbx` et sans push. \|
14		-\| `push-kits.sh`, `publish.sh` \| Publient les kits (et le template) sur Docker Hub avec `docker buildx`. \|
15		-
16		-## Avant de commencer : deux différences avec la v2
17		-
18		-- L'image template doit être sur un registre. Un kit v3 est construit au-dessus du template. Quand vous lancez un kit depuis son dossier, `sbx` le construit dans son sandbox de build, dont le moteur Docker télécharge le template depuis le registre. Une image présente seulement dans votre stockage local ne suffit pas, et `--pull never` ou `sbx template load` n'y changent rien. `k33g/mm-sandbox:0.2.1` est déjà sur Docker Hub ; pour une autre version, poussez-la d'abord (étape 1).
19		-- L'espace de travail est `/home/agent/workspace`. L'image de base du template déclare ce répertoire de travail, et un workload d'agent v3 (`sbx@1`) y est monté. Donnez à `config` un chemin relatif à l'espace de travail (`agent.dmr.yaml`, `demo/agent.dmr.yaml`) ; un chemin absolu de votre Mac (`/Users/…`) n'existe pas dans le sandbox.
20		-
21		-## Étapes
22		-
23		-### 1. Rendre le template disponible
24		-
25		-Pour la version de `release.env` (`v0.2.1`), rien à faire : `k33g/mm-sandbox:0.2.1` est sur Docker Hub. Pour un `mm` en cours de travail, construisez et poussez le template depuis la racine du dépôt :
26		-
27		-```bash
28		-PUSH=1 ./docker-sbx-v3/build.sh v0.2.2
29		-```
30		-
31		-Le script construit `k33g/mm-sandbox:0.2.2` pour linux/amd64 et linux/arm64, la pousse, puis réécrit les valeurs par défaut `image` et `tag` des kits pour qu'ils nomment cette image. `IMAGE_OWNER=<compte>` la pousse sous votre propre compte.
32		-
33		-### 2. Vérifier les kits (facultatif)
34		-
35		-```bash
36		-./docker-sbx-v3/check-kits.sh
37		-```
38		-
39		-Chaque kit est construit avec `docker buildx build -f <kit>.yaml`, qui passe par le frontend des kits : il refuse une clé inconnue ou un argument qui ne respecte pas son motif. Le résultat va dans `tmp/kits-v3/<kit>/`. Avec [`kit-tck`](https://github.com/docker/sandbox-kit-spec) dans le `PATH` (`go build ./cmd/kit-tck` dans un clone de la spécification), le script lance aussi le contrôle de conformité et affiche `✓ conforms`.
40		-
41		-### 3. Mode fenêtre dans le terminal (kit `mm-tui`)
42		-
43		-Depuis le projet sur lequel `mm` doit travailler :
44		-
45		-```bash
46		-cd /chemin/de/votre/projet
47		-sbx run /chemin/de/mini-me/docker-sbx-v3/kits/mm-tui . -- agent.dmr.yaml
48		-```
49		-
50		-Le premier lancement construit le kit (quelques secondes : une couche au-dessus du template), crée le sandbox, monte le répertoire courant et lance `mm -tui agent.dmr.yaml`. Ce qui suit `--` est la ligne de commande de `mm`. Sans rien après `--`, `mm` lit l'argument `config` du kit, puis `./agent.yaml`, puis ses valeurs par défaut :
51		-
52		-```bash
53		-sbx run /chemin/de/mini-me/docker-sbx-v3/kits/mm-tui . --kit-arg config=agent.dmr.yaml
54		-```
55		-
56		-### 4. Depuis un éditeur (kit `mm-acp`)
57		-
58		-1. Créez le sandbox une fois, depuis le projet que l'éditeur ouvrira :
59		-
60		- ```bash
61		- cd /chemin/de/votre/projet
62		- sbx create --name mm-acp /chemin/de/mini-me/docker-sbx-v3/kits/mm-acp . \
63		- --kit-arg config=agent.dmr.yaml
64		- ```
65		-
66		-2. Déclarez-le dans l'éditeur. Dans le `settings.json` de Zed :
67		-
68		- ```json
69		- {
70		- "agent_servers": {
71		- "mini-me (sandbox)": {
72		- "type": "custom",
73		- "command": "sbx",
74		- "args": ["exec", "-i", "mm-acp", "mm", "-acp"]
75		- }
76		- }
77		- }
78		- ```
79		-
80		-3. Ouvrez le panneau d'agent et choisissez mini-me (sandbox). Comme en v2, l'éditeur passe par `sbx exec -i`, parce qu'un client ACP a besoin de stdin et stdout bruts et que `sbx run` alloue toujours un terminal. `sbx run --name mm-acp` affiche ce branchement et ouvre un shell.
81		-
82		-### 5. Une fois les kits publiés
83		-
84		-Après `./docker-sbx-v3/publish.sh` (ou `push-kits.sh`) pour une version, les kits sont des images ordinaires sur Docker Hub, et aucun dossier n'est nécessaire :
85		-
86		-```bash
87		-sbx run k33g/sbx-kit-mm-tui:0.2.1 . -- agent.dmr.yaml
88		-sbx create --name mm-acp k33g/sbx-kit-mm-acp:0.2.1 . --kit-arg config=agent.dmr.yaml
89		-```
90		-
91		-Les dépôts sont `sbx-kit-<kit>`, pas les `k33g/mm-tui` / `k33g/mm-acp` de la v2 : publier un kit v3 ne remplace jamais un kit v2.
92		-
93		-## Arguments des kits
94		-
95		-\| `--kit-arg` \| Défaut \| Quand il s'applique \| Effet \|
96		-\|---\|---\|---\|---\|
97		-\| `config=<chemin>` \| vide \| à `sbx run` / `sbx create` \| L'`AGENT_CONFIG` de `mm` : relatif à l'espace de travail, ou absolu dans le sandbox. Vide : `./agent.yaml`, puis les valeurs par défaut. \|
98		-\| `tag=<version>` \| la version de mm (`0.2.1`) \| à la construction du kit \| Le tag du template sur lequel le kit est construit ; c'est aussi la version du kit. Sans `v`. \|
99		-\| `image=<dépôt>` \| `k33g/mm-sandbox` \| à la construction du kit \| Le dépôt du template sur lequel le kit est construit. \|
100		-
101		-`tag` et `image` sont des arguments de construction : ils sont figés dans un kit publié, qui nomme toujours l'image sur laquelle il a été construit. Pour une autre version de `mm`, prenez le kit de cette version.
102		-
103		-## Le serveur de modèles reste sur l'hôte
104		-
105		-Rien ne change par rapport à la v2 : Docker Model Runner et llama-server tournent sur votre machine et sont joints par `host.docker.internal`. `agent.dmr.yaml` s'y replie déjà ; pour llama-server, voir [le guide v2](run-in-a-docker-sandbox.md#le-serveur-de-modèles-reste-sur-lhôte). Les deux kits autorisent les ports 12434 et 8080 de l'hôte ; pour un autre port, `sbx policy allow network host.docker.internal:<port>`.
106		-
107		-## Voir aussi
108		-
109		-- Ce qui change par rapport aux kits v2, champ par champ : [`docker-sbx-v3/README.md`](../../../docker-sbx-v3/README.md).
110		-- Les kits v2, la passerelle MCP et les variantes pour éditeur : [Faire tourner mini-me dans un Docker Sandbox](run-in-a-docker-sandbox.md).
111		-- Le format des kits : [spécification v3](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md).

--# Faire tourner mini-me avec les kits sandbox v3
--
--Ce guide montre comment exécuter `mm` dans un [Docker Sandbox](https://docs.docker.com/ai/sandboxes/) avec les kits écrits pour la [spécification de kit v3](https://github.com/docker/sandbox-kit-spec), sous [`docker-sbx-v3/`](../../../docker-sbx-v3/README.md). Ils font le même travail que les kits v2 de [Faire tourner mini-me dans un Docker Sandbox](run-in-a-docker-sandbox.md) — le mode fenêtre avec `mm-tui`, un éditeur avec `mm-acp` — et les kits v2 continuent de fonctionner à côté. Il suppose Docker Desktop avec la commande `sbx`, et un serveur de modèles (Docker Model Runner ou llama-server) qui tourne sur votre machine.
--
--> **État.** Les kits v3 se construisent avec le frontend `docker/sandbox-kit:3` et passent le contrôle de conformité de la spécification (`kit-tck validate`), mais ils n'ont pas encore été lancés avec `sbx`, et ne sont pas encore publiés. La spécification de kit elle-même est encore marquée expérimentale.
--
--| Élément | Ce que c'est |
--|---|---|
--| `template/Dockerfile` | L'image **template**, `k33g/mm-sandbox:<version>` — la même image qu'en v2. |
--| `kits/mm-tui/mm-tui.yaml` + `mm-tui.dockerfile` | Le kit du mode fenêtre : un descripteur (les déclarations) et un Dockerfile (le contenu : `FROM` le template, `ENTRYPOINT ["mm-tui"]`). |
--| `kits/mm-acp/mm-acp.yaml` + `mm-acp.dockerfile` | Le kit pour un éditeur, même forme, `ENTRYPOINT ["mm-acp-info"]`. |
--| `build.sh`, `sync-kits.sh` | Construisent le template, et alignent les kits dessus. |
--| `check-kits.sh` | Construit les kits en local et les vérifie, sans `sbx` et sans push. |
--| `push-kits.sh`, `publish.sh` | Publient les kits (et le template) sur Docker Hub avec `docker buildx`. |
--
--## Avant de commencer : deux différences avec la v2
--
--- **L'image template doit être sur un registre.** Un kit v3 est *construit* au-dessus du template. Quand vous lancez un kit depuis son dossier, `sbx` le construit dans son sandbox de build, dont le moteur Docker télécharge le template depuis le registre. Une image présente seulement dans votre stockage local ne suffit pas, et `--pull never` ou `sbx template load` n'y changent rien. `k33g/mm-sandbox:0.2.1` est déjà sur Docker Hub ; pour une autre version, poussez-la d'abord (étape 1).
--- **L'espace de travail est `/home/agent/workspace`.** L'image de base du template déclare ce répertoire de travail, et un workload d'agent v3 (`sbx@1`) y est monté. Donnez à `config` un chemin relatif à l'espace de travail (`agent.dmr.yaml`, `demo/agent.dmr.yaml`) ; un chemin absolu de votre Mac (`/Users/…`) n'existe pas dans le sandbox.
--
--## Étapes
--
--### 1. Rendre le template disponible
--
--Pour la version de `release.env` (`v0.2.1`), rien à faire : `k33g/mm-sandbox:0.2.1` est sur Docker Hub. Pour un `mm` en cours de travail, construisez et poussez le template depuis la racine du dépôt :
--
--```bash
--PUSH=1 ./docker-sbx-v3/build.sh v0.2.2
--```
--
--Le script construit `k33g/mm-sandbox:0.2.2` pour linux/amd64 et linux/arm64, la pousse, puis réécrit les valeurs par défaut `image` et `tag` des kits pour qu'ils nomment cette image. `IMAGE_OWNER=<compte>` la pousse sous votre propre compte.
--
--### 2. Vérifier les kits (facultatif)
--
--```bash
--./docker-sbx-v3/check-kits.sh
--```
--
--Chaque kit est construit avec `docker buildx build -f <kit>.yaml`, qui passe par le frontend des kits : il refuse une clé inconnue ou un argument qui ne respecte pas son motif. Le résultat va dans `tmp/kits-v3/<kit>/`. Avec [`kit-tck`](https://github.com/docker/sandbox-kit-spec) dans le `PATH` (`go build ./cmd/kit-tck` dans un clone de la spécification), le script lance aussi le contrôle de conformité et affiche `✓ conforms`.
--
--### 3. Mode fenêtre dans le terminal (kit `mm-tui`)
--
--Depuis le projet sur lequel `mm` doit travailler :
--
--```bash
--cd /chemin/de/votre/projet
--sbx run /chemin/de/mini-me/docker-sbx-v3/kits/mm-tui . -- agent.dmr.yaml
--```
--
--Le premier lancement construit le kit (quelques secondes : une couche au-dessus du template), crée le sandbox, monte le répertoire courant et lance `mm -tui agent.dmr.yaml`. Ce qui suit `--` est la ligne de commande de `mm`. Sans rien après `--`, `mm` lit l'argument `config` du kit, puis `./agent.yaml`, puis ses valeurs par défaut :
--
--```bash
--sbx run /chemin/de/mini-me/docker-sbx-v3/kits/mm-tui . --kit-arg config=agent.dmr.yaml
--```
--
--### 4. Depuis un éditeur (kit `mm-acp`)
--
--1. Créez le sandbox une fois, depuis le projet que l'éditeur ouvrira :
--
--   ```bash
--   cd /chemin/de/votre/projet
--   sbx create --name mm-acp /chemin/de/mini-me/docker-sbx-v3/kits/mm-acp . \
--       --kit-arg config=agent.dmr.yaml
--   ```
--
--2. Déclarez-le dans l'éditeur. Dans le `settings.json` de Zed :
--
--   ```json
--   {
--     "agent_servers": {
--       "mini-me (sandbox)": {
--         "type": "custom",
--         "command": "sbx",
--         "args": ["exec", "-i", "mm-acp", "mm", "-acp"]
--       }
--     }
--   }
--   ```
--
--3. Ouvrez le panneau d'agent et choisissez **mini-me (sandbox)**. Comme en v2, l'éditeur passe par `sbx exec -i`, parce qu'un client ACP a besoin de stdin et stdout bruts et que `sbx run` alloue toujours un terminal. `sbx run --name mm-acp` affiche ce branchement et ouvre un shell.
--
--### 5. Une fois les kits publiés
--
--Après `./docker-sbx-v3/publish.sh` (ou `push-kits.sh`) pour une version, les kits sont des images ordinaires sur Docker Hub, et aucun dossier n'est nécessaire :
--
--```bash
--sbx run k33g/sbx-kit-mm-tui:0.2.1 . -- agent.dmr.yaml
--sbx create --name mm-acp k33g/sbx-kit-mm-acp:0.2.1 . --kit-arg config=agent.dmr.yaml
--```
--
--Les dépôts sont `sbx-kit-<kit>`, pas les `k33g/mm-tui` / `k33g/mm-acp` de la v2 : publier un kit v3 ne remplace jamais un kit v2.
--
--## Arguments des kits
--
--| `--kit-arg` | Défaut | Quand il s'applique | Effet |
--|---|---|---|---|
--| `config=<chemin>` | vide | à `sbx run` / `sbx create` | L'`AGENT_CONFIG` de `mm` : relatif à l'espace de travail, ou absolu dans le sandbox. Vide : `./agent.yaml`, puis les valeurs par défaut. |
--| `tag=<version>` | la version de mm (`0.2.1`) | à la construction du kit | Le tag du template sur lequel le kit est construit ; c'est aussi la version du kit. Sans `v`. |
--| `image=<dépôt>` | `k33g/mm-sandbox` | à la construction du kit | Le dépôt du template sur lequel le kit est construit. |
--
--`tag` et `image` sont des arguments de construction : ils sont figés dans un kit publié, qui nomme toujours l'image sur laquelle il a été construit. Pour une autre version de `mm`, prenez le kit de cette version.
--
--## Le serveur de modèles reste sur l'hôte
--
--Rien ne change par rapport à la v2 : Docker Model Runner et llama-server tournent sur votre machine et sont joints par `host.docker.internal`. `agent.dmr.yaml` s'y replie déjà ; pour llama-server, voir [le guide v2](run-in-a-docker-sandbox.md#le-serveur-de-modèles-reste-sur-lhôte). Les deux kits autorisent les ports 12434 et 8080 de l'hôte ; pour un autre port, `sbx policy allow network host.docker.internal:<port>`.
--
--## Voir aussi
--
--- Ce qui change par rapport aux kits v2, champ par champ : [`docker-sbx-v3/README.md`](../../../docker-sbx-v3/README.md).
--- Les kits v2, la passerelle MCP et les variantes pour éditeur : [Faire tourner mini-me dans un Docker Sandbox](run-in-a-docker-sandbox.md).
--- Le format des kits : [spécification v3](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md).

deleted mini-mes/riker/go.mod +0 -3 Viewed

deleted file mode 100644
@@ -1,3 +0,0 @@
1		-module hello-world-json
2		-
3		-go 1.27

--module hello-world-json
--
--go 1.27

deleted mini-mes/riker/handlers.go +0 -28 Viewed

deleted file mode 100644
@@ -1,28 +0,0 @@
1		-package main
2		-
3		-import (
4		- "encoding/json"
5		- "net/http"
6		-)
7		-
8		-// helloMessage is the value returned by the /hello endpoint.
9		-const helloMessage = "Hello World 🌍👋"
10		-
11		-// newRouter wires the HTTP routes to their handlers.
12		-func newRouter() http.Handler {
13		- mux := http.NewServeMux()
14		- mux.HandleFunc("/hello", helloHandler)
15		- return mux
16		-}
17		-
18		-// helloHandler serves GET /hello.
19		-func helloHandler(w http.ResponseWriter, r *http.Request) {
20		- if r.Method != http.MethodGet {
21		- http.Error(w, http.StatusText(http.StatusMethodNotAllowed), http.StatusMethodNotAllowed)
22		- return
23		- }
24		-
25		- w.Header().Set("Content-Type", "application/json")
26		- w.WriteHeader(http.StatusOK)
27		- json.NewEncoder(w).Encode(map[string]string{"message": helloMessage})
28		-}

--package main
--
--import (
--	"encoding/json"
--	"net/http"
--)
--
--// helloMessage is the value returned by the /hello endpoint.
--const helloMessage = "Hello World 🌍👋"
--
--// newRouter wires the HTTP routes to their handlers.
--func newRouter() http.Handler {
--	mux := http.NewServeMux()
--	mux.HandleFunc("/hello", helloHandler)
--	return mux
--}
--
--// helloHandler serves GET /hello.
--func helloHandler(w http.ResponseWriter, r *http.Request) {
--	if r.Method != http.MethodGet {
--		http.Error(w, http.StatusText(http.StatusMethodNotAllowed), http.StatusMethodNotAllowed)
--		return
--	}
--
--	w.Header().Set("Content-Type", "application/json")
--	w.WriteHeader(http.StatusOK)
--	json.NewEncoder(w).Encode(map[string]string{"message": helloMessage})
--}

deleted mini-mes/riker/handlers_test.go +0 -55 Viewed

deleted file mode 100644
@@ -1,55 +0,0 @@
1		-package main
2		-
3		-import (
4		- "encoding/json"
5		- "net/http"
6		- "net/http/httptest"
7		- "testing"
8		-)
9		-
10		-// A1: GET /hello returns 200, application/json and the expected body.
11		-func TestHelloGet(t *testing.T) {
12		- req := httptest.NewRequest(http.MethodGet, "/hello", nil)
13		- rec := httptest.NewRecorder()
14		- newRouter().ServeHTTP(rec, req)
15		-
16		- if rec.Code != http.StatusOK {
17		- t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
18		- }
19		- if ct := rec.Header().Get("Content-Type"); ct != "application/json" {
20		- t.Fatalf("Content-Type = %q, want %q", ct, "application/json")
21		- }
22		-
23		- var body map[string]string
24		- if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
25		- t.Fatalf("body is not valid JSON: %v", err)
26		- }
27		- if got, ok := body["message"]; !ok \|\| got != helloMessage {
28		- t.Fatalf("message = %q (present=%v), want %q", got, ok, helloMessage)
29		- }
30		- if len(body) != 1 {
31		- t.Fatalf("body has %d keys, want 1: %v", len(body), body)
32		- }
33		-}
34		-
35		-// A2: POST /hello returns 405.
36		-func TestHelloMethodNotAllowed(t *testing.T) {
37		- req := httptest.NewRequest(http.MethodPost, "/hello", nil)
38		- rec := httptest.NewRecorder()
39		- newRouter().ServeHTTP(rec, req)
40		-
41		- if rec.Code != http.StatusMethodNotAllowed {
42		- t.Fatalf("status = %d, want %d", rec.Code, http.StatusMethodNotAllowed)
43		- }
44		-}
45		-
46		-// A3: an undefined route returns 404.
47		-func TestUnknownRoute(t *testing.T) {
48		- req := httptest.NewRequest(http.MethodGet, "/unknown", nil)
49		- rec := httptest.NewRecorder()
50		- newRouter().ServeHTTP(rec, req)
51		-
52		- if rec.Code != http.StatusNotFound {
53		- t.Fatalf("status = %d, want %d", rec.Code, http.StatusNotFound)
54		- }
55		-}

--package main
--
--import (
--	"encoding/json"
--	"net/http"
--	"net/http/httptest"
--	"testing"
--)
--
--// A1: GET /hello returns 200, application/json and the expected body.
--func TestHelloGet(t *testing.T) {
--	req := httptest.NewRequest(http.MethodGet, "/hello", nil)
--	rec := httptest.NewRecorder()
--	newRouter().ServeHTTP(rec, req)
--
--	if rec.Code != http.StatusOK {
--		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
--	}
--	if ct := rec.Header().Get("Content-Type"); ct != "application/json" {
--		t.Fatalf("Content-Type = %q, want %q", ct, "application/json")
--	}
--
--	var body map[string]string
--	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
--		t.Fatalf("body is not valid JSON: %v", err)
--	}
--	if got, ok := body["message"]; !ok || got != helloMessage {
--		t.Fatalf("message = %q (present=%v), want %q", got, ok, helloMessage)
--	}
--	if len(body) != 1 {
--		t.Fatalf("body has %d keys, want 1: %v", len(body), body)
--	}
--}
--
--// A2: POST /hello returns 405.
--func TestHelloMethodNotAllowed(t *testing.T) {
--	req := httptest.NewRequest(http.MethodPost, "/hello", nil)
--	rec := httptest.NewRecorder()
--	newRouter().ServeHTTP(rec, req)
--
--	if rec.Code != http.StatusMethodNotAllowed {
--		t.Fatalf("status = %d, want %d", rec.Code, http.StatusMethodNotAllowed)
--	}
--}
--
--// A3: an undefined route returns 404.
--func TestUnknownRoute(t *testing.T) {
--	req := httptest.NewRequest(http.MethodGet, "/unknown", nil)
--	rec := httptest.NewRecorder()
--	newRouter().ServeHTTP(rec, req)
--
--	if rec.Code != http.StatusNotFound {
--		t.Fatalf("status = %d, want %d", rec.Code, http.StatusNotFound)
--	}
--}

deleted mini-mes/riker/main.go +0 -30 Viewed

deleted file mode 100644
@@ -1,30 +0,0 @@
1		-package main
2		-
3		-import (
4		- "log"
5		- "net/http"
6		- "os"
7		- "strconv"
8		-)
9		-
10		-// defaultPort is the TCP port the service listens on when PORT is unset.
11		-const defaultPort = 7070
12		-
13		-func main() {
14		- addr := ":" + strconv.Itoa(resolvePort())
15		- log.Printf("listening on %s", addr)
16		- if err := http.ListenAndServe(addr, newRouter()); err != nil {
17		- log.Fatal(err)
18		- }
19		-}
20		-
21		-// resolvePort returns the port to listen on: the PORT environment variable
22		-// when set to a valid integer, otherwise defaultPort.
23		-func resolvePort() int {
24		- if p := os.Getenv("PORT"); p != "" {
25		- if n, err := strconv.Atoi(p); err == nil {
26		- return n
27		- }
28		- }
29		- return defaultPort
30		-}

--package main
--
--import (
--	"log"
--	"net/http"
--	"os"
--	"strconv"
--)
--
--// defaultPort is the TCP port the service listens on when PORT is unset.
--const defaultPort = 7070
--
--func main() {
--	addr := ":" + strconv.Itoa(resolvePort())
--	log.Printf("listening on %s", addr)
--	if err := http.ListenAndServe(addr, newRouter()); err != nil {
--		log.Fatal(err)
--	}
--}
--
--// resolvePort returns the port to listen on: the PORT environment variable
--// when set to a valid integer, otherwise defaultPort.
--func resolvePort() int {
--	if p := os.Getenv("PORT"); p != "" {
--		if n, err := strconv.Atoi(p); err == nil {
--			return n
--		}
--	}
--	return defaultPort
--}

deleted mini-mes/riker/main_test.go +0 -29 Viewed

deleted file mode 100644
@@ -1,29 +0,0 @@
1		-package main
2		-
3		-import (
4		- "testing"
5		-)
6		-
7		-// R1: without a PORT environment variable, the port is the new default (7070).
8		-func TestResolvePortDefault(t *testing.T) {
9		- t.Setenv("PORT", "")
10		- if got := resolvePort(); got != 7070 {
11		- t.Fatalf("resolvePort() = %d, want %d", got, 7070)
12		- }
13		-}
14		-
15		-// R2: when PORT is a valid integer it takes precedence over the default.
16		-func TestResolvePortEnvPrecedence(t *testing.T) {
17		- t.Setenv("PORT", "9090")
18		- if got := resolvePort(); got != 9090 {
19		- t.Fatalf("resolvePort() = %d, want %d", got, 9090)
20		- }
21		-}
22		-
23		-// Edge case: when PORT is not a valid integer, fall back to the default.
24		-func TestResolvePortInvalidEnv(t *testing.T) {
25		- t.Setenv("PORT", "not-a-number")
26		- if got := resolvePort(); got != 7070 {
27		- t.Fatalf("resolvePort() = %d, want %d", got, 7070)
28		- }
29		-}

--package main
--
--import (
--	"testing"
--)
--
--// R1: without a PORT environment variable, the port is the new default (7070).
--func TestResolvePortDefault(t *testing.T) {
--	t.Setenv("PORT", "")
--	if got := resolvePort(); got != 7070 {
--		t.Fatalf("resolvePort() = %d, want %d", got, 7070)
--	}
--}
--
--// R2: when PORT is a valid integer it takes precedence over the default.
--func TestResolvePortEnvPrecedence(t *testing.T) {
--	t.Setenv("PORT", "9090")
--	if got := resolvePort(); got != 9090 {
--		t.Fatalf("resolvePort() = %d, want %d", got, 9090)
--	}
--}
--
--// Edge case: when PORT is not a valid integer, fall back to the default.
--func TestResolvePortInvalidEnv(t *testing.T) {
--	t.Setenv("PORT", "not-a-number")
--	if got := resolvePort(); got != 7070 {
--		t.Fatalf("resolvePort() = %d, want %d", got, 7070)
--	}
--}

deleted mini-mes/riker/specs/change-port-7070.spec.md +0 -29 Viewed

deleted file mode 100644
@@ -1,29 +0,0 @@
1		-# Change Port to 7070
2		-
3		-## Goal
4		-Modify the Go web service to use port 7070 as its default listening port instead of 8080.
5		-
6		-## Context
7		-The service is currently implemented in `main.go` and uses a constant `defaultPort` set to `8080`. It also allows overriding the port via the `PORT` environment variable.
8		-
9		-## Requirements
10		-R1: Change the `defaultPort` constant from `8080` to `7070`.
11		-R2: Ensure the service still respects the `PORT` environment variable if it is provided.
12		-
13		-## Interfaces
14		-No changes to external interfaces (HTTP routes or types) are required, only the default listening address.
15		-
16		-## Edge cases and errors
17		-- If the `PORT` environment variable is provided, it should take precedence over the new default (7070).
18		-- If the `PORT` environment variable is not a valid integer, the service should fallback to the new default (7070).
19		-
20		-## Acceptance criteria
21		-A1: Given the service is started without a `PORT` environment variable, when it is running, then it should be listening on port 7070.
22		-A2: Given the service is started with `PORT=9090`, when it is running, then it should be listening on port 9090.
23		-
24		-## Out of scope
25		-- Changing the router or any HTTP handlers.
26		-- Adding support for other protocols.
27		-
28		-## Open questions
29		-None.

--# Change Port to 7070
--
--## Goal
--Modify the Go web service to use port 7070 as its default listening port instead of 8080.
--
--## Context
--The service is currently implemented in `main.go` and uses a constant `defaultPort` set to `8080`. It also allows overriding the port via the `PORT` environment variable.
--
--## Requirements
--R1: Change the `defaultPort` constant from `8080` to `7070`.
--R2: Ensure the service still respects the `PORT` environment variable if it is provided.
--
--## Interfaces
--No changes to external interfaces (HTTP routes or types) are required, only the default listening address.
--
--## Edge cases and errors
--- If the `PORT` environment variable is provided, it should take precedence over the new default (7070).
--- If the `PORT` environment variable is not a valid integer, the service should fallback to the new default (7070).
--
--## Acceptance criteria
--A1: Given the service is started without a `PORT` environment variable, when it is running, then it should be listening on port 7070.
--A2: Given the service is started with `PORT=9090`, when it is running, then it should be listening on port 9090.
--
--## Out of scope
--- Changing the router or any HTTP handlers.
--- Adding support for other protocols.
--
--## Open questions
--None.

deleted mini-mes/riker/specs/hello-world-json.spec.md +0 -41 Viewed

deleted file mode 100644
@@ -1,41 +0,0 @@
1		-# Hello World JSON Web Service
2		-
3		-## Goal
4		-Create a minimal Go web service that serves a JSON response containing a "Hello World" message decorated with emojis.
5		-
6		-## Context
7		-This is a new project with no existing codebase.
8		-
9		-## Requirements
10		-1. The service must be written in Go.
11		-2. The service must listen on a TCP port (default 8080).
12		-3. The service must provide a single HTTP GET endpoint at `/hello`.
13		-4. The response for `/hello` must have an HTTP 200 OK status.
14		-5. The response body must be a valid JSON object.
15		-6. The JSON object must contain a single key `message` with the value "Hello World 🌍👋".
16		-7. The `Content-Type` header of the response must be `application/json`.
17		-
18		-## Interfaces
19		-### HTTP Routes
20		-- `GET /hello`
21		- - Response Body: `{"message": "Hello World 🌍👋"}`
22		- - Headers: `Content-Type: application/json`
23		-
24		-## Edge cases and errors
25		-1. Any HTTP method other than `GET` on `/hello` must return `405 Method Not Allowed`.
26		-2. Any request to an undefined route must return `404 Not Found`.
27		-
28		-## Acceptance criteria
29		-1. A1: Given the server is running, When I perform `curl -i http://localhost:8080/hello`, Then I receive a `200 OK` status and the body `{"message": "Hello World 🌍👋"}` with `Content-Type: application/json`.
30		-2. A2: Given the server is running, When I perform `curl -i -X POST http://localhost:8080/hello`, Then I receive a `405 Method Not Allowed` status.
31		-3. A3: Given the server is running, When I perform `curl -i http://localhost:8080/unknown`, Then I receive a `404 Not Found` status.
32		-
33		-## Out of scope
34		-- Adding more endpoints.
35		-- Using external web frameworks (e.g., Gin, Echo); use standard `net/http` unless otherwise requested.
36		-- Persistent storage or databases.
37		-- Dockerization or CI/CD pipelines.
38		-
39		-## Open questions
40		-- Which emojis to use? (Default: 🌍👋)
41		-- Which web framework to use? (Default: standard library `net/http`)

--# Hello World JSON Web Service
--
--## Goal
--Create a minimal Go web service that serves a JSON response containing a "Hello World" message decorated with emojis.
--
--## Context
--This is a new project with no existing codebase.
--
--## Requirements
--1. The service must be written in Go.
--2. The service must listen on a TCP port (default 8080).
--3. The service must provide a single HTTP GET endpoint at `/hello`.
--4. The response for `/hello` must have an HTTP 200 OK status.
--5. The response body must be a valid JSON object.
--6. The JSON object must contain a single key `message` with the value "Hello World 🌍👋".
--7. The `Content-Type` header of the response must be `application/json`.
--
--## Interfaces
--### HTTP Routes
--- `GET /hello`
--  - Response Body: `{"message": "Hello World 🌍👋"}`
--  - Headers: `Content-Type: application/json`
--
--## Edge cases and errors
--1. Any HTTP method other than `GET` on `/hello` must return `405 Method Not Allowed`.
--2. Any request to an undefined route must return `404 Not Found`.
--
--## Acceptance criteria
--1. A1: Given the server is running, When I perform `curl -i http://localhost:8080/hello`, Then I receive a `200 OK` status and the body `{"message": "Hello World 🌍👋"}` with `Content-Type: application/json`.
--2. A2: Given the server is running, When I perform `curl -i -X POST http://localhost:8080/hello`, Then I receive a `405 Method Not Allowed` status.
--3. A3: Given the server is running, When I perform `curl -i http://localhost:8080/unknown`, Then I receive a `404 Not Found` status.
--
--## Out of scope
--- Adding more endpoints.
--- Using external web frameworks (e.g., Gin, Echo); use standard `net/http` unless otherwise requested.
--- Persistent storage or databases.
--- Dockerization or CI/CD pipelines.
--
--## Open questions
--- Which emojis to use? (Default: 🌍👋)
--- Which web framework to use? (Default: standard library `net/http`)

modified sbx/README.md +23 -28 Viewed

@@ -1,28 +1,23 @@
1		-
2		-If the agent config file is name `agent.yaml` (default value), you don't need to specify the name of the config file.
3		-
4		-sbx run --name mm-0.3.0 ./kits/mini-me
5		-
6		-sbx run --name mm-0.3.0 ./kits/mini-me -- -tui -config agent.lucy.yaml
7		-
8		-sbx run --name mm-0.3.0 ./kits/mini-me --kit ./kits/go-toolchain --kit ./kits/cli-tools -- -tui -config agent.yaml
9		-
10		-
11		-## ACP
12		-sbx create --name mm-acp ./kits/mini-me . --kit ./kits/go-toolchain
13		-
14		-sbx exec -i mm-acp mm -acp -config agent.lucy.yaml
15		-
16		-
17		-##
18		-
19		-sbx run --name mm-0.3.0 ./kits/mini-me
20		-
21		-$ sbx run "git+https://git.rickub.com/bots-garden/mini-me.git#ref=<REVISION>&dir=sbx-kits/mini-me" \
22		- --kit "git+https://github.com/<ORG>/<REPO>.git#ref=<REVISION>&dir=sbx-kits/go-toolchain"
23		-
24		-
25		-https://rickub.com/bots-garden/mini-me/releases/v0.3.0
26		-
27		-$ git rev-parse HEAD # commit courant
28		-$ git rev-parse v1.0.0^{commit} # commit derrière un tag (annoté ou non)
		\ No newline at end of file
	1	+# Mini Me sbx kit
	2	+
	3	+You can find the kit on: https://rickub.com/bots-garden/mini-me-kit
	4	+
	5	+## Use the kit remotely
	6	+> Prerequisites
	7	+```bash
	8	+sbx settings set kit.allowedSources '["docker.io/","git.rickub.com/bots-garden/"]'
	9	+```
	10	+
	11	+```bash
	12	+RELEASE=v0.0.1
	13	+REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
	14	+sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me"
	15	+```
	16	+
	17	+```bash
	18	+RELEASE=v0.0.1
	19	+REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
	20	+sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" \
	21	+--kit ./kits/go-toolchain --kit ./kits/cli-tools \
	22	+-- -tui -config agent.lucy.yaml
	23	+```

--
--If the agent config file is name `agent.yaml` (default value), you don't need to specify the name of the config file.
--
--sbx run --name mm-0.3.0 ./kits/mini-me
--
--sbx run --name mm-0.3.0 ./kits/mini-me -- -tui -config agent.lucy.yaml
--
--sbx run --name mm-0.3.0 ./kits/mini-me --kit ./kits/go-toolchain --kit ./kits/cli-tools -- -tui -config agent.yaml
--
--
--## ACP
--sbx create --name mm-acp ./kits/mini-me . --kit ./kits/go-toolchain
--
--sbx exec -i mm-acp mm -acp -config agent.lucy.yaml
--
--
--##
--
--sbx run --name mm-0.3.0 ./kits/mini-me
--
--$ sbx run "git+https://git.rickub.com/bots-garden/mini-me.git#ref=<REVISION>&dir=sbx-kits/mini-me" \
--    --kit "git+https://github.com/<ORG>/<REPO>.git#ref=<REVISION>&dir=sbx-kits/go-toolchain"
--
--
--https://rickub.com/bots-garden/mini-me/releases/v0.3.0
--
--$ git rev-parse HEAD                    # commit courant
--$ git rev-parse v1.0.0^{commit}         # commit derrière un tag (annoté ou non)
 \ No newline at end of file
++# Mini Me sbx kit
++
++You can find the kit on: https://rickub.com/bots-garden/mini-me-kit
++
++## Use the kit remotely
++> Prerequisites
++```bash
++sbx settings set kit.allowedSources '["docker.io/","git.rickub.com/bots-garden/"]'
++```
++
++```bash
++RELEASE=v0.0.1
++REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
++sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me"
++```
++
++```bash
++RELEASE=v0.0.1
++REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
++sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" \
++--kit ./kits/go-toolchain --kit ./kits/cli-tools \
++-- -tui -config agent.lucy.yaml
++```

modified sbx/agent.lucy.yaml +1 -1 Viewed

@@ -76,7 +76,7 @@ maxOutput: 16000
76	76	maxTurns: 40
77	77
78	78	# Where the `read_skill` tool looks for its markdown procedures.
79		-# The path is relative to the CURRENT DIRECTORY: run the agent from demo-llmman/.
	79	+# The path is relative to the CURRENT DIRECTORY: run the agent from sbx/.
80	80	skillsDir: ../skills
81	81
82	82	# Persistent sessions, per project.

  maxTurns: 40
  # Where the `read_skill` tool looks for its markdown procedures.
--# The path is relative to the CURRENT DIRECTORY: run the agent from demo-llmman/.
++# The path is relative to the CURRENT DIRECTORY: run the agent from sbx/.
  skillsDir: ../skills
  # Persistent sessions, per project.

modified sbx/agent.yaml +1 -1 Viewed

@@ -76,7 +76,7 @@ maxOutput: 16000
76	76	maxTurns: 40
77	77
78	78	# Where the `read_skill` tool looks for its markdown procedures.
79		-# The path is relative to the CURRENT DIRECTORY: run the agent from demo-llmman/.
	79	+# The path is relative to the CURRENT DIRECTORY: run the agent from sbx/.
80	80	skillsDir: ../skills
81	81
82	82	# Persistent sessions, per project.

  maxTurns: 40
  # Where the `read_skill` tool looks for its markdown procedures.
--# The path is relative to the CURRENT DIRECTORY: run the agent from demo-llmman/.
++# The path is relative to the CURRENT DIRECTORY: run the agent from sbx/.
  skillsDir: ../skills
  # Persistent sessions, per project.

added sbx/kits/go-toolchain/go-context.md +6 -0 Viewed

new file mode 100644
@@ -0,0 +1,6 @@
	1	+## Go
	2	+
	3	+`go`, `gofmt` and `gopls` are installed (`/usr/local/go`). Run `go build ./...`
	4	+and `go test ./...` before reporting a task complete. Prefer `gopls` for
	5	+navigation and refactoring (definitions, references, rename) over text search.
	6	+Module downloads go through `proxy.golang.org`; other hosts may be blocked.
		\ No newline at end of file

++## Go
++
++`go`, `gofmt` and `gopls` are installed (`/usr/local/go`). Run `go build ./...`
++and `go test ./...` before reporting a task complete. Prefer `gopls` for
++navigation and refactoring (definitions, references, rename) over text search.
++Module downloads go through `proxy.golang.org`; other hosts may be blocked.
 \ No newline at end of file

deleted sbx/kits/mini-me/mini-me.dockerfile +0 -36 Viewed

deleted file mode 100644
@@ -1,36 +0,0 @@
1		-# syntax=docker/dockerfile:1
2		-#
3		-# Base: Docker's shell template = Ubuntu, non-root `agent` user (UID 1000),
4		-# bash, git, curl, CA certificates. No agent pre-installed.
5		-FROM docker/sandbox-templates:shell
6		-
7		-USER root
8		-
9		-# --- mm release v0.3.0 --------------------------------------------------------
10		-# rickub release assets are addressed by UUID, so the version cannot be derived
11		-# from a template URL: to bump, replace these four values (URLs + SHA-256 from
12		-# the release page).
13		-ARG TARGETARCH
14		-ARG MM_URL_AMD64=https://rickub.com/bots-garden/mini-me/release-assets/33d3bc3f-9195-487a-ab72-d55308f27e58
15		-ARG MM_SHA_AMD64=9743c634a53bfaf7dd817fbf61a27e8492464576d0223c920988025deea3732b
16		-ARG MM_URL_ARM64=https://rickub.com/bots-garden/mini-me/release-assets/75b8fe40-a4f5-41bf-8f8d-f70ac445acd4
17		-ARG MM_SHA_ARM64=5557dd60d31cafa76c8c35f0eb02b0cf4ca110f11d226cbd2f9d1e2e5c429dfc
18		-
19		-# A heredoc RUN does not stop at the first failing line by itself: the
20		-# script starts with `set -eu`, so a bad checksum fails the build.
21		-RUN <<EOF
22		-set -eu
23		-case "${TARGETARCH}" in
24		- amd64) url="${MM_URL_AMD64}"; sha="${MM_SHA_AMD64}" ;;
25		- arm64) url="${MM_URL_ARM64}"; sha="${MM_SHA_ARM64}" ;;
26		- *) echo "unsupported TARGETARCH: ${TARGETARCH}" >&2; exit 1 ;;
27		-esac
28		-curl -fsSL "${url}" -o /usr/local/bin/mm
29		-echo "${sha} /usr/local/bin/mm" \| sha256sum -c -
30		-chmod 0755 /usr/local/bin/mm
31		-EOF
32		-
33		-# Back to the sandbox user, then declare the launch command.
34		-USER agent
35		-ENTRYPOINT ["mm"]
36		-CMD ["-tui"]
		\ No newline at end of file

--# syntax=docker/dockerfile:1
--#
--# Base: Docker's shell template = Ubuntu, non-root `agent` user (UID 1000),
--# bash, git, curl, CA certificates. No agent pre-installed.
--FROM docker/sandbox-templates:shell
--
--USER root
--
--# --- mm release v0.3.0 --------------------------------------------------------
--# rickub release assets are addressed by UUID, so the version cannot be derived
--# from a template URL: to bump, replace these four values (URLs + SHA-256 from
--# the release page).
--ARG TARGETARCH
--ARG MM_URL_AMD64=https://rickub.com/bots-garden/mini-me/release-assets/33d3bc3f-9195-487a-ab72-d55308f27e58
--ARG MM_SHA_AMD64=9743c634a53bfaf7dd817fbf61a27e8492464576d0223c920988025deea3732b
--ARG MM_URL_ARM64=https://rickub.com/bots-garden/mini-me/release-assets/75b8fe40-a4f5-41bf-8f8d-f70ac445acd4
--ARG MM_SHA_ARM64=5557dd60d31cafa76c8c35f0eb02b0cf4ca110f11d226cbd2f9d1e2e5c429dfc
--
--# A heredoc RUN does not stop at the first failing line by itself: the
--# script starts with `set -eu`, so a bad checksum fails the build.
--RUN <<EOF
--set -eu
--case "${TARGETARCH}" in
--  amd64) url="${MM_URL_AMD64}"; sha="${MM_SHA_AMD64}" ;;
--  arm64) url="${MM_URL_ARM64}"; sha="${MM_SHA_ARM64}" ;;
--  *) echo "unsupported TARGETARCH: ${TARGETARCH}" >&2; exit 1 ;;
--esac
--curl -fsSL "${url}" -o /usr/local/bin/mm
--echo "${sha}  /usr/local/bin/mm" | sha256sum -c -
--chmod 0755 /usr/local/bin/mm
--EOF
--
--# Back to the sandbox user, then declare the launch command.
--USER agent
--ENTRYPOINT ["mm"]
--CMD ["-tui"]
 \ No newline at end of file

deleted sbx/kits/mini-me/mini-me.yaml +0 -35 Viewed

deleted file mode 100644
@@ -1,35 +0,0 @@
1		-# syntax=docker/sandbox-kit:3
2		-schemaVersion: "3"
3		-kind: workload
4		-displayName: Mini Me
5		-description: Mini Me (mm), a minimalist coding agent for local LLMs
6		-sourceUrl: https://rickub.com/bots-garden/mini-me
7		-
8		-# Lets other kits declare `requires: [mini-me]`.
9		-# Two kits that provide the same feature cannot be combined.
10		-provides: ["mini-me@0.3.0"]
11		-
12		-capabilities:
13		- # The workload is prepared for sbx to launch it (agent user, bash, ...).
14		- - type: com.docker.sandbox/sbx@1
15		-
16		- # Egress is deny-by-default. mm talks to a model server running on the host.
17		- # ASSUMPTION: Docker Model Runner on host.docker.internal:12434.
18		- # Check the port/host for your setup, then `sbx policy log` if it is blocked.
19		- - type: com.docker.sandbox/network-policy@1
20		- config:
21		- runtime:
22		- allow:
23		- - host.docker.internal:12434
24		-
25		- # # Instructions for the agent. The workload picks the file name,
26		- # # mixins (go-toolchain, cli-tools) append their own guidance to it.
27		- # - type: com.docker.sandbox/agent-context@1
28		- # config:
29		- # filename: AGENTS.md
30		- # contentFile: ./context.md
31		-
32		- # # `sbx run` (TTY) => `mm -tui`. Headless runs use ENTRYPOINT + CMD as-is.
33		- # - type: com.docker.sandbox/lifecycle@1
34		- # config:
35		- # interactive: ["-tui"]

--# syntax=docker/sandbox-kit:3
--schemaVersion: "3"
--kind: workload
--displayName: Mini Me
--description: Mini Me (mm), a minimalist coding agent for local LLMs
--sourceUrl: https://rickub.com/bots-garden/mini-me
--
--# Lets other kits declare `requires: [mini-me]`.
--# Two kits that provide the same feature cannot be combined.
--provides: ["mini-me@0.3.0"]
--
--capabilities:
--  # The workload is prepared for sbx to launch it (agent user, bash, ...).
--  - type: com.docker.sandbox/sbx@1
--
--  # Egress is deny-by-default. mm talks to a model server running on the host.
--  # ASSUMPTION: Docker Model Runner on host.docker.internal:12434.
--  # Check the port/host for your setup, then `sbx policy log` if it is blocked.
--  - type: com.docker.sandbox/network-policy@1
--    config:
--      runtime:
--        allow:
--          - host.docker.internal:12434
--
--  # # Instructions for the agent. The workload picks the file name,
--  # # mixins (go-toolchain, cli-tools) append their own guidance to it.
--  # - type: com.docker.sandbox/agent-context@1
--  #   config:
--  #     filename: AGENTS.md
--  #     contentFile: ./context.md
--
--  # # `sbx run` (TTY) => `mm -tui`. Headless runs use ENTRYPOINT + CMD as-is.
--  # - type: com.docker.sandbox/lifecycle@1
--  #   config:
--  #     interactive: ["-tui"]

🛟 Updated.Unverified