bots-garden/mini-me · 04a9101

deleted 01-release.tag.sh +0 -67 Viewed

deleted file mode 100755
@@ -1,67 +0,0 @@
1		-#!/bin/bash
2		-: <<'COMMENT'
3		-1. Update TAG and ABOUT in .release.env
4		-2. Run this script: ./01-release.tag.sh (commit, push, tag, push the tag)
5		-3. Run the local-ci-*.sh scripts in order: they build on this machine and
6		- publish. The tag push no longer starts a workflow (.github.bak).
7		-COMMENT
8		-
9		-# Without this, a failing step is ignored and the next one runs anyway. That is
10		-# not theoretical: `git tag` refusing a tag that already existed was skipped in
11		-# silence, and the `git push` below then pushed the OLD tag — so a release was
12		-# cut from a commit nobody meant, and 03 was left to notice.
13		-set -euo pipefail
14		-
15		-set -o allexport
16		-source .release.env
17		-set +o allexport
18		-
19		-echo "Generating release: ${TAG} ${ABOUT}"
20		-
21		-# tagExists reports whether TAG is already taken, here or on the remote. The
22		-# remote matters on its own: a tag deleted locally after a failed attempt still
23		-# exists there, and pushing a new one at a different commit is rejected.
24		-tagExists() {
25		- if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
26		- printf 'locally, on %s\n' "$(git rev-parse --short "${TAG}^{commit}")"
27		- return 0
28		- fi
29		- if ! remote="$(git ls-remote --tags origin "refs/tags/${TAG}" 2>/dev/null)"; then
30		- return 1 # the remote is unreachable; the push below will say so
31		- fi
32		- if [ -n "${remote}" ]; then
33		- # No commit is named here on purpose: for an annotated tag ls-remote
34		- # gives the tag object, not the commit, and printing that as if it were
35		- # the commit sends the reader looking for a SHA they will never find.
36		- printf 'on origin\n'
37		- return 0
38		- fi
39		- return 1
40		-}
41		-
42		-if where="$(tagExists)"; then
43		- echo "❌ ${TAG} already exists ${where}"
44		- echo "💡 Bump TAG in .release.env, or move the tag onto this commit:"
45		- echo " git tag -f -a ${TAG} -m \"${ABOUT}\""
46		- echo " git push --force origin ${TAG}"
47		- exit 1
48		-fi
49		-
50		-find . -name '.DS_Store' -type f -delete
51		-
52		-git add .
53		-
54		-# Nothing to commit is not a failure — the work may already be committed — but
55		-# under `set -e` a plain `git commit` would stop the release right here.
56		-if git diff --cached --quiet; then
57		- echo "Nothing to commit; releasing what is already on HEAD"
58		-else
59		- git commit -m "📦 ${ABOUT}"
60		-fi
61		-
62		-git push origin main
63		-
64		-# The tag goes on after the push, so a rejected push never leaves a tag behind
65		-# pointing at a commit the remote has never seen.
66		-git tag -a "${TAG}" -m "${ABOUT}"
67		-git push origin "${TAG}"

--#!/bin/bash
--: <<'COMMENT'
--1. Update TAG and ABOUT in .release.env
--2. Run this script: ./01-release.tag.sh   (commit, push, tag, push the tag)
--3. Run the local-ci-*.sh scripts in order: they build on this machine and
--   publish. The tag push no longer starts a workflow (.github.bak).
--COMMENT
--
--# Without this, a failing step is ignored and the next one runs anyway. That is
--# not theoretical: `git tag` refusing a tag that already existed was skipped in
--# silence, and the `git push` below then pushed the OLD tag — so a release was
--# cut from a commit nobody meant, and 03 was left to notice.
--set -euo pipefail
--
--set -o allexport
--source .release.env
--set +o allexport
--
--echo "Generating release: ${TAG} ${ABOUT}"
--
--# tagExists reports whether TAG is already taken, here or on the remote. The
--# remote matters on its own: a tag deleted locally after a failed attempt still
--# exists there, and pushing a new one at a different commit is rejected.
--tagExists() {
--	if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
--		printf 'locally, on %s\n' "$(git rev-parse --short "${TAG}^{commit}")"
--		return 0
--	fi
--	if ! remote="$(git ls-remote --tags origin "refs/tags/${TAG}" 2>/dev/null)"; then
--		return 1 # the remote is unreachable; the push below will say so
--	fi
--	if [ -n "${remote}" ]; then
--		# No commit is named here on purpose: for an annotated tag ls-remote
--		# gives the tag object, not the commit, and printing that as if it were
--		# the commit sends the reader looking for a SHA they will never find.
--		printf 'on origin\n'
--		return 0
--	fi
--	return 1
--}
--
--if where="$(tagExists)"; then
--	echo "❌ ${TAG} already exists ${where}"
--	echo "💡 Bump TAG in .release.env, or move the tag onto this commit:"
--	echo "     git tag -f -a ${TAG} -m \"${ABOUT}\""
--	echo "     git push --force origin ${TAG}"
--	exit 1
--fi
--
--find . -name '.DS_Store' -type f -delete
--
--git add .
--
--# Nothing to commit is not a failure — the work may already be committed — but
--# under `set -e` a plain `git commit` would stop the release right here.
--if git diff --cached --quiet; then
--	echo "Nothing to commit; releasing what is already on HEAD"
--else
--	git commit -m "📦 ${ABOUT}"
--fi
--
--git push origin main
--
--# The tag goes on after the push, so a rejected push never leaves a tag behind
--# pointing at a commit the remote has never seen.
--git tag -a "${TAG}" -m "${ABOUT}"
--git push origin "${TAG}"

deleted 02-build-releases.sh +0 -172 Viewed

deleted file mode 100755
@@ -1,172 +0,0 @@
1		-#!/bin/bash
2		-: <<'COMMENT'
3		-Build the release binaries of mm and stage them under release/${TAG}/
4		-
5		-Usage:
6		- ./02-build-releases.sh # TAG and ABOUT come from .release.env
7		- ./02-build-releases.sh v0.2.0 # override the tag for this run (what CI does)
8		-
9		-Only the Go toolchain is needed: every binary is a plain `go build`, there is
10		-no Makefile and no helper script. The same command works on a laptop and in a
11		-Rickub CI job (runners are linux/amd64; the other targets are cross-compiled).
12		-
13		-What ends up in release/${TAG}/:
14		- mm-<version>-<os>-<arch>[.exe] one binary per platform
15		- SHA256SUMS checksums of the binaries
16		- README.md download table + how to run
17		-COMMENT
18		-
19		-set -euo pipefail
20		-
21		-# .release.env carries TAG ("v0.2.0") and ABOUT (the one-line description). It
22		-# is git-ignored (*.env), so a CI job does not have it: there the tag comes
23		-# from the command line and ABOUT from the environment, or defaults to the
24		-# tag. A tag given on the command line always wins, so a test build never
25		-# edits the file.
26		-if [ -f .release.env ]; then
27		- source .release.env
28		-fi
29		-TAG="${1:-${TAG:-}}"
30		-ABOUT="${ABOUT:-Mini Me ${TAG}}"
31		-
32		-# A tag that is not vMAJOR.MINOR.PATCH[-prerelease] is a typo — measured: a
33		-# .release.env with "v0.o.0" (letter o) would otherwise build and stage
34		-# binaries nobody can name.
35		-if ! [[ "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
36		- echo "❌ TAG must look like v1.2.3 or v1.2.3-rc.1, got '${TAG}' (check .release.env)"
37		- exit 1
38		-fi
39		-
40		-# The platforms a release is built for. Add or remove a line and everything
41		-# below follows: the builds, the checksums and the README.
42		-PLATFORMS=(
43		- "darwin/arm64"
44		- "linux/amd64"
45		- "linux/arm64"
46		- "windows/amd64"
47		- "windows/arm64"
48		-)
49		-
50		-# The tag is "v0.2.0"; the assets carry the bare version, "0.2.0".
51		-VERSION="${TAG#v}"
52		-RELEASES_DIR="release/${TAG}"
53		-
54		-# -trimpath keeps this machine's paths out of binaries that go to strangers;
55		-# -s -w drops the symbol table and DWARF, about a third of the size. -X stamps
56		-# the tag into the binary, which is what `mm --version`, the start-up banner
57		-# and the window's status bar report: without it they fall back to the commit
58		-# Go embeds, and a downloaded release would not know its own name.
59		-BUILD_FLAGS=(-trimpath -ldflags "-s -w -X mm/internal/version.stamped=${TAG}")
60		-
61		-echo "🚀 Building Mini Me ${TAG} — ${ABOUT}"
62		-echo "🐹 $(go version)"
63		-
64		-rm -rf "${RELEASES_DIR}"
65		-mkdir -p "${RELEASES_DIR}"
66		-
67		-# assetName is what the binary for a platform is called once staged. Windows
68		-# executables carry .exe, or Windows will not run them.
69		-assetName() {
70		- local goos=$1 goarch=$2
71		- local name="mm-${VERSION}-${goos}-${goarch}"
72		- if [ "${goos}" = "windows" ]; then
73		- name="${name}.exe"
74		- fi
75		- printf '%s\n' "${name}"
76		-}
77		-
78		-echo ""
79		-echo "🔨 Cross-compiling for ${#PLATFORMS[@]} platforms..."
80		-
81		-for platform in "${PLATFORMS[@]}"; do
82		- goos="${platform%/*}"
83		- goarch="${platform#*/}"
84		- asset="$(assetName "${goos}" "${goarch}")"
85		-
86		- # CGO_ENABLED=0: nothing to link against on the other side of a
87		- # cross-compile, and mm needs no C — genkit, tcell and the ACP SDK are pure
88		- # Go. Without it, a darwin build from a Linux box fails at link time.
89		- if ! CGO_ENABLED=0 GOOS="${goos}" GOARCH="${goarch}" \
90		- go build "${BUILD_FLAGS[@]}" -o "${RELEASES_DIR}/${asset}" .; then
91		- echo " ❌ ${platform}"
92		- exit 1
93		- fi
94		- echo " ✅ ${asset}"
95		-done
96		-
97		-# The binary for this machine is the only one that can run here, and running
98		-# it is the one proof that what ships starts at all: -h prints the usage and
99		-# exits 0 before any config or model server is looked for.
100		-HOST_ASSET="$(assetName "$(go env GOOS)" "$(go env GOARCH)")"
101		-if [ -x "${RELEASES_DIR}/${HOST_ASSET}" ]; then
102		- if ! "${RELEASES_DIR}/${HOST_ASSET}" -h >/dev/null 2>&1; then
103		- echo " ❌ ${HOST_ASSET} does not start (mm -h failed)"
104		- exit 1
105		- fi
106		- # The stamp is a string passed to the linker: a renamed package or variable
107		- # does not fail the build, it silently leaves the binary reporting a commit
108		- # hash. Ask the binary itself, here, while the release can still be stopped.
109		- if ! "${RELEASES_DIR}/${HOST_ASSET}" --version \| grep -q -- "${TAG}"; then
110		- echo " ❌ ${HOST_ASSET} does not report ${TAG}: $("${RELEASES_DIR}/${HOST_ASSET}" --version)"
111		- echo " 💡 check -X mm/internal/version.stamped in BUILD_FLAGS"
112		- exit 1
113		- fi
114		- echo " ✅ ${HOST_ASSET} starts and reports ${TAG}"
115		-fi
116		-
117		-# checksum runs whichever of the two tools this machine has: sha256sum on
118		-# Linux, shasum on macOS.
119		-checksum() {
120		- if command -v sha256sum >/dev/null 2>&1; then
121		- sha256sum "$@"
122		- else
123		- shasum -a 256 "$@"
124		- fi
125		-}
126		-
127		-# One SHA256SUMS for every platform, names only (no directory), which is what
128		-# `sha256sum -c` expects to read next to the downloaded files.
129		-(cd "${RELEASES_DIR}" && checksum mm-"${VERSION}"-* >SHA256SUMS)
130		-echo " ✅ SHA256SUMS"
131		-
132		-# downloadTable lists the platforms as a Markdown table, so the README grows
133		-# and shrinks with PLATFORMS rather than repeating it by hand.
134		-downloadTable() {
135		- printf '\| Platform \| Download \|\n\|---\|---\|\n'
136		- for platform in "${PLATFORMS[@]}"; do
137		- local goos="${platform%/}" goarch="${platform#/}"
138		- # shellcheck disable=SC2016 # the backticks are Markdown code spans, not a command substitution
139		- printf '\| %s \| `%s` \|\n' "${platform}" "$(assetName "${goos}" "${goarch}")"
140		- done
141		-}
142		-
143		-cat >"${RELEASES_DIR}/README.md" <<EOM
144		-# Mini Me ${TAG}
145		-
146		-${ABOUT}
147		-
148		-Built with $(go env GOVERSION), CGO disabled. No runtime dependency besides a
149		-model server (Docker Model Runner or llama-server).
150		-
151		-$(downloadTable)
152		-
153		-## Running it
154		-
155		- chmod +x mm-${VERSION}-<platform>
156		- ./mm-${VERSION}-<platform> agent.yaml # line mode
157		- ./mm-${VERSION}-<platform> -tui agent.yaml # window mode
158		- ./mm-${VERSION}-<platform> -acp # from an editor (Zed, …)
159		-
160		-On macOS, an unsigned download is quarantined until you say otherwise:
161		-
162		- xattr -d com.apple.quarantine mm-${VERSION}-darwin-arm64
163		-
164		-## Verifying the download
165		-
166		- sha256sum -c SHA256SUMS --ignore-missing # shasum -a 256 -c on macOS
167		-EOM
168		-echo " ✅ README.md"
169		-
170		-echo ""
171		-echo "✨ Build complete!"
172		-ls -lh "${RELEASES_DIR}"

--#!/bin/bash
--: <<'COMMENT'
--Build the release binaries of mm and stage them under release/${TAG}/
--
--Usage:
--  ./02-build-releases.sh          # TAG and ABOUT come from .release.env
--  ./02-build-releases.sh v0.2.0   # override the tag for this run (what CI does)
--
--Only the Go toolchain is needed: every binary is a plain `go build`, there is
--no Makefile and no helper script. The same command works on a laptop and in a
--Rickub CI job (runners are linux/amd64; the other targets are cross-compiled).
--
--What ends up in release/${TAG}/:
--  mm-<version>-<os>-<arch>[.exe]   one binary per platform
--  SHA256SUMS                       checksums of the binaries
--  README.md                        download table + how to run
--COMMENT
--
--set -euo pipefail
--
--# .release.env carries TAG ("v0.2.0") and ABOUT (the one-line description). It
--# is git-ignored (*.env), so a CI job does not have it: there the tag comes
--# from the command line and ABOUT from the environment, or defaults to the
--# tag. A tag given on the command line always wins, so a test build never
--# edits the file.
--if [ -f .release.env ]; then
--	source .release.env
--fi
--TAG="${1:-${TAG:-}}"
--ABOUT="${ABOUT:-Mini Me ${TAG}}"
--
--# A tag that is not vMAJOR.MINOR.PATCH[-prerelease] is a typo — measured: a
--# .release.env with "v0.o.0" (letter o) would otherwise build and stage
--# binaries nobody can name.
--if ! [[ "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
--	echo "❌ TAG must look like v1.2.3 or v1.2.3-rc.1, got '${TAG}' (check .release.env)"
--	exit 1
--fi
--
--# The platforms a release is built for. Add or remove a line and everything
--# below follows: the builds, the checksums and the README.
--PLATFORMS=(
--	"darwin/arm64"
--	"linux/amd64"
--	"linux/arm64"
--	"windows/amd64"
--	"windows/arm64"
--)
--
--# The tag is "v0.2.0"; the assets carry the bare version, "0.2.0".
--VERSION="${TAG#v}"
--RELEASES_DIR="release/${TAG}"
--
--# -trimpath keeps this machine's paths out of binaries that go to strangers;
--# -s -w drops the symbol table and DWARF, about a third of the size. -X stamps
--# the tag into the binary, which is what `mm --version`, the start-up banner
--# and the window's status bar report: without it they fall back to the commit
--# Go embeds, and a downloaded release would not know its own name.
--BUILD_FLAGS=(-trimpath -ldflags "-s -w -X mm/internal/version.stamped=${TAG}")
--
--echo "🚀 Building Mini Me ${TAG} — ${ABOUT}"
--echo "🐹 $(go version)"
--
--rm -rf "${RELEASES_DIR}"
--mkdir -p "${RELEASES_DIR}"
--
--# assetName is what the binary for a platform is called once staged. Windows
--# executables carry .exe, or Windows will not run them.
--assetName() {
--	local goos=$1 goarch=$2
--	local name="mm-${VERSION}-${goos}-${goarch}"
--	if [ "${goos}" = "windows" ]; then
--		name="${name}.exe"
--	fi
--	printf '%s\n' "${name}"
--}
--
--echo ""
--echo "🔨 Cross-compiling for ${#PLATFORMS[@]} platforms..."
--
--for platform in "${PLATFORMS[@]}"; do
--	goos="${platform%/*}"
--	goarch="${platform#*/}"
--	asset="$(assetName "${goos}" "${goarch}")"
--
--	# CGO_ENABLED=0: nothing to link against on the other side of a
--	# cross-compile, and mm needs no C — genkit, tcell and the ACP SDK are pure
--	# Go. Without it, a darwin build from a Linux box fails at link time.
--	if ! CGO_ENABLED=0 GOOS="${goos}" GOARCH="${goarch}" \
--		go build "${BUILD_FLAGS[@]}" -o "${RELEASES_DIR}/${asset}" .; then
--		echo "   ❌ ${platform}"
--		exit 1
--	fi
--	echo "   ✅ ${asset}"
--done
--
--# The binary for this machine is the only one that can run here, and running
--# it is the one proof that what ships starts at all: -h prints the usage and
--# exits 0 before any config or model server is looked for.
--HOST_ASSET="$(assetName "$(go env GOOS)" "$(go env GOARCH)")"
--if [ -x "${RELEASES_DIR}/${HOST_ASSET}" ]; then
--	if ! "${RELEASES_DIR}/${HOST_ASSET}" -h >/dev/null 2>&1; then
--		echo "   ❌ ${HOST_ASSET} does not start (mm -h failed)"
--		exit 1
--	fi
--	# The stamp is a string passed to the linker: a renamed package or variable
--	# does not fail the build, it silently leaves the binary reporting a commit
--	# hash. Ask the binary itself, here, while the release can still be stopped.
--	if ! "${RELEASES_DIR}/${HOST_ASSET}" --version | grep -q -- "${TAG}"; then
--		echo "   ❌ ${HOST_ASSET} does not report ${TAG}: $("${RELEASES_DIR}/${HOST_ASSET}" --version)"
--		echo "   💡 check -X mm/internal/version.stamped in BUILD_FLAGS"
--		exit 1
--	fi
--	echo "   ✅ ${HOST_ASSET} starts and reports ${TAG}"
--fi
--
--# checksum runs whichever of the two tools this machine has: sha256sum on
--# Linux, shasum on macOS.
--checksum() {
--	if command -v sha256sum >/dev/null 2>&1; then
--		sha256sum "$@"
--	else
--		shasum -a 256 "$@"
--	fi
--}
--
--# One SHA256SUMS for every platform, names only (no directory), which is what
--# `sha256sum -c` expects to read next to the downloaded files.
--(cd "${RELEASES_DIR}" && checksum mm-"${VERSION}"-* >SHA256SUMS)
--echo "   ✅ SHA256SUMS"
--
--# downloadTable lists the platforms as a Markdown table, so the README grows
--# and shrinks with PLATFORMS rather than repeating it by hand.
--downloadTable() {
--	printf '| Platform | Download |\n|---|---|\n'
--	for platform in "${PLATFORMS[@]}"; do
--		local goos="${platform%/*}" goarch="${platform#*/}"
--		# shellcheck disable=SC2016 # the backticks are Markdown code spans, not a command substitution
--		printf '| %s | `%s` |\n' "${platform}" "$(assetName "${goos}" "${goarch}")"
--	done
--}
--
--cat >"${RELEASES_DIR}/README.md" <<EOM
--# Mini Me ${TAG}
--
--${ABOUT}
--
--Built with $(go env GOVERSION), CGO disabled. No runtime dependency besides a
--model server (Docker Model Runner or llama-server).
--
--$(downloadTable)
--
--## Running it
--
--    chmod +x mm-${VERSION}-<platform>
--    ./mm-${VERSION}-<platform> agent.yaml          # line mode
--    ./mm-${VERSION}-<platform> -tui agent.yaml     # window mode
--    ./mm-${VERSION}-<platform> -acp                # from an editor (Zed, …)
--
--On macOS, an unsigned download is quarantined until you say otherwise:
--
--    xattr -d com.apple.quarantine mm-${VERSION}-darwin-arm64
--
--## Verifying the download
--
--    sha256sum -c SHA256SUMS --ignore-missing     # shasum -a 256 -c on macOS
--EOM
--echo "   ✅ README.md"
--
--echo ""
--echo "✨ Build complete!"
--ls -lh "${RELEASES_DIR}"

modified README.md +2 -2 Viewed

@@ -132,7 +132,7 @@ Anything that speaks ACP can host `mm -acp` the same way: JetBrains IDEs (In
132	132	- Use mini-me from another program: drive `mm -acp` over ACP — `demo.acp.sdk/nodejs/minime.js` gives Node.js `complete`, `stream`, cancellation and a permission callback, with no dependency. See [`demo.acp.sdk/`](demo.acp.sdk/README.en.md).
133	133	- Test a model: `testing/` holds two benches run by mm itself — a coordinator agent gives small tasks to a candidate agent whose model is under test, checks each result with a command, and writes a Markdown report: the model as a working agent (`testing/model-check/`) and function calling alone, with tools declared in the agent file (`testing/function-calling/`). See [`testing/`](testing/README.en.md).
134	134	- Containers: `mm dockerinit` writes a `Dockerfile` (the latest release, for amd64 and arm64, not root) and a `compose.yaml` that mounts your project. See [run mini-me in a container](docs/en/how-to/run-in-a-container.md).
135		-- 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). `mm sbxinit` writes a `sbxenv.yaml` with the latest kit.
	135	+- Docker Sandboxes: the sandbox kit lives in its own repository, [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit); `demos/use-with-sbx/` explains how to use it (`sbx run …`), with two mixins (`go-toolchain`, `cli-tools`) and ready-made configurations — see `demos/use-with-sbx/README.md` and [Run mini-me in a Docker Sandbox](docs/en/how-to/run-in-a-docker-sandbox.md). `mm sbxinit` writes a `sbxenv.yaml` with the latest kit.
136	136
137	137	## Demos
138	138
@@ -155,7 +155,7 @@ The `demos/` directory holds ready-made set-ups (most with a README explaining h
155	155	\| `demos/struggle-signals/` \| a fake OpenAI-compatible server and `run-all.sh` that trigger every struggle signal (loop, failed calls, broken call, stalled, max turns, context full…) without a real model \|
156	156	\| `demo.acp.sdk/` \| mini-me as a library from other languages, by driving `mm -acp` over ACP — four clients with the same API (start, complete, stream, cancel, permission callback), four examples and tests against a fake mm each: `nodejs/` (ticket 167, no dependency), `nodejs-sdk/` (ticket 188, official ACP TypeScript SDK), `go/` (ticket 168, package `minime`), `kotlin/` (ticket 187, official ACP Kotlin SDK); see [demo.acp.sdk/README.en.md](demo.acp.sdk/README.en.md) \|
157	157	\| `testing/` \| model testers run by mm itself: a coordinator (Gemma 4 12B) follows a skill, gives small tasks to a `candidate` agent whose model is under test (Qwen3.5 4B for model-check, Luciole 1B for function-calling), checks each result with a command and writes a Markdown report — `model-check/` (tool calls, exact instructions, Go code that must run, several steps) and `function-calling/` (only tools declared in the candidate's `tools:`) \|
158		-\| `dev.team/` \| a team of five agents for a 32 GB laptop (ticket 152): a Qwen3.5 4B coordinator hands each request to a reformulator, a coder, a reviewer or a tutor (Gemma 4 12B, Mellum2 12B); hooks keep one model in memory at a time; measured: bug fixes, lessons and reviews work, new features not yet \|
	158	+\| `demos/dev.team/` \| a team of five agents for a 32 GB laptop (ticket 152): a Qwen3.5 4B coordinator hands each request to a reformulator, a coder, a reviewer or a tutor (Gemma 4 12B, Mellum2 12B); hooks keep one model in memory at a time; measured: bug fixes, lessons and reviews work, new features not yet \|
159	159	\| `demos/blog-team/` \| the smallest team: a lead, a coder and a reviewer in 75 lines of YAML, one model (Mellum2 12B Q8_0 on llmman), written for a blog post \|
160	160	\| `demos/translator/` \| a French ↔ English translator (Gemma 4 E4B on llmman): `AGENTS.md` for the style, skills for technical texts, e-mails and idioms, `$styles` for professional / informal / Slack versions, `translate.sh` for files \|
161	161	\| `demos/qwen-style/` \| a general coding agent whose system prompt follows Qwen Code's, adapted to mm's tools, in three configurations on llmman: Qwen3.8 27B, Qwen3-Coder-Next, Qwen3.6 35B-A3B — Qwen Code's `new-app` and `simplify` skills, measured results \|

  - **Use mini-me from another program**: drive `mm -acp` over ACP — `demo.acp.sdk/nodejs/minime.js` gives Node.js `complete`, `stream`, cancellation and a permission callback, with no dependency. See [`demo.acp.sdk/`](demo.acp.sdk/README.en.md).
  - **Test a model**: `testing/` holds two benches run by mm itself — a coordinator agent gives small tasks to a candidate agent whose model is under test, checks each result with a command, and writes a Markdown report: the model as a working agent (`testing/model-check/`) and function calling alone, with tools declared in the agent file (`testing/function-calling/`). See [`testing/`](testing/README.en.md).
  - **Containers**: `mm dockerinit` writes a `Dockerfile` (the latest release, for amd64 and arm64, not root) and a `compose.yaml` that mounts your project. See [run mini-me in a container](docs/en/how-to/run-in-a-container.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). `mm sbxinit` writes a `sbxenv.yaml` with the latest kit.
++- **Docker Sandboxes**: the sandbox kit lives in its own repository, [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit); `demos/use-with-sbx/` explains how to use it (`sbx run …`), with two mixins (`go-toolchain`, `cli-tools`) and ready-made configurations — see `demos/use-with-sbx/README.md` and [Run mini-me in a Docker Sandbox](docs/en/how-to/run-in-a-docker-sandbox.md). `mm sbxinit` writes a `sbxenv.yaml` with the latest kit.
  ## Demos
  | `demos/struggle-signals/` | a fake OpenAI-compatible server and `run-all.sh` that trigger every struggle signal (loop, failed calls, broken call, stalled, max turns, context full…) without a real model |
  | `demo.acp.sdk/` | mini-me as a library from other languages, by driving `mm -acp` over ACP — four clients with the same API (start, complete, stream, cancel, permission callback), four examples and tests against a fake mm each: `nodejs/` (ticket 167, no dependency), `nodejs-sdk/` (ticket 188, official ACP TypeScript SDK), `go/` (ticket 168, package `minime`), `kotlin/` (ticket 187, official ACP Kotlin SDK); see [demo.acp.sdk/README.en.md](demo.acp.sdk/README.en.md) |
  | `testing/` | model testers run by mm itself: a coordinator (Gemma 4 12B) follows a skill, gives small tasks to a `candidate` agent whose model is under test (Qwen3.5 4B for model-check, Luciole 1B for function-calling), checks each result with a command and writes a Markdown report — `model-check/` (tool calls, exact instructions, Go code that must run, several steps) and `function-calling/` (only tools declared in the candidate's `tools:`) |
--| `dev.team/` | a team of five agents for a 32 GB laptop (ticket 152): a Qwen3.5 4B coordinator hands each request to a reformulator, a coder, a reviewer or a tutor (Gemma 4 12B, Mellum2 12B); hooks keep one model in memory at a time; measured: bug fixes, lessons and reviews work, new features not yet |
++| `demos/dev.team/` | a team of five agents for a 32 GB laptop (ticket 152): a Qwen3.5 4B coordinator hands each request to a reformulator, a coder, a reviewer or a tutor (Gemma 4 12B, Mellum2 12B); hooks keep one model in memory at a time; measured: bug fixes, lessons and reviews work, new features not yet |
  | `demos/blog-team/` | the smallest team: a lead, a coder and a reviewer in 75 lines of YAML, one model (Mellum2 12B Q8_0 on llmman), written for a blog post |
  | `demos/translator/` | a French ↔ English translator (Gemma 4 E4B on llmman): `AGENTS.md` for the style, skills for technical texts, e-mails and idioms, `$styles` for professional / informal / Slack versions, `translate.sh` for files |
  | `demos/qwen-style/` | a general coding agent whose system prompt follows Qwen Code's, adapted to mm's tools, in three configurations on llmman: Qwen3.8 27B, Qwen3-Coder-Next, Qwen3.6 35B-A3B — Qwen Code's `new-app` and `simplify` skills, measured results |

renamed demos/dev.team/README.en.md +9 -9 Viewed

similarity index 97%
rename from dev.team/README.en.md
rename to demos/dev.team/README.en.md
@@ -78,14 +78,14 @@ Only the coder may `rename`; the others' prompts forbid it. gopls finds the `go.
78	78	![team/ read-only, workspace/ read-write](dev-team-sandbox.svg)
79	79
80	80	```
81		-dev.team/
	81	+demos/dev.team/
82	82	├── sbxenv.yaml, start-zed.sh, stop-zed.sh the sandbox — never mounted
83	83	├── README., dev-team-.{drawio,svg,png} this documentation
84	84	├── team/ the agents and their hooks → mounted READ-ONLY
85	85	└── workspace/ your code (empty in the repository), .mm/ → the read-write workspace
86	86	```
87	87
88		-The agents' files are what decides what the team may do: their prompts, their tools, `yolo`, the hooks. A team member with `bash` and `write_file` could rewrite them, and the next start would run its version. So they live in `team/`, which the sandbox mounts with `readOnly: true`, apart from the code the team changes. Docker also recommends keeping the environment file outside every mounted directory, so that an agent cannot change the commands your host runs: `sbxenv.yaml` and the scripts stay at the root of `dev.team/`, which is not mounted.
	88	+The agents' files are what decides what the team may do: their prompts, their tools, `yolo`, the hooks. A team member with `bash` and `write_file` could rewrite them, and the next start would run its version. So they live in `team/`, which the sandbox mounts with `readOnly: true`, apart from the code the team changes. Docker also recommends keeping the environment file outside every mounted directory, so that an agent cannot change the commands your host runs: `sbxenv.yaml` and the scripts stay at the root of `demos/dev.team/`, which is not mounted.
89	89
90	90	mm finds the coordinator through `AGENT_CONFIG`, set in `sbxenv.yaml`; the other agents and the hooks are found next to it (`mmConfigs` paths and `$MM_CONFIG_DIR` are relative to `team/agent.yaml`). Sessions and traces go to `workspace/.mm/`, the session's working directory.
91	91
@@ -94,7 +94,7 @@ mm finds the coordinator through `AGENT_CONFIG`, set in `sbxenv.yaml`; the other
94	94	### In a sandbox, with Zed
95	95
96	96	```bash
97		-cd dev.team
	97	+cd demos/dev.team
98	98	sbx setup ssh # once
99	99	./start-zed.sh # sbx env create --env-arg DEV_TEAM_DIR=$PWD, then Zed on workspace/
100	100	./stop-zed.sh # removes the sandbox; team/ and workspace/ stay on the host
@@ -107,10 +107,10 @@ To check, once the sandbox is up: `sbx version` (`sbx env` needs 0.39.0 or newer
107	107	### On the host
108	108
109	109	```bash
110		-cd dev.team/workspace
111		-AGENT_CONFIG=$PWD/../team/agent.yaml ../../mm -tui
112		-../../mm -config ../team/agent.yaml -tui # the same
113		-../../mm -config ../team/agent.yaml -p "…" # one request, then exit (the reformulator cannot ask you anything)
	110	+cd demos/dev.team/workspace
	111	+AGENT_CONFIG=$PWD/../team/agent.yaml ../../../mm -tui
	112	+../../../mm -config ../team/agent.yaml -tui # the same
	113	+../../../mm -config ../team/agent.yaml -p "…" # one request, then exit (the reformulator cannot ask you anything)
114	114	```
115	115
116	116	The sandbox publishes ports 8080, 6060 and 5050 to the same ports on the host (`ports` in `sbxenv.yaml`, applied at creation): a server started in the sandbox must listen on `0.0.0.0` to be reached on `http://localhost:8080`.
@@ -217,7 +217,7 @@ Mellum2 stays the default, as the ticket chose: about 6 times faster, and right
217	217	## Files
218	218
219	219	```
220		-dev.team/
	220	+demos/dev.team/
221	221	├── sbxenv.yaml the sandbox: workspace/ read-write, team/ read-only, AGENT_CONFIG
222	222	├── start-zed.sh, stop-zed.sh create the sandbox and open workspace/ in Zed; remove it
223	223	├── team/ read-only in the sandbox
@@ -235,4 +235,4 @@ dev.team/
235	235	└── dev-team-sandbox.* diagram: the sandbox mounts (.drawio .svg .png)
236	236	```
237	237
238		-The diagrams are generated by `.claude/skills/drawio-fancy-diagram/generator/examples/dev_team.py dev.team`.
	238	+The diagrams are generated by `.claude/skills/drawio-fancy-diagram/generator/examples/dev_team.py demos/dev.team`.

  ![team/ read-only, workspace/ read-write](dev-team-sandbox.svg)
  ```
--dev.team/
++demos/dev.team/
  ├── sbxenv.yaml, start-zed.sh, stop-zed.sh   the sandbox — never mounted
  ├── README.*, dev-team-*.{drawio,svg,png}    this documentation
  ├── team/        the agents and their hooks  → mounted READ-ONLY
  └── workspace/   your code (empty in the repository), .mm/  → the read-write workspace
  ```
--The agents' files are what decides what the team may do: their prompts, their tools, `yolo`, the hooks. A team member with `bash` and `write_file` could rewrite them, and the next start would run its version. So they live in `team/`, which the sandbox mounts with `readOnly: true`, apart from the code the team changes. Docker also recommends keeping the environment file outside every mounted directory, so that an agent cannot change the commands your host runs: `sbxenv.yaml` and the scripts stay at the root of `dev.team/`, which is not mounted.
++The agents' files are what decides what the team may do: their prompts, their tools, `yolo`, the hooks. A team member with `bash` and `write_file` could rewrite them, and the next start would run its version. So they live in `team/`, which the sandbox mounts with `readOnly: true`, apart from the code the team changes. Docker also recommends keeping the environment file outside every mounted directory, so that an agent cannot change the commands your host runs: `sbxenv.yaml` and the scripts stay at the root of `demos/dev.team/`, which is not mounted.
  mm finds the coordinator through `AGENT_CONFIG`, set in `sbxenv.yaml`; the other agents and the hooks are found next to it (`mmConfigs` paths and `$MM_CONFIG_DIR` are relative to `team/agent.yaml`). Sessions and traces go to `workspace/.mm/`, the session's working directory.
  ### In a sandbox, with Zed
  ```bash
--cd dev.team
++cd demos/dev.team
  sbx setup ssh             # once
  ./start-zed.sh            # sbx env create --env-arg DEV_TEAM_DIR=$PWD, then Zed on workspace/
  ./stop-zed.sh             # removes the sandbox; team/ and workspace/ stay on the host
  ### On the host
  ```bash
--cd dev.team/workspace
++cd demos/dev.team/workspace
--AGENT_CONFIG=$PWD/../team/agent.yaml ../../mm -tui
++AGENT_CONFIG=$PWD/../team/agent.yaml ../../../mm -tui
--../../mm -config ../team/agent.yaml -tui      # the same
++../../../mm -config ../team/agent.yaml -tui      # the same
--../../mm -config ../team/agent.yaml -p "…"    # one request, then exit (the reformulator cannot ask you anything)
++../../../mm -config ../team/agent.yaml -p "…"    # one request, then exit (the reformulator cannot ask you anything)
  ```
  The sandbox publishes ports 8080, 6060 and 5050 to the same ports on the host (`ports` in `sbxenv.yaml`, applied at creation): a server started in the sandbox must listen on `0.0.0.0` to be reached on `http://localhost:8080`.
  ## Files
  ```
--dev.team/
++demos/dev.team/
  ├── sbxenv.yaml                the sandbox: workspace/ read-write, team/ read-only, AGENT_CONFIG
  ├── start-zed.sh, stop-zed.sh  create the sandbox and open workspace/ in Zed; remove it
  ├── team/                      read-only in the sandbox
  └── dev-team-sandbox.*         diagram: the sandbox mounts (.drawio .svg .png)
  ```
--The diagrams are generated by `.claude/skills/drawio-fancy-diagram/generator/examples/dev_team.py dev.team`.
++The diagrams are generated by `.claude/skills/drawio-fancy-diagram/generator/examples/dev_team.py demos/dev.team`.

renamed demos/dev.team/README.fr.md +9 -9 Viewed

similarity index 97%
rename from dev.team/README.fr.md
rename to demos/dev.team/README.fr.md
@@ -78,14 +78,14 @@ Seul le coder peut faire `rename` ; les prompts des autres l'interdisent. gopls
78	78	![team/ en lecture seule, workspace/ en lecture-écriture](dev-team-sandbox.svg)
79	79
80	80	```
81		-dev.team/
	81	+demos/dev.team/
82	82	├── sbxenv.yaml, start-zed.sh, stop-zed.sh la sandbox — jamais montés
83	83	├── README., dev-team-.{drawio,svg,png} cette documentation
84	84	├── team/ les agents et leurs hooks → monté en LECTURE SEULE
85	85	└── workspace/ votre code (vide dans le dépôt), .mm/ → l'espace de travail en lecture-écriture
86	86	```
87	87
88		-Les fichiers des agents décident de ce que l'équipe a le droit de faire : leurs prompts, leurs outils, `yolo`, les hooks. Un membre de l'équipe qui a `bash` et `write_file` pourrait les réécrire, et le prochain démarrage exécuterait sa version. Ils sont donc dans `team/`, que la sandbox monte avec `readOnly: true`, à part du code que l'équipe modifie. Docker recommande aussi de garder le fichier d'environnement hors de tout dossier monté, pour qu'un agent ne puisse pas changer les commandes que lance votre machine : `sbxenv.yaml` et les scripts restent à la racine de `dev.team/`, qui n'est pas montée.
	88	+Les fichiers des agents décident de ce que l'équipe a le droit de faire : leurs prompts, leurs outils, `yolo`, les hooks. Un membre de l'équipe qui a `bash` et `write_file` pourrait les réécrire, et le prochain démarrage exécuterait sa version. Ils sont donc dans `team/`, que la sandbox monte avec `readOnly: true`, à part du code que l'équipe modifie. Docker recommande aussi de garder le fichier d'environnement hors de tout dossier monté, pour qu'un agent ne puisse pas changer les commandes que lance votre machine : `sbxenv.yaml` et les scripts restent à la racine de `demos/dev.team/`, qui n'est pas montée.
89	89
90	90	mm trouve le coordinateur grâce à `AGENT_CONFIG`, défini dans `sbxenv.yaml` ; les autres agents et les hooks sont trouvés à côté (les chemins de `mmConfigs` et `$MM_CONFIG_DIR` sont relatifs à `team/agent.yaml`). Les sessions et les traces vont dans `workspace/.mm/`, le dossier de travail de la session.
91	91
@@ -94,7 +94,7 @@ mm trouve le coordinateur grâce à `AGENT_CONFIG`, défini dans `sbxenv.yaml` ;
94	94	### Dans une sandbox, avec Zed
95	95
96	96	```bash
97		-cd dev.team
	97	+cd demos/dev.team
98	98	sbx setup ssh # une fois
99	99	./start-zed.sh # sbx env create --env-arg DEV_TEAM_DIR=$PWD, puis Zed sur workspace/
100	100	./stop-zed.sh # supprime la sandbox ; team/ et workspace/ restent sur la machine
@@ -107,10 +107,10 @@ Pour vérifier, une fois la sandbox lancée : `sbx version` (`sbx env` demande l
107	107	### Sur la machine
108	108
109	109	```bash
110		-cd dev.team/workspace
111		-AGENT_CONFIG=$PWD/../team/agent.yaml ../../mm -tui
112		-../../mm -config ../team/agent.yaml -tui # la même chose
113		-../../mm -config ../team/agent.yaml -p "…" # une demande, puis sortie (le reformulator ne peut rien vous demander)
	110	+cd demos/dev.team/workspace
	111	+AGENT_CONFIG=$PWD/../team/agent.yaml ../../../mm -tui
	112	+../../../mm -config ../team/agent.yaml -tui # la même chose
	113	+../../../mm -config ../team/agent.yaml -p "…" # une demande, puis sortie (le reformulator ne peut rien vous demander)
114	114	```
115	115
116	116	La sandbox publie les ports 8080, 6060 et 5050 sur les mêmes ports de la machine (`ports` dans `sbxenv.yaml`, appliqué à la création) : un serveur lancé dans la sandbox doit écouter sur `0.0.0.0` pour être joignable sur `http://localhost:8080`.
@@ -217,7 +217,7 @@ Mellum2 reste le coder par défaut, comme le ticket l'a choisi : environ 6 fois
217	217	## Fichiers
218	218
219	219	```
220		-dev.team/
	220	+demos/dev.team/
221	221	├── sbxenv.yaml la sandbox : workspace/ en lecture-écriture, team/ en lecture seule, AGENT_CONFIG
222	222	├── start-zed.sh, stop-zed.sh créer la sandbox et ouvrir workspace/ dans Zed ; la supprimer
223	223	├── team/ en lecture seule dans la sandbox
@@ -235,4 +235,4 @@ dev.team/
235	235	└── dev-team-sandbox.* diagramme : les montages de la sandbox (.drawio .svg .png)
236	236	```
237	237
238		-Les diagrammes sont générés par `.claude/skills/drawio-fancy-diagram/generator/examples/dev_team.py dev.team`.
	238	+Les diagrammes sont générés par `.claude/skills/drawio-fancy-diagram/generator/examples/dev_team.py demos/dev.team`.

  ![team/ en lecture seule, workspace/ en lecture-écriture](dev-team-sandbox.svg)
  ```
--dev.team/
++demos/dev.team/
  ├── sbxenv.yaml, start-zed.sh, stop-zed.sh   la sandbox — jamais montés
  ├── README.*, dev-team-*.{drawio,svg,png}    cette documentation
  ├── team/        les agents et leurs hooks   → monté en LECTURE SEULE
  └── workspace/   votre code (vide dans le dépôt), .mm/  → l'espace de travail en lecture-écriture
  ```
--Les fichiers des agents décident de ce que l'équipe a le droit de faire : leurs prompts, leurs outils, `yolo`, les hooks. Un membre de l'équipe qui a `bash` et `write_file` pourrait les réécrire, et le prochain démarrage exécuterait sa version. Ils sont donc dans `team/`, que la sandbox monte avec `readOnly: true`, à part du code que l'équipe modifie. Docker recommande aussi de garder le fichier d'environnement hors de tout dossier monté, pour qu'un agent ne puisse pas changer les commandes que lance votre machine : `sbxenv.yaml` et les scripts restent à la racine de `dev.team/`, qui n'est pas montée.
++Les fichiers des agents décident de ce que l'équipe a le droit de faire : leurs prompts, leurs outils, `yolo`, les hooks. Un membre de l'équipe qui a `bash` et `write_file` pourrait les réécrire, et le prochain démarrage exécuterait sa version. Ils sont donc dans `team/`, que la sandbox monte avec `readOnly: true`, à part du code que l'équipe modifie. Docker recommande aussi de garder le fichier d'environnement hors de tout dossier monté, pour qu'un agent ne puisse pas changer les commandes que lance votre machine : `sbxenv.yaml` et les scripts restent à la racine de `demos/dev.team/`, qui n'est pas montée.
  mm trouve le coordinateur grâce à `AGENT_CONFIG`, défini dans `sbxenv.yaml` ; les autres agents et les hooks sont trouvés à côté (les chemins de `mmConfigs` et `$MM_CONFIG_DIR` sont relatifs à `team/agent.yaml`). Les sessions et les traces vont dans `workspace/.mm/`, le dossier de travail de la session.
  ### Dans une sandbox, avec Zed
  ```bash
--cd dev.team
++cd demos/dev.team
  sbx setup ssh             # une fois
  ./start-zed.sh            # sbx env create --env-arg DEV_TEAM_DIR=$PWD, puis Zed sur workspace/
  ./stop-zed.sh             # supprime la sandbox ; team/ et workspace/ restent sur la machine
  ### Sur la machine
  ```bash
--cd dev.team/workspace
++cd demos/dev.team/workspace
--AGENT_CONFIG=$PWD/../team/agent.yaml ../../mm -tui
++AGENT_CONFIG=$PWD/../team/agent.yaml ../../../mm -tui
--../../mm -config ../team/agent.yaml -tui      # la même chose
++../../../mm -config ../team/agent.yaml -tui      # la même chose
--../../mm -config ../team/agent.yaml -p "…"    # une demande, puis sortie (le reformulator ne peut rien vous demander)
++../../../mm -config ../team/agent.yaml -p "…"    # une demande, puis sortie (le reformulator ne peut rien vous demander)
  ```
  La sandbox publie les ports 8080, 6060 et 5050 sur les mêmes ports de la machine (`ports` dans `sbxenv.yaml`, appliqué à la création) : un serveur lancé dans la sandbox doit écouter sur `0.0.0.0` pour être joignable sur `http://localhost:8080`.
  ## Fichiers
  ```
--dev.team/
++demos/dev.team/
  ├── sbxenv.yaml                la sandbox : workspace/ en lecture-écriture, team/ en lecture seule, AGENT_CONFIG
  ├── start-zed.sh, stop-zed.sh  créer la sandbox et ouvrir workspace/ dans Zed ; la supprimer
  ├── team/                      en lecture seule dans la sandbox
  └── dev-team-sandbox.*         diagramme : les montages de la sandbox (.drawio .svg .png)
  ```
--Les diagrammes sont générés par `.claude/skills/drawio-fancy-diagram/generator/examples/dev_team.py dev.team`.
++Les diagrammes sont générés par `.claude/skills/drawio-fancy-diagram/generator/examples/dev_team.py demos/dev.team`.

renamed demos/dev.team/dev-team-flow.drawio +0 -0 Viewed

similarity index 100%
rename from dev.team/dev-team-flow.drawio
rename to demos/dev.team/dev-team-flow.drawio

similarity index 100%
rename from dev.team/dev-team-flow.drawio
rename to demos/dev.team/dev-team-flow.drawio

renamed demos/dev.team/dev-team-flow.png +0 -0 Viewed

similarity index 100%
rename from dev.team/dev-team-flow.png
rename to demos/dev.team/dev-team-flow.png

similarity index 100%
rename from dev.team/dev-team-flow.png
rename to demos/dev.team/dev-team-flow.png

renamed demos/dev.team/dev-team-flow.svg +0 -0 Viewed

similarity index 100%
rename from dev.team/dev-team-flow.svg
rename to demos/dev.team/dev-team-flow.svg

similarity index 100%
rename from dev.team/dev-team-flow.svg
rename to demos/dev.team/dev-team-flow.svg

renamed demos/dev.team/dev-team-memory.drawio +0 -0 Viewed

similarity index 100%
rename from dev.team/dev-team-memory.drawio
rename to demos/dev.team/dev-team-memory.drawio

similarity index 100%
rename from dev.team/dev-team-memory.drawio
rename to demos/dev.team/dev-team-memory.drawio

renamed demos/dev.team/dev-team-memory.png +0 -0 Viewed

similarity index 100%
rename from dev.team/dev-team-memory.png
rename to demos/dev.team/dev-team-memory.png

similarity index 100%
rename from dev.team/dev-team-memory.png
rename to demos/dev.team/dev-team-memory.png

renamed demos/dev.team/dev-team-memory.svg +0 -0 Viewed

similarity index 100%
rename from dev.team/dev-team-memory.svg
rename to demos/dev.team/dev-team-memory.svg

similarity index 100%
rename from dev.team/dev-team-memory.svg
rename to demos/dev.team/dev-team-memory.svg

renamed demos/dev.team/dev-team-sandbox.drawio +0 -0 Viewed

similarity index 100%
rename from dev.team/dev-team-sandbox.drawio
rename to demos/dev.team/dev-team-sandbox.drawio

similarity index 100%
rename from dev.team/dev-team-sandbox.drawio
rename to demos/dev.team/dev-team-sandbox.drawio

renamed demos/dev.team/dev-team-sandbox.png +0 -0 Viewed

similarity index 100%
rename from dev.team/dev-team-sandbox.png
rename to demos/dev.team/dev-team-sandbox.png

similarity index 100%
rename from dev.team/dev-team-sandbox.png
rename to demos/dev.team/dev-team-sandbox.png

renamed demos/dev.team/dev-team-sandbox.svg +0 -0 Viewed

similarity index 100%
rename from dev.team/dev-team-sandbox.svg
rename to demos/dev.team/dev-team-sandbox.svg

similarity index 100%
rename from dev.team/dev-team-sandbox.svg
rename to demos/dev.team/dev-team-sandbox.svg

renamed demos/dev.team/sbxenv.yaml +1 -1 Viewed

similarity index 99%
rename from dev.team/sbxenv.yaml
rename to demos/dev.team/sbxenv.yaml
@@ -16,7 +16,7 @@ kits:
16	16	# directory: Docker recommends it, so that an agent cannot rewrite the
17	17	# commands your host runs (writableEnvFiles is left off).
18	18	#
19		-# dev.team/
	19	+# demos/dev.team/
20	20	# ├── sbxenv.yaml, start-zed.sh, stop-zed.sh, README.* not mounted
21	21	# ├── team/ the agents (agent*.yaml) and their hooks READ-ONLY
22	22	# └── workspace/ the code the team works on read-write

  # directory: Docker recommends it, so that an agent cannot rewrite the
  # commands your host runs (writableEnvFiles is left off).
  #
--#   dev.team/
++#   demos/dev.team/
  #   ├── sbxenv.yaml, start-zed.sh, stop-zed.sh, README.*   not mounted
  #   ├── team/        the agents (agent*.yaml) and their hooks   READ-ONLY
  #   └── workspace/   the code the team works on                 read-write

renamed demos/dev.team/start-zed.sh +1 -1 Viewed

similarity index 79%
rename from dev.team/start-zed.sh
rename to demos/dev.team/start-zed.sh
@@ -1,6 +1,6 @@
1	1	#!/usr/bin/env bash
2	2	# Creates the sandbox from sbxenv.yaml and opens workspace/ in Zed over SSH.
3		-# Run it from dev.team/ (the folder of sbxenv.yaml). Once: sbx setup ssh
	3	+# Run it from demos/dev.team/ (the folder of sbxenv.yaml). Once: sbx setup ssh
4	4	set -euo pipefail
5	5	cd "$(dirname "$0")"
6	6	# DEV_TEAM_DIR tells the sandbox where team/agent.yaml is (AGENT_CONFIG).

  #!/usr/bin/env bash
  # Creates the sandbox from sbxenv.yaml and opens workspace/ in Zed over SSH.
--# Run it from dev.team/ (the folder of sbxenv.yaml). Once: sbx setup ssh
++# Run it from demos/dev.team/ (the folder of sbxenv.yaml). Once: sbx setup ssh
  set -euo pipefail
  cd "$(dirname "$0")"
  # DEV_TEAM_DIR tells the sandbox where team/agent.yaml is (AGENT_CONFIG).

renamed demos/dev.team/stop-zed.sh +0 -0 Viewed

similarity index 100%
rename from dev.team/stop-zed.sh
rename to demos/dev.team/stop-zed.sh

similarity index 100%
rename from dev.team/stop-zed.sh
rename to demos/dev.team/stop-zed.sh

renamed demos/dev.team/team/agent.coder.ornith.yaml +1 -1 Viewed

similarity index 98%
rename from dev.team/team/agent.coder.ornith.yaml
rename to demos/dev.team/team/agent.coder.ornith.yaml
@@ -8,7 +8,7 @@
8	8	# the project's own commands. Called by the coordinator (agent.yaml) with a
9	9	# task brief from the reformulator; also usable alone:
10	10	#
11		-# cd dev.team/workspace && ../../mm -config ../team/agent.coder.ornith.yaml
	11	+# cd demos/dev.team/workspace && ../../../mm -config ../team/agent.coder.ornith.yaml
12	12	#
13	13	# Model: Ornith 1.5 9B (a Qwen3.5 9B fine-tune), Q4_K_M, 6.7 GB.
14	14

  # the project's own commands. Called by the coordinator (agent.yaml) with a
  # task brief from the reformulator; also usable alone:
  #
--#   cd dev.team/workspace && ../../mm -config ../team/agent.coder.ornith.yaml
++#   cd demos/dev.team/workspace && ../../../mm -config ../team/agent.coder.ornith.yaml
  #
  # Model: Ornith 1.5 9B (a Qwen3.5 9B fine-tune), Q4_K_M, 6.7 GB.

renamed demos/dev.team/team/agent.coder.yaml +1 -1 Viewed

similarity index 98%
rename from dev.team/team/agent.coder.yaml
rename to demos/dev.team/team/agent.coder.yaml
@@ -2,7 +2,7 @@
2	2	# the project's own commands. Called by the coordinator (agent.yaml) with a
3	3	# task brief from the reformulator; also usable alone:
4	4	#
5		-# cd dev.team/workspace && ../../mm -config ../team/agent.coder.yaml
	5	+# cd demos/dev.team/workspace && ../../../mm -config ../team/agent.coder.yaml
6	6	#
7	7	# Model: Mellum2 12B-A2.5B Instruct (JetBrains), Q4_K_M, 8.1 GB — a code
8	8	# model, mixture of experts (2.5B active), so it answers fast for its size.

  # the project's own commands. Called by the coordinator (agent.yaml) with a
  # task brief from the reformulator; also usable alone:
  #
--#   cd dev.team/workspace && ../../mm -config ../team/agent.coder.yaml
++#   cd demos/dev.team/workspace && ../../../mm -config ../team/agent.coder.yaml
  #
  # Model: Mellum2 12B-A2.5B Instruct (JetBrains), Q4_K_M, 8.1 GB — a code
  # model, mixture of experts (2.5B active), so it answers fast for its size.

renamed demos/dev.team/team/agent.reformulator.yaml +1 -1 Viewed

similarity index 98%
rename from dev.team/team/agent.reformulator.yaml
rename to demos/dev.team/team/agent.reformulator.yaml
@@ -4,7 +4,7 @@
4	4	# nothing. Called first by the coordinator (agent.yaml) for every code task;
5	5	# also usable alone:
6	6	#
7		-# cd dev.team/workspace && ../../mm -config ../team/agent.reformulator.yaml
	7	+# cd demos/dev.team/workspace && ../../../mm -config ../team/agent.reformulator.yaml
8	8	#
9	9	# Model: Gemma 4 12B it (unsloth), Q4_K_M, 7.3 GB — good at rewriting and at
10	10	# following a fixed output shape. Same model as the reviewer.

  # nothing. Called first by the coordinator (agent.yaml) for every code task;
  # also usable alone:
  #
--#   cd dev.team/workspace && ../../mm -config ../team/agent.reformulator.yaml
++#   cd demos/dev.team/workspace && ../../../mm -config ../team/agent.reformulator.yaml
  #
  # Model: Gemma 4 12B it (unsloth), Q4_K_M, 7.3 GB — good at rewriting and at
  # following a fixed output shape. Same model as the reviewer.

renamed demos/dev.team/team/agent.reviewer.yaml +1 -1 Viewed

similarity index 98%
rename from dev.team/team/agent.reviewer.yaml
rename to demos/dev.team/team/agent.reviewer.yaml
@@ -3,7 +3,7 @@
3	3	# with a verdict. It never changes the application's code: the coder does.
4	4	# Called by the coordinator (agent.yaml); also usable alone:
5	5	#
6		-# cd dev.team/workspace && ../../mm -config ../team/agent.reviewer.yaml
	6	+# cd demos/dev.team/workspace && ../../../mm -config ../team/agent.reviewer.yaml
7	7	#
8	8	# Model: Gemma 4 12B it (unsloth), Q4_K_M, 7.3 GB. A different model from the
9	9	# coder's on purpose: a reviewer that shares the author's model shares its

  # with a verdict. It never changes the application's code: the coder does.
  # Called by the coordinator (agent.yaml); also usable alone:
  #
--#   cd dev.team/workspace && ../../mm -config ../team/agent.reviewer.yaml
++#   cd demos/dev.team/workspace && ../../../mm -config ../team/agent.reviewer.yaml
  #
  # Model: Gemma 4 12B it (unsloth), Q4_K_M, 7.3 GB. A different model from the
  # coder's on purpose: a reviewer that shares the author's model shares its

renamed demos/dev.team/team/agent.tutor.yaml +1 -1 Viewed

similarity index 97%
rename from dev.team/team/agent.tutor.yaml
rename to demos/dev.team/team/agent.tutor.yaml
@@ -8,7 +8,7 @@
8	8	# - no sessions: an agent called through ask_agent runs with sessions off
9	9	# (AGENT_SESSIONS=off), the coordinator keeps the conversation.
10	10	#
11		-# cd dev.team/workspace && ../../mm -config ../team/agent.tutor.yaml # alone, with sessions
	11	+# cd demos/dev.team/workspace && ../../../mm -config ../team/agent.tutor.yaml # alone, with sessions
12	12
13	13	provider: llmman
14	14	#model: hf.co/JetBrains/Mellum2-12B-A2.5B-Instruct-GGUF-Q4_K_M:Q4_K_M

  #   - no sessions: an agent called through ask_agent runs with sessions off
  #     (AGENT_SESSIONS=off), the coordinator keeps the conversation.
  #
--#   cd dev.team/workspace && ../../mm -config ../team/agent.tutor.yaml      # alone, with sessions
++#   cd demos/dev.team/workspace && ../../../mm -config ../team/agent.tutor.yaml      # alone, with sessions
  provider: llmman
  #model: hf.co/JetBrains/Mellum2-12B-A2.5B-Instruct-GGUF-Q4_K_M:Q4_K_M

renamed demos/dev.team/team/agent.yaml +4 -4 Viewed

similarity index 96%
rename from dev.team/team/agent.yaml
rename to demos/dev.team/team/agent.yaml
@@ -15,13 +15,13 @@
15	15	# reloads the coordinator's 4B by itself to read the answer. Peak: one 12B
16	16	# model, ~8 GB + its KV cache at 32k.
17	17	#
18		-# This file lives in dev.team/team/, mounted READ-ONLY in the sandbox
19		-# (sbxenv.yaml); the team works in dev.team/workspace/. Run it from there:
	18	+# This file lives in demos/dev.team/team/, mounted READ-ONLY in the sandbox
	19	+# (sbxenv.yaml); the team works in demos/dev.team/workspace/. Run it from there:
20	20	#
21	21	# sandbox: ./start-zed.sh (AGENT_CONFIG points here), then in workspace/:
22	22	# mm -tui
23		-# host: cd dev.team/workspace
24		-# ../../mm -config ../team/agent.yaml -tui
	23	+# host: cd demos/dev.team/workspace
	24	+# ../../../mm -config ../team/agent.yaml -tui
25	25
26	26	# ─── Model and server ────────────────────────────────────────────────────────
27	27

  # reloads the coordinator's 4B by itself to read the answer. Peak: one 12B
  # model, ~8 GB + its KV cache at 32k.
  #
--# This file lives in dev.team/team/, mounted READ-ONLY in the sandbox
++# This file lives in demos/dev.team/team/, mounted READ-ONLY in the sandbox
--# (sbxenv.yaml); the team works in dev.team/workspace/. Run it from there:
++# (sbxenv.yaml); the team works in demos/dev.team/workspace/. Run it from there:
  #
  #   sandbox:  ./start-zed.sh  (AGENT_CONFIG points here), then in workspace/:
  #             mm -tui
--#   host:     cd dev.team/workspace
++#   host:     cd demos/dev.team/workspace
--#             ../../mm -config ../team/agent.yaml -tui
++#             ../../../mm -config ../team/agent.yaml -tui
  # ─── Model and server ────────────────────────────────────────────────────────

renamed demos/dev.team/team/hooks/gofmt.js +0 -0 Viewed

similarity index 100%
rename from dev.team/team/hooks/gofmt.js
rename to demos/dev.team/team/hooks/gofmt.js

similarity index 100%
rename from dev.team/team/hooks/gofmt.js
rename to demos/dev.team/team/hooks/gofmt.js

renamed demos/dev.team/team/hooks/unload.js +0 -0 Viewed

similarity index 100%
rename from dev.team/team/hooks/unload.js
rename to demos/dev.team/team/hooks/unload.js

similarity index 100%
rename from dev.team/team/hooks/unload.js
rename to demos/dev.team/team/hooks/unload.js

renamed demos/dev.team/workspace/.gitignore +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/.gitignore
rename to demos/dev.team/workspace/.gitignore

similarity index 100%
rename from dev.team/workspace/.gitignore
rename to demos/dev.team/workspace/.gitignore

renamed demos/dev.team/workspace/.gitkeep +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/.gitkeep
rename to demos/dev.team/workspace/.gitkeep

similarity index 100%
rename from dev.team/workspace/.gitkeep
rename to demos/dev.team/workspace/.gitkeep

renamed demos/dev.team/workspace/README.md +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/README.md
rename to demos/dev.team/workspace/README.md

similarity index 100%
rename from dev.team/workspace/README.md
rename to demos/dev.team/workspace/README.md

renamed demos/dev.team/workspace/go.mod +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/go.mod
rename to demos/dev.team/workspace/go.mod

similarity index 100%
rename from dev.team/workspace/go.mod
rename to demos/dev.team/workspace/go.mod

renamed demos/dev.team/workspace/go.sum +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/go.sum
rename to demos/dev.team/workspace/go.sum

similarity index 100%
rename from dev.team/workspace/go.sum
rename to demos/dev.team/workspace/go.sum

renamed demos/dev.team/workspace/internal/app/db.go +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/internal/app/db.go
rename to demos/dev.team/workspace/internal/app/db.go

similarity index 100%
rename from dev.team/workspace/internal/app/db.go
rename to demos/dev.team/workspace/internal/app/db.go

renamed demos/dev.team/workspace/internal/app/handlers.go +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/internal/app/handlers.go
rename to demos/dev.team/workspace/internal/app/handlers.go

similarity index 100%
rename from dev.team/workspace/internal/app/handlers.go
rename to demos/dev.team/workspace/internal/app/handlers.go

renamed demos/dev.team/workspace/internal/app/models.go +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/internal/app/models.go
rename to demos/dev.team/workspace/internal/app/models.go

similarity index 100%
rename from dev.team/workspace/internal/app/models.go
rename to demos/dev.team/workspace/internal/app/models.go

renamed demos/dev.team/workspace/internal/app/review_test.go +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/internal/app/review_test.go
rename to demos/dev.team/workspace/internal/app/review_test.go

similarity index 100%
rename from dev.team/workspace/internal/app/review_test.go
rename to demos/dev.team/workspace/internal/app/review_test.go

renamed demos/dev.team/workspace/internal/app/templates.go +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/internal/app/templates.go
rename to demos/dev.team/workspace/internal/app/templates.go

similarity index 100%
rename from dev.team/workspace/internal/app/templates.go
rename to demos/dev.team/workspace/internal/app/templates.go

renamed demos/dev.team/workspace/review_test.go +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/review_test.go
rename to demos/dev.team/workspace/review_test.go

similarity index 100%
rename from dev.team/workspace/review_test.go
rename to demos/dev.team/workspace/review_test.go

renamed demos/dev.team/workspace/templates/form.html +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/templates/form.html
rename to demos/dev.team/workspace/templates/form.html

similarity index 100%
rename from dev.team/workspace/templates/form.html
rename to demos/dev.team/workspace/templates/form.html

renamed demos/dev.team/workspace/templates/layout.html +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/templates/layout.html
rename to demos/dev.team/workspace/templates/layout.html

similarity index 100%
rename from dev.team/workspace/templates/layout.html
rename to demos/dev.team/workspace/templates/layout.html

renamed demos/dev.team/workspace/templates/list.html +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/templates/list.html
rename to demos/dev.team/workspace/templates/list.html

similarity index 100%
rename from dev.team/workspace/templates/list.html
rename to demos/dev.team/workspace/templates/list.html

renamed demos/dev.team/workspace/templates/style.css +0 -0 Viewed

similarity index 100%
rename from dev.team/workspace/templates/style.css
rename to demos/dev.team/workspace/templates/style.css

similarity index 100%
rename from dev.team/workspace/templates/style.css
rename to demos/dev.team/workspace/templates/style.css

renamed demos/use-with-sbx/AGENTS.md +0 -0 Viewed

similarity index 100%
rename from sbx/AGENTS.md
rename to demos/use-with-sbx/AGENTS.md

similarity index 100%
rename from sbx/AGENTS.md
rename to demos/use-with-sbx/AGENTS.md

renamed demos/use-with-sbx/README.md +0 -0 Viewed

similarity index 100%
rename from sbx/README.md
rename to demos/use-with-sbx/README.md

similarity index 100%
rename from sbx/README.md
rename to demos/use-with-sbx/README.md

renamed demos/use-with-sbx/agent.lucy.yaml +2 -2 Viewed

similarity index 99%
rename from sbx/agent.lucy.yaml
rename to demos/use-with-sbx/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 sbx/.
80		-skillsDir: ../skills
	79	+# The path is relative to the CURRENT DIRECTORY: run the agent from demos/use-with-sbx/.
	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 sbx/.
++# The path is relative to the CURRENT DIRECTORY: run the agent from demos/use-with-sbx/.
--skillsDir: ../skills
++skillsDir: ../../skills
  # Persistent sessions, per project.
  # When enabled, every conversation is saved as one JSON file under `dir`.

renamed demos/use-with-sbx/agent.yaml +2 -2 Viewed

similarity index 99%
rename from sbx/agent.yaml
rename to demos/use-with-sbx/agent.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 sbx/.
80		-skillsDir: ../skills
	79	+# The path is relative to the CURRENT DIRECTORY: run the agent from demos/use-with-sbx/.
	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 sbx/.
++# The path is relative to the CURRENT DIRECTORY: run the agent from demos/use-with-sbx/.
--skillsDir: ../skills
++skillsDir: ../../skills
  # Persistent sessions, per project.
  # When enabled, every conversation is saved as one JSON file under `dir`.

renamed demos/use-with-sbx/kits/cli-tools/cli-tools.dockerfile +0 -0 Viewed

similarity index 100%
rename from sbx/kits/cli-tools/cli-tools.dockerfile
rename to demos/use-with-sbx/kits/cli-tools/cli-tools.dockerfile

similarity index 100%
rename from sbx/kits/cli-tools/cli-tools.dockerfile
rename to demos/use-with-sbx/kits/cli-tools/cli-tools.dockerfile

renamed demos/use-with-sbx/kits/cli-tools/cli-tools.yaml +0 -0 Viewed

similarity index 100%
rename from sbx/kits/cli-tools/cli-tools.yaml
rename to demos/use-with-sbx/kits/cli-tools/cli-tools.yaml

similarity index 100%
rename from sbx/kits/cli-tools/cli-tools.yaml
rename to demos/use-with-sbx/kits/cli-tools/cli-tools.yaml

renamed demos/use-with-sbx/kits/go-toolchain/go-context.md +0 -0 Viewed

similarity index 100%
rename from sbx/kits/go-toolchain/go-context.md
rename to demos/use-with-sbx/kits/go-toolchain/go-context.md

similarity index 100%
rename from sbx/kits/go-toolchain/go-context.md
rename to demos/use-with-sbx/kits/go-toolchain/go-context.md

renamed demos/use-with-sbx/kits/go-toolchain/go-toolchain.dockerfile +0 -0 Viewed

similarity index 100%
rename from sbx/kits/go-toolchain/go-toolchain.dockerfile
rename to demos/use-with-sbx/kits/go-toolchain/go-toolchain.dockerfile

similarity index 100%
rename from sbx/kits/go-toolchain/go-toolchain.dockerfile
rename to demos/use-with-sbx/kits/go-toolchain/go-toolchain.dockerfile

renamed demos/use-with-sbx/kits/go-toolchain/go-toolchain.yaml +0 -0 Viewed

similarity index 100%
rename from sbx/kits/go-toolchain/go-toolchain.yaml
rename to demos/use-with-sbx/kits/go-toolchain/go-toolchain.yaml

similarity index 100%
rename from sbx/kits/go-toolchain/go-toolchain.yaml
rename to demos/use-with-sbx/kits/go-toolchain/go-toolchain.yaml

deleted dev.team/workspace/cmd/issueapp/main.go +0 -29 Viewed

deleted file mode 100644
@@ -1,29 +0,0 @@
1		-package main
2		-
3		-import (
4		- "flag"
5		- "fmt"
6		- "log"
7		-
8		- "issueapp/internal/app"
9		-)
10		-
11		-const dbPath = "issues.db"
12		-
13		-func main() {
14		- port := flag.Int("port", 8080, "HTTP port to listen on")
15		- flag.Parse()
16		-
17		- if err := app.InitDB(dbPath); err != nil {
18		- log.Fatalf("failed to init database: %v", err)
19		- }
20		- defer app.CloseDB()
21		-
22		- r := app.NewRouter()
23		-
24		- addr := fmt.Sprintf(":%d", *port)
25		- log.Println("listening on http://localhost" + addr)
26		- if err := r.Run(addr); err != nil {
27		- log.Fatalf("server error: %v", err)
28		- }
29		-}

--package main
--
--import (
--	"flag"
--	"fmt"
--	"log"
--
--	"issueapp/internal/app"
--)
--
--const dbPath = "issues.db"
--
--func main() {
--	port := flag.Int("port", 8080, "HTTP port to listen on")
--	flag.Parse()
--
--	if err := app.InitDB(dbPath); err != nil {
--		log.Fatalf("failed to init database: %v", err)
--	}
--	defer app.CloseDB()
--
--	r := app.NewRouter()
--
--	addr := fmt.Sprintf(":%d", *port)
--	log.Println("listening on http://localhost" + addr)
--	if err := r.Run(addr); err != nil {
--		log.Fatalf("server error: %v", err)
--	}
--}

modified docs/en/README.md +1 -1 Viewed

@@ -28,7 +28,7 @@ This documentation is organised along the four [Diátaxis](https://diataxis.fr)
28	28	- [Confirm tool calls before they run](how-to/confirm-tool-calls.md) — `yolo: false`, the four answers, `AGENT_YOLO`, who decides with `mmConfigs`
29	29	- [Let the agent ask you questions](how-to/let-the-agent-ask-you.md) — `ask_user`: answer in the terminal, the window or an editor, turn it off, decide for the agents yours calls (`askUserTool`, `mmConfigs.<name>.askUser`, `AGENT_ASK_USER`)
30	30	- [Run mini-me in a container](how-to/run-in-a-container.md) — `mm dockerinit`: a Dockerfile with the latest release, not root, and a compose file
31		-- [Run mini-me in a Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — `mm sbxinit` for a sbxenv.yaml; 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
	31	+- [Run mini-me in a Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — `mm sbxinit` for a sbxenv.yaml; the `mini-me` kit from [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), the `go-toolchain` and `cli-tools` mixins under `demos/use-with-sbx/`, window mode and editor
32	32	- [Add a skill](how-to/add-a-skill.md)
33	33	- [Declare a custom tool](how-to/declare-a-custom-tool.md)
34	34	- [Write a custom tool as a WebAssembly module](how-to/write-a-wasm-tool.md)

  - [Confirm tool calls before they run](how-to/confirm-tool-calls.md) — `yolo: false`, the four answers, `AGENT_YOLO`, who decides with `mmConfigs`
  - [Let the agent ask you questions](how-to/let-the-agent-ask-you.md) — `ask_user`: answer in the terminal, the window or an editor, turn it off, decide for the agents yours calls (`askUserTool`, `mmConfigs.<name>.askUser`, `AGENT_ASK_USER`)
  - [Run mini-me in a container](how-to/run-in-a-container.md) — `mm dockerinit`: a Dockerfile with the latest release, not root, and a compose file
--- [Run mini-me in a Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — `mm sbxinit` for a sbxenv.yaml; 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 in a Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — `mm sbxinit` for a sbxenv.yaml; the `mini-me` kit from [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), the `go-toolchain` and `cli-tools` mixins under `demos/use-with-sbx/`, window mode and editor
  - [Add a skill](how-to/add-a-skill.md)
  - [Declare a custom tool](how-to/declare-a-custom-tool.md)
  - [Write a custom tool as a WebAssembly module](how-to/write-a-wasm-tool.md)

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

@@ -2,15 +2,15 @@
2	2
3	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		-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`.
	5	+Everything lives under [`demos/use-with-sbx/`](../../../demos/use-with-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	7	\| Piece \| Where \| What it is \|
8	8	\|---\|---\|---\|
9	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). \|
	10	+\| `go-toolchain` \| `demos/use-with-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` \| `demos/use-with-sbx/kits/cli-tools/` \| A mixin: `rg`, `bat` and `eza` as static binaries. No runtime network. \|
	12	+\| `agent.yaml`, `agent.lucy.yaml` \| `demos/use-with-sbx/` \| Two `mm` configurations for llmman (Jan-nano, Lucy). \|
	13	+\| `AGENTS.md` \| `demos/use-with-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). \|
14	14
15	15	## Steps
16	16
@@ -24,10 +24,10 @@ sbx settings set kit.allowedSources '["docker.io/","git.rickub.com/bots-garden/"
24	24
25	25	### 2. Window mode in the terminal
26	26
27		-From the directory you want `mm` to work on — `sbx/` itself, to use its configurations and its `AGENTS.md`:
	27	+From the directory you want `mm` to work on — `demos/use-with-sbx/` itself, to use its configurations and its `AGENTS.md`:
28	28
29	29	```bash
30		-cd sbx
	30	+cd demos/use-with-sbx
31	31	RELEASE=v0.0.1
32	32	REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
33	33	sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me"
@@ -55,7 +55,7 @@ An editor talks to `mm -acp` over raw stdin and stdout, which `sbx run` cannot c
55	55	RELEASE=v0.0.1
56	56	REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
57	57	sbx create --name mm-acp "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" . \
58		- --kit /path/to/mini-me/sbx/kits/go-toolchain
	58	+ --kit /path/to/mini-me/demos/use-with-sbx/kits/go-toolchain
59	59	```
60	60
61	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 `/`):
@@ -63,7 +63,7 @@ An editor talks to `mm -acp` over raw stdin and stdout, which `sbx run` cannot c
63	63	```bash
64	64	git clone https://git.rickub.com/bots-garden/mini-me-kit.git /path/to/mini-me-kit
65	65	sbx create --name mm-acp /path/to/mini-me-kit/mini-me . \
66		- --kit /path/to/mini-me/sbx/kits/go-toolchain
	66	+ --kit /path/to/mini-me/demos/use-with-sbx/kits/go-toolchain
67	67	```
68	68
69	69	The workspace (`.`) is fixed at creation: one sandbox per project, each with its own `--name`.
@@ -158,13 +158,13 @@ sbx env create --force --env-arg PROJECT_DIR="$PWD"
158	158	sbx env rm --force --env-arg PROJECT_DIR="$PWD"
159	159	```
160	160
161		-`mm sbxinit` does not generate this form, because it makes the file longer for a case most projects do not have. Running `mm sbxinit` again and answering `yes` replaces these additions. [`dev.team/sbxenv.yaml`](../../../dev.team/sbxenv.yaml) is a complete example.
	161	+`mm sbxinit` does not generate this form, because it makes the file longer for a case most projects do not have. Running `mm sbxinit` again and answering `yes` replaces these additions. [`demos/dev.team/sbxenv.yaml`](../../../demos/dev.team/sbxenv.yaml) is a complete example.
162	162
163	163	## The model server stays on the host
164	164
165	165	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.
166	166
167		-- 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`).
	167	+- 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 `demos/use-with-sbx/` use llmman (`fallback: http://host.docker.internal:17434/v1`).
168	168	- For another port — llama-server's `8080`, for instance — add it to the kit's `network-policy` capability, or allow it for one sandbox:
169	169
170	170	```bash

  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.
--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 [`demos/use-with-sbx/`](../../../demos/use-with-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`.
  | 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`. |
++| `go-toolchain` | `demos/use-with-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. |
++| `cli-tools` | `demos/use-with-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). |
++| `agent.yaml`, `agent.lucy.yaml` | `demos/use-with-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). |
++| `AGENTS.md` | `demos/use-with-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). |
  ## Steps
  ### 2. Window mode in the terminal
--From the directory you want `mm` to work on — `sbx/` itself, to use its configurations and its `AGENTS.md`:
++From the directory you want `mm` to work on — `demos/use-with-sbx/` itself, to use its configurations and its `AGENTS.md`:
  ```bash
--cd sbx
++cd demos/use-with-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"
     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
++       --kit /path/to/mini-me/demos/use-with-sbx/kits/go-toolchain
     ```
     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
     git clone https://git.rickub.com/bots-garden/mini-me-kit.git /path/to/mini-me-kit
     sbx create --name mm-acp /path/to/mini-me-kit/mini-me . \
--       --kit /path/to/mini-me/sbx/kits/go-toolchain
++       --kit /path/to/mini-me/demos/use-with-sbx/kits/go-toolchain
     ```
     The workspace (`.`) is fixed at creation: one sandbox per project, each with its own `--name`.
  sbx env rm --force --env-arg PROJECT_DIR="$PWD"
  ```
--`mm sbxinit` does not generate this form, because it makes the file longer for a case most projects do not have. Running `mm sbxinit` again and answering `yes` replaces these additions. [`dev.team/sbxenv.yaml`](../../../dev.team/sbxenv.yaml) is a complete example.
++`mm sbxinit` does not generate this form, because it makes the file longer for a case most projects do not have. Running `mm sbxinit` again and answering `yes` replaces these additions. [`demos/dev.team/sbxenv.yaml`](../../../demos/dev.team/sbxenv.yaml) is a complete example.
  ## 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.
--- 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`).
++- 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 `demos/use-with-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:
    ```bash

modified docs/en/reference/cli.md +1 -1 Viewed

@@ -40,7 +40,7 @@ mm v0.1.7 (go1.26.5, darwin/arm64)
40	40
41	41	\| Where it comes from \| What you see \|
42	42	\|---\|---\|
43		-\| A release binary, stamped at build time by `02-build-releases.sh` \| The tag: `v0.1.7` \|
	43	+\| A release binary, stamped at build time by `local-ci-2-build.sh` \| The tag: `v0.1.7` \|
44	44	\| `go install`ed from a tagged version \| That tag \|
45	45	\| Built by hand from a working tree (`go build`, `./install.sh`) \| The short commit, `9073268`, with `+dirty` when the tree had uncommitted changes \|
46	46	\| Built with `-buildvcs=false` \| `unknown` \|

  | Where it comes from | What you see |
  |---|---|
--| A release binary, stamped at build time by `02-build-releases.sh` | The tag: `v0.1.7` |
++| A release binary, stamped at build time by `local-ci-2-build.sh` | The tag: `v0.1.7` |
  | `go install`ed from a tagged version | That tag |
  | Built by hand from a working tree (`go build`, `./install.sh`) | The short commit, `9073268`, with `+dirty` when the tree had uncommitted changes |
  | Built with `-buildvcs=false` | `unknown` |

modified docs/fr/README.md +1 -1 Viewed

@@ -28,7 +28,7 @@ Cette documentation est organisée selon les quatre quadrants [Diátaxis](https:
28	28	- [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`
29	29	- [Laisser l'agent vous poser des questions](how-to/let-the-agent-ask-you.md) — `ask_user` : répondre dans le terminal, la fenêtre ou un éditeur, couper l'outil, décider pour les agents que le vôtre appelle (`askUserTool`, `mmConfigs.<nom>.askUser`, `AGENT_ASK_USER`)
30	30	- [Faire tourner mini-me dans un conteneur](how-to/run-in-a-container.md) — `mm dockerinit` : un Dockerfile avec la dernière version, sans root, et un fichier compose
31		-- [Faire tourner mini-me dans un Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — `mm sbxinit` pour un sbxenv.yaml ; 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
	31	+- [Faire tourner mini-me dans un Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — `mm sbxinit` pour un sbxenv.yaml ; le kit `mini-me` de [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), les mixins `go-toolchain` et `cli-tools` sous `demos/use-with-sbx/`, mode fenêtre et éditeur
32	32	- [Ajouter un skill](how-to/add-a-skill.md)
33	33	- [Déclarer un outil personnalisé](how-to/declare-a-custom-tool.md)
34	34	- [Écrire un outil personnalisé sous forme de module WebAssembly](how-to/write-a-wasm-tool.md)

  - [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`
  - [Laisser l'agent vous poser des questions](how-to/let-the-agent-ask-you.md) — `ask_user` : répondre dans le terminal, la fenêtre ou un éditeur, couper l'outil, décider pour les agents que le vôtre appelle (`askUserTool`, `mmConfigs.<nom>.askUser`, `AGENT_ASK_USER`)
  - [Faire tourner mini-me dans un conteneur](how-to/run-in-a-container.md) — `mm dockerinit` : un Dockerfile avec la dernière version, sans root, et un fichier compose
--- [Faire tourner mini-me dans un Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — `mm sbxinit` pour un sbxenv.yaml ; 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 dans un Docker Sandbox](how-to/run-in-a-docker-sandbox.md) — `mm sbxinit` pour un sbxenv.yaml ; le kit `mini-me` de [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), les mixins `go-toolchain` et `cli-tools` sous `demos/use-with-sbx/`, mode fenêtre et éditeur
  - [Ajouter un skill](how-to/add-a-skill.md)
  - [Déclarer un outil personnalisé](how-to/declare-a-custom-tool.md)
  - [Écrire un outil personnalisé sous forme de module WebAssembly](how-to/write-a-wasm-tool.md)

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

@@ -2,15 +2,15 @@
2	2
3	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		-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`.
	5	+Tout se trouve sous [`demos/use-with-sbx/`](../../../demos/use-with-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	7	\| Élément \| Où \| Ce que c'est \|
8	8	\|---\|---\|---\|
9	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). \|
	10	+\| `go-toolchain` \| `demos/use-with-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` \| `demos/use-with-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` \| `demos/use-with-sbx/` \| Deux configurations `mm` pour llmman (Jan-nano, Lucy). \|
	13	+\| `AGENTS.md` \| `demos/use-with-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). \|
14	14
15	15	## Étapes
16	16
@@ -24,10 +24,10 @@ sbx settings set kit.allowedSources '["docker.io/","git.rickub.com/bots-garden/"
24	24
25	25	### 2. Mode fenêtre dans le terminal
26	26
27		-Depuis le dossier sur lequel `mm` doit travailler — `sbx/` lui-même, pour utiliser ses configurations et son `AGENTS.md` :
	27	+Depuis le dossier sur lequel `mm` doit travailler — `demos/use-with-sbx/` lui-même, pour utiliser ses configurations et son `AGENTS.md` :
28	28
29	29	```bash
30		-cd sbx
	30	+cd demos/use-with-sbx
31	31	RELEASE=v0.0.1
32	32	REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
33	33	sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me"
@@ -55,7 +55,7 @@ Un éditeur parle à `mm -acp` par stdin et stdout bruts, ce que `sbx run` ne pe
55	55	RELEASE=v0.0.1
56	56	REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
57	57	sbx create --name mm-acp "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" . \
58		- --kit /chemin/vers/mini-me/sbx/kits/go-toolchain
	58	+ --kit /chemin/vers/mini-me/demos/use-with-sbx/kits/go-toolchain
59	59	```
60	60
61	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 `/`) :
@@ -63,7 +63,7 @@ Un éditeur parle à `mm -acp` par stdin et stdout bruts, ce que `sbx run` ne pe
63	63	```bash
64	64	git clone https://git.rickub.com/bots-garden/mini-me-kit.git /chemin/vers/mini-me-kit
65	65	sbx create --name mm-acp /chemin/vers/mini-me-kit/mini-me . \
66		- --kit /chemin/vers/mini-me/sbx/kits/go-toolchain
	66	+ --kit /chemin/vers/mini-me/demos/use-with-sbx/kits/go-toolchain
67	67	```
68	68
69	69	L'espace de travail (`.`) est fixé à la création : un sandbox par projet, chacun avec son propre `--name`.
@@ -158,13 +158,13 @@ sbx env create --force --env-arg PROJECT_DIR="$PWD"
158	158	sbx env rm --force --env-arg PROJECT_DIR="$PWD"
159	159	```
160	160
161		-`mm sbxinit` ne génère pas cette forme, car elle allonge le fichier pour un cas que la plupart des projets n'ont pas. Relancer `mm sbxinit` en répondant `yes` remplace ces ajouts. [`dev.team/sbxenv.yaml`](../../../dev.team/sbxenv.yaml) en est un exemple complet.
	161	+`mm sbxinit` ne génère pas cette forme, car elle allonge le fichier pour un cas que la plupart des projets n'ont pas. Relancer `mm sbxinit` en répondant `yes` remplace ces ajouts. [`demos/dev.team/sbxenv.yaml`](../../../demos/dev.team/sbxenv.yaml) en est un exemple complet.
162	162
163	163	## Le serveur de modèles reste sur l'hôte
164	164
165	165	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.
166	166
167		-- 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`).
	167	+- 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 `demos/use-with-sbx/` utilisent llmman (`fallback: http://host.docker.internal:17434/v1`).
168	168	- 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 :
169	169
170	170	```bash

  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.
--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 se trouve sous [`demos/use-with-sbx/`](../../../demos/use-with-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`.
  | É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`. |
++| `go-toolchain` | `demos/use-with-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. |
++| `cli-tools` | `demos/use-with-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). |
++| `agent.yaml`, `agent.lucy.yaml` | `demos/use-with-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). |
++| `AGENTS.md` | `demos/use-with-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). |
  ## Étapes
  ### 2. Mode fenêtre dans le terminal
--Depuis le dossier sur lequel `mm` doit travailler — `sbx/` lui-même, pour utiliser ses configurations et son `AGENTS.md` :
++Depuis le dossier sur lequel `mm` doit travailler — `demos/use-with-sbx/` lui-même, pour utiliser ses configurations et son `AGENTS.md` :
  ```bash
--cd sbx
++cd demos/use-with-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"
     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
++       --kit /chemin/vers/mini-me/demos/use-with-sbx/kits/go-toolchain
     ```
     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
     git clone https://git.rickub.com/bots-garden/mini-me-kit.git /chemin/vers/mini-me-kit
     sbx create --name mm-acp /chemin/vers/mini-me-kit/mini-me . \
--       --kit /chemin/vers/mini-me/sbx/kits/go-toolchain
++       --kit /chemin/vers/mini-me/demos/use-with-sbx/kits/go-toolchain
     ```
     L'espace de travail (`.`) est fixé à la création : un sandbox par projet, chacun avec son propre `--name`.
  sbx env rm --force --env-arg PROJECT_DIR="$PWD"
  ```
--`mm sbxinit` ne génère pas cette forme, car elle allonge le fichier pour un cas que la plupart des projets n'ont pas. Relancer `mm sbxinit` en répondant `yes` remplace ces ajouts. [`dev.team/sbxenv.yaml`](../../../dev.team/sbxenv.yaml) en est un exemple complet.
++`mm sbxinit` ne génère pas cette forme, car elle allonge le fichier pour un cas que la plupart des projets n'ont pas. Relancer `mm sbxinit` en répondant `yes` remplace ces ajouts. [`demos/dev.team/sbxenv.yaml`](../../../demos/dev.team/sbxenv.yaml) en est un exemple complet.
  ## 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 redirige vers votre machine.
--- 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`).
++- 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 `demos/use-with-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 :
    ```bash

modified docs/fr/reference/cli.md +1 -1 Viewed

@@ -40,7 +40,7 @@ mm v0.1.7 (go1.26.5, darwin/arm64)
40	40
41	41	\| D'où elle vient \| Ce que vous voyez \|
42	42	\|---\|---\|
43		-\| Un binaire de release, estampillé à la construction par `02-build-releases.sh` \| Le tag : `v0.1.7` \|
	43	+\| Un binaire de release, estampillé à la construction par `local-ci-2-build.sh` \| Le tag : `v0.1.7` \|
44	44	\| Installé par `go install` depuis une version taguée \| Ce tag \|
45	45	\| Construit à la main depuis un arbre de travail (`go build`, `./install.sh`) \| Le commit court, `9073268`, suivi de `+dirty` si l'arbre avait des modifications non validées \|
46	46	\| Construit avec `-buildvcs=false` \| `unknown` \|

  | D'où elle vient | Ce que vous voyez |
  |---|---|
--| Un binaire de release, estampillé à la construction par `02-build-releases.sh` | Le tag : `v0.1.7` |
++| Un binaire de release, estampillé à la construction par `local-ci-2-build.sh` | Le tag : `v0.1.7` |
  | Installé par `go install` depuis une version taguée | Ce tag |
  | Construit à la main depuis un arbre de travail (`go build`, `./install.sh`) | Le commit court, `9073268`, suivi de `+dirty` si l'arbre avait des modifications non validées |
  | Construit avec `-buildvcs=false` | `unknown` |

added guides/agent-settings-for-small-models.md +217 -0 Viewed

new file mode 100644
@@ -0,0 +1,217 @@
	1	+# Agent settings for small models (in plain words)
	2	+
	3	+[Version française](reglages-agents-petits-modeles.md)
	4	+
	5	+> This guide explains, without jargon, what each setting of a mini-me agent does, why it exists, what its default value is, and how to set it when you run a small language model locally (one that fits on your laptop, not a giant model in the cloud).
	6	+
	7	+## Why these settings exist
	8	+
	9	+A small local model (a few billion parameters, running on a consumer CPU/GPU) does not have the same weaknesses as a large cloud model:
	10	+
	11	+- it is slow, above all when it reads a long prompt ("prompt processing");
	12	+- it has a limited memory (context window), often 8k to 32k tokens, sometimes less;
	13	+- it loops or drifts more easily (repeats the same command, forgets what it already read, spins off in its reasoning);
	14	+- it can hallucinate the result of a command it never actually ran.
	15	+
	16	+The settings below are the safeguards that make up for this. They tell the agent "stop if you are too slow", "do not keep everything in memory", "do not go round in circles forever", "do not send back a wall of text that clogs your own memory".
	17	+
	18	+They go in the agent's YAML file (`agent.*.yaml`), under the same key names.
	19	+
	20	+---
	21	+
	22	+## 1. `contextWindow`: the size of the model's memory
	23	+
	24	+In plain words: the size of the model's "working memory", in tokens (one token ≈ 0.75 word). Everything the agent said, read and ran must fit in it. When it is full, room must be made (see the `context` section below).
	25	+
	26	+- Default value: `0`, meaning "I don't know, ask the server". If the server (llama.cpp, Docker Model Runner…) reports the context size it was configured with, mini-me uses it automatically.
	27	+- How to set it: usually, do not set it yourself when your server can report it: leave `0`. Set it by hand only when your server does not report it, and then use the real value you configured on the server (e.g. `-c 8192` on `llama-server` → `contextWindow: 8192`).
	28	+- For a small model: small models often come with an advertised window of 32k or more, but in practice their quality drops well before that limit. Knowing the real usable value keeps the context-compression calculations (section 8) reliable.
	29	+
	30	+---
	31	+
	32	+## 2. `firstTokenTimeout`: how long the model may take to start answering
	33	+
	34	+In plain words: before the model produces its first word, the server must read the whole prompt (the question + the history + the instructions). On a small local model, reading a 20-30k-token prompt can take several minutes. This setting says: "how long do I wait before deciding that it crashed?"
	35	+
	36	+- Default value: `3 minutes`.
	37	+- Special feature: when the server (llama.cpp) reports its reading progress meanwhile, the clock restarts at each report. So in practice it will not cut as long as the server is making progress: this timeout mostly protects against a real, silent hang.
	38	+- How to set it:
	39	+ - Small model (≤ 8B) with a good GPU: the default (3 min) is usually enough.
	40	+ - Larger model (15-30B), modest machine (CPU only, little VRAM), or very long prompts (big `AGENTS.md`, long history): raise it to `5m` or even `10m`.
	41	+ - Golden rule: never shorter than `watchdogTimeout` (see just below), or the protection makes no sense.
	42	+
	43	+---
	44	+
	45	+## 3. `watchdogTimeout`: the watchdog while the model generates
	46	+
	47	+In plain words: once the model has started answering (or using a tool), this setting checks that it keeps producing something regularly. If it stays silent longer than this, with nothing new coming out, mini-me decides the connection is stuck and cuts it.
	48	+
	49	+- Default value: `20 seconds`.
	50	+- Difference from `firstTokenTimeout`: `firstTokenTimeout` watches the start (reading the prompt), `watchdogTimeout` watches what follows (token-by-token generation, or a tool running). That is why `watchdogTimeout` is much shorter.
	51	+- How to set it:
	52	+ - If the agent has the `bash` tool and commands may legitimately take time (build, tests, downloads), raise this timeout together with `bashTimeout`: while a bash command runs, the watchdog keeps counting. If `bashTimeout` is `2m`, `watchdogTimeout` must be at least `2m` too, or mini-me would cut the command before it ends.
	53	+ - For a simple "chat" use without heavy tools: the default is fine, even on a slow small model (token-by-token generation is what counts, not overall speed).
	54	+
	55	+---
	56	+
	57	+## 4. `bashTimeout`: how long a shell command may run
	58	+
	59	+In plain words: when the agent runs a command (`bash`), this is the longest it may run before mini-me kills it, even if it has printed nothing.
	60	+
	61	+- Default value: `30 seconds`.
	62	+- How to set it:
	63	+ - Quick tasks (reading a file, `git status`, `ls`): the 30 s default is plenty.
	64	+ - Heavy tasks you expect (compiling, tests, installing dependencies, a long search): raise it generously, for example `2m`, `5m`, or more depending on the project.
	65	+ - Always raise `watchdogTimeout` at the same time (see section 3). It is the most common trap: a command is killed by the watchdog although `bashTimeout` gave it time.
	66	+ - This setting depends less on the size of the model than on the kind of project the agent works on.
	67	+
	68	+---
	69	+
	70	+## 5. `maxTurns`: how many model ↔ tool round trips one question may take
	71	+
	72	+In plain words: to answer one question, the agent may go round several times: "I run a command" → "I look at the result" → "I run another one" → and so on. This setting caps the number of rounds before mini-me stops the agent (so that it cannot loop forever).
	73	+
	74	+- Default value: `10`.
	75	+- Value actually used in the shipped configurations: `40`. Experience shows that 10 is often too low for realistic coding tasks with a small model, which needs more iterations (re-reading, fixing, trying again) than a large one.
	76	+- How to set it:
	77	+ - Narrow task, a single action expected (a factual question, one tool call): `8` to `15` is enough, and it protects better against loops.
	78	+ - General coding agent (exploring code, editing, testing): `40` to `60` is reasonable, especially with a small model that needs several tries.
	79	+ - The smaller or weaker the model, the more likely it is to loop without ever concluding: pair a generous `maxTurns` with good loop detection rather than setting a huge value "just in case".
	80	+
	81	+---
	82	+
	83	+## 6. `maxOutput`: the most a tool may send back to the model
	84	+
	85	+In plain words: if a `bash` command returns 500,000 characters (a big log file, for example), we do not want it to fill the model's whole memory at once. This setting truncates the result before the model sees it.
	86	+
	87	+- Default value: `16000` characters.
	88	+- How it truncates: not just by cutting the end. mini-me keeps the beginning of the output and up to 2000 characters of the end, because the useful information (an error, a summary) is often at the end of a long output.
	89	+- How to set it:
	90	+ - Small model with a small context window (8k-16k tokens): lower it, for example to `4000`-`8000`, so that one command cannot use up a third of the available memory.
	91	+ - Model with a large context window, or an agent that really needs to see whole outputs (e.g. analysing a big diff): you can raise it to `20000`-`30000`, but remember that every output "costs" tokens and brings forward the moment the context compression (section 8) kicks in.
	92	+
	93	+---
	94	+
	95	+## 7. `agentsMd`: how the agent reads its project instructions
	96	+
	97	+In plain words: `AGENTS.md` (or an equivalent file) holds the project's own instructions, which the agent must follow. This block controls whether and how that file is loaded.
	98	+
	99	+```yaml
	100	+agentsMd:
	101	+ enabled: true
	102	+ path: "AGENTS.md"
	103	+ maxChars: 0
	104	+```
	105	+
	106	+- `enabled`, default `true`: reads the file automatically.
	107	+- `path`, default `"AGENTS.md"`: the name or path of the file to read.
	108	+- `maxChars`, default `0` (= no limit).
	109	+
	110	+### The important point about `maxChars`
	111	+
	112	+It is not a truncation. When `AGENTS.md` is longer than `maxChars` characters, it is not cut: it is left out entirely (the source code says why: cutting in the middle could drop the very rule that matters). The start-up banner says so (`skipped (too long)`) rather than pretending the whole file was read.
	113	+
	114	+- How to set it:
	115	+ - Even without `maxChars`, mini-me warns you: the start-up banner warns when `AGENTS.md` takes 20 % or more of a known context window (estimate: number of characters ÷ 3.5). With a small model, that is the sign to shorten the file.
	116	+ - `maxChars` is a hard limit on top of that warning. With a small model and a small window, a long `AGENTS.md` can take a large share of the memory before the conversation even starts. Setting `maxChars` guarantees it never goes beyond: above it, the file is left out, the banner says so, and you know it must be shortened.
	117	+ - To compute a value: 20 % of the window × 3.5. Example: an 8192-token window → 20 % = 1638 tokens → about `maxChars: 5700`.
	118	+ - If your `AGENTS.md` is short (a few hundred lines at most) and your model has a comfortable window (32k+), you can leave `0`.
	119	+
	120	+---
	121	+
	122	+## 8. `context`: automatic compression of the history
	123	+
	124	+In plain words: as the conversation goes on, the history (questions, answers, command results) grows. On a small model with limited memory, there comes a point where it no longer fits. This block decides when and how the older exchanges are summarised automatically to make room, without losing the thread.
	125	+
	126	+```yaml
	127	+context:
	128	+ enabled: false
	129	+ threshold: 75
	130	+ maxMessages: 80
	131	+ keepLastTurns: 3
	132	+ summaryMaxTokens: 1200
	133	+ prompt: ""
	134	+ showStats: true
	135	+```
	136	+
	137	+\| Sub-setting \| Default \| What it does \| How to set it \|
	138	+\|---\|---\|---\|---\|
	139	+\| `enabled` \| `false` \| Turns automatic compression on. Even when it is off, you can still compress by hand (`/compact`). \| Turn it on (`true`) for any small local model: it is the main protection against a "full context" that makes the agent fail or degrade. \|
	140	+\| `threshold` \| `75` (%) \| Share of the context window beyond which compression starts. 75 % deliberately leaves a quarter of the memory free for the next question, the tool results and the answer. \| Not too low (you would compress too often and lose continuity); not too high (you risk filling up before compression can act). 70-80 % is a good range. \|
	141	+\| `maxMessages` \| `80` \| Fallback trigger based on the number of messages, used when the window size is unknown (`contextWindow: 0` and a server that does not say). One command = 2 messages (the call + the result), so 80 ≈ 30 commands of history. \| The code justifies 80 as roughly the point where a 12B local model starts to slow down. On a smaller model, you can lower it if the agent gets slower or confused before 80 messages. Set `0` to turn this trigger off when you are sure of `contextWindow`. \|
	142	+\| `keepLastTurns` \| `3` \| Number of most recent turns kept as they are (not summarised): that is where the agent is actively working, and summarising it would make the agent redo what it has just done. \| Keep at least `2`-`3`. Raise it a little (`4`-`5`) if the agent "forgets" a very recent action right after a compression. \|
	143	+\| `summaryMaxTokens` \| `1200` \| Largest summary generated to replace the old exchanges. The cap stops a runaway model from writing a summary that itself fills the window it was meant to empty. \| For a small model, do not raise it much: a summary must stay compact. `1200` suits most cases; go down to `600`-`800` to save even more room. \|
	144	+\| `prompt` \| `""` (built-in prompt) \| Replaces the prompt used to ask for the summary. \| Leave it empty unless you have a specific need (e.g. a summary that keeps a particular format). \|
	145	+\| `showStats` \| `true` \| Prints an information line after each compression (how many tokens were saved, etc.). \| Leave it on: it shows that compression does its job. Turn it off only for a quieter output. \|
	146	+
	147	+Practical tip: the summary is requested without the tools and without "reasoning" mode, precisely so that `summaryMaxTokens` is not wasted on thinking instead of a useful summary.
	148	+
	149	+---
	150	+
	151	+## Summary: typical profiles
	152	+
	153	+\| Situation \| `firstTokenTimeout` \| `watchdogTimeout` \| `bashTimeout` \| `maxTurns` \| `maxOutput` \| `context.enabled` \|
	154	+\|---\|---\|---\|---\|---\|---\|---\|
	155	+\| Small model (≤ 8B), short tasks/chat, no `bash` or commands under 20 s \| `3m` (default) \| `20s` (default) \| `30s` (default) \| `15` \| `8000` \| `true` \|
	156	+\| Small/medium model, general coding agent \| `5m` \| `2m` (aligned on bashTimeout) \| `2m` \| `40` \| `16000` \| `true` \|
	157	+\| Larger model or modest machine (CPU) \| `10m` \| `5m` \| `5m` \| `40`-`60` \| `16000`-`24000` \| `true` \|
	158	+
	159	+In the first row, `watchdogTimeout` (20 s) is shorter than `bashTimeout` (30 s): those are the defaults, and they only fit when no command runs longer than 20 s. As soon as the agent runs longer commands, align the two as in the other rows (section 3).
	160	+
	161	+These profiles are starting points, not absolute truths: adjust them by watching how your model actually behaves (does it loop, is it cut too early, does the context fill up too fast).
	162	+
	163	+---
	164	+
	165	+## 9. Sampling: how the model picks its words
	166	+
	167	+In plain words: "sampling" is the set of settings that control how the model picks the next word among all the ones it finds plausible. It decides whether the model is precise and predictable or creative and varied. Unlike the settings above (timeouts, quotas), sampling has no fixed structure in mini-me: it is a free list of keys (`sampling:` in the YAML) passed almost as is to the model's server.
	168	+
	169	+```yaml
	170	+sampling:
	171	+ temperature: 0.0
	172	+ top_p: 0.9
	173	+ max_tokens: 4096
	174	+```
	175	+
	176	+These are the only three keys mini-me sets by default. The others (`top_k`, `min_p`, `repeat_penalty`…) have no default: add them yourself if your server and model support them and you need them.
	177	+
	178	+### `temperature`: the "precise ↔ creative" dial
	179	+
	180	+In plain words: the closer it is to `0`, the more the model always picks the word it finds most likely (stable, reproducible answers, sometimes a little rigid). The higher it goes towards `1` (or beyond), the more it accepts less obvious words (more varied answers, but also more risk of mistakes and drift).
	181	+
	182	+- mini-me default: `0.0`, deliberately very low, because mini-me is designed as a coding agent, where precision and reproducibility matter, not creativity.
	183	+- How to set it for a small model:
	184	+ - An agent that runs commands, writes code, follows strict instructions: keep `0.0`-`0.2`. A small model already makes more mistakes and loops more than a large one; a low temperature reduces that risk.
	185	+ - A conversational or creative agent, or one that must rephrase or brainstorm: go up to `0.5`-`0.8`. Beyond `0.8`, a small model more easily turns incoherent.
	186	+
	187	+### `top_p` (nucleus sampling): how wide the choice is
	188	+
	189	+In plain words: instead of considering every possible word, the model only looks at the smallest group of words whose combined probability reaches this share. `top_p: 0.9` means "only consider the words that together cover 90 % of the probability; ignore the long tail of unlikely ones".
	190	+
	191	+- mini-me default: `0.9`.
	192	+- How to set it: together with a low `temperature`, `0.9` is already a good "safe" compromise for a small model. You can go down to `0.8` to cut odd detours further; there is no point going higher for a coding agent.
	193	+
	194	+### `top_k`: limiting the number of candidates (optional, no default in mini-me)
	195	+
	196	+In plain words: keep only the `k` most likely words at each step and ignore the rest, whatever `top_p` says.
	197	+
	198	+- How to set it: small models (often small Qwen, Gemma or Llama) do not all react to `top_k` the same way, and some model families explicitly recommend a value (for example `20`-`40`) in their model card. Check the metadata or recommendations of the GGUF model you use rather than guessing: a poorly chosen `top_k` can make a small model more repetitive or, on the contrary, more unstable.
	199	+
	200	+### `repeat_penalty` / `min_p`: against repetition (optional, no default in mini-me)
	201	+
	202	+In plain words: `repeat_penalty` penalises the model for reusing a word it used recently (useful against repetition loops, a classic weakness of small models). `min_p` is an alternative to `top_p` that drops the words whose probability is too low compared with the most likely word at that moment.
	203	+
	204	+- How to set them: these are typically the settings that vary most from one model family to another; there is no universal value. Good practice is to use the values the model card recommends (often in the GGUF metadata or the model's documentation) rather than improvising. If the agent repeats sentences or actions in a loop, this is often the first setting to adjust, together with mini-me's loop detector and `maxTurns` (section 5).
	205	+
	206	+### `max_tokens`: the longest an answer may be
	207	+
	208	+In plain words: how many tokens the model may generate in one answer before it is cut.
	209	+
	210	+- mini-me default: `4096`.
	211	+- How to set it: for a small model with a small context window, check that `max_tokens` leaves enough room in the window for the prompt itself: `max_tokens` + prompt size must not exceed `contextWindow`. Lower it (`1024`-`2048`) if your answers must stay short (e.g. classification, extraction); keep the default for an agent that writes code or longer explanations.
	212	+
	213	+### In short: mini-me's sampling philosophy
	214	+
	215	+mini-me assumes that a small local model is a coding agent first, so its default sampling favours precision and reproducibility (`temperature: 0.0`) over creativity. It is the safest starting point to limit mistakes, hallucinated command results and loops; loosen it yourself if your use is more conversational or creative.
	216	+
	217	+> mini-me has no automatic "sampling profile" per model family today: the defaults are generic and deliberately conservative. When you switch models, check these settings again rather than keeping another model's out of habit.

++# Agent settings for small models (in plain words)
++
++*[Version française](reglages-agents-petits-modeles.md)*
++
++> This guide explains, without jargon, what each setting of a mini-me agent does, why it exists, what its default value is, and how to set it **when you run a small language model locally** (one that fits on your laptop, not a giant model in the cloud).
++
++## Why these settings exist
++
++A small local model (a few billion parameters, running on a consumer CPU/GPU) does not have the same weaknesses as a large cloud model:
++
++- it is **slow**, above all when it reads a long prompt ("prompt processing");
++- it has a **limited memory (context window)**, often 8k to 32k tokens, sometimes less;
++- it **loops or drifts** more easily (repeats the same command, forgets what it already read, spins off in its reasoning);
++- it can **hallucinate** the result of a command it never actually ran.
++
++The settings below are the safeguards that make up for this. They tell the agent "stop if you are too slow", "do not keep everything in memory", "do not go round in circles forever", "do not send back a wall of text that clogs your own memory".
++
++They go in the agent's YAML file (`agent.*.yaml`), under the same key names.
++
++---
++
++## 1. `contextWindow`: the size of the model's memory
++
++**In plain words**: the size of the model's "working memory", in tokens (one token ≈ 0.75 word). Everything the agent said, read and ran must fit in it. When it is full, room must be made (see the `context` section below).
++
++- **Default value**: `0`, meaning "I don't know, ask the server". If the server (llama.cpp, Docker Model Runner…) reports the context size it was configured with, mini-me uses it automatically.
++- **How to set it**: usually, **do not set it yourself** when your server can report it: leave `0`. Set it by hand only when your server does not report it, and then use the real value you configured on the server (e.g. `-c 8192` on `llama-server` → `contextWindow: 8192`).
++- **For a small model**: small models often come with an advertised window of 32k or more, but **in practice their quality drops well before** that limit. Knowing the real usable value keeps the context-compression calculations (section 8) reliable.
++
++---
++
++## 2. `firstTokenTimeout`: how long the model may take to *start* answering
++
++**In plain words**: before the model produces its first word, the server must *read* the whole prompt (the question + the history + the instructions). On a small local model, reading a 20-30k-token prompt can take several minutes. This setting says: "how long do I wait before deciding that it crashed?"
++
++- **Default value**: `3 minutes`.
++- **Special feature**: when the server (llama.cpp) reports its reading progress meanwhile, the clock **restarts** at each report. So in practice it will not cut as long as the server is making progress: this timeout mostly protects against a real, silent hang.
++- **How to set it**:
++  - Small model (≤ 8B) with a good GPU: the default (3 min) is usually enough.
++  - Larger model (15-30B), modest machine (CPU only, little VRAM), or very long prompts (big `AGENTS.md`, long history): raise it to `5m` or even `10m`.
++  - Golden rule: **never shorter than `watchdogTimeout`** (see just below), or the protection makes no sense.
++
++---
++
++## 3. `watchdogTimeout`: the watchdog while the model *generates*
++
++**In plain words**: once the model has started answering (or using a tool), this setting checks that it keeps producing something regularly. If it stays silent longer than this, *with nothing new coming out*, mini-me decides the connection is stuck and cuts it.
++
++- **Default value**: `20 seconds`.
++- **Difference from `firstTokenTimeout`**: `firstTokenTimeout` watches the **start** (reading the prompt), `watchdogTimeout` watches **what follows** (token-by-token generation, or a tool running). That is why `watchdogTimeout` is much shorter.
++- **How to set it**:
++  - If the agent has the `bash` tool and commands may legitimately take time (build, tests, downloads), **raise this timeout together with `bashTimeout`**: while a bash command runs, the watchdog keeps counting. If `bashTimeout` is `2m`, `watchdogTimeout` must be at least `2m` too, or mini-me would cut the command before it ends.
++  - For a simple "chat" use without heavy tools: the default is fine, even on a slow small model (token-by-token generation is what counts, not overall speed).
++
++---
++
++## 4. `bashTimeout`: how long a shell command may run
++
++**In plain words**: when the agent runs a command (`bash`), this is the longest it may run before mini-me kills it, even if it has printed nothing.
++
++- **Default value**: `30 seconds`.
++- **How to set it**:
++  - Quick tasks (reading a file, `git status`, `ls`): the 30 s default is plenty.
++  - Heavy tasks you expect (compiling, tests, installing dependencies, a long search): raise it generously, for example `2m`, `5m`, or more depending on the project.
++  - **Always raise `watchdogTimeout` at the same time** (see section 3). It is the most common trap: a command is killed by the watchdog although `bashTimeout` gave it time.
++  - This setting depends less on the size of the model than on the kind of project the agent works on.
++
++---
++
++## 5. `maxTurns`: how many model ↔ tool round trips one question may take
++
++**In plain words**: to answer one question, the agent may go round several times: "I run a command" → "I look at the result" → "I run another one" → and so on. This setting caps the number of rounds before mini-me stops the agent (so that it cannot loop forever).
++
++- **Default value**: `10`.
++- **Value actually used in the shipped configurations**: `40`. Experience shows that 10 is often too low for realistic coding tasks with a small model, which needs more iterations (re-reading, fixing, trying again) than a large one.
++- **How to set it**:
++  - Narrow task, a single action expected (a factual question, one tool call): `8` to `15` is enough, and it protects better against loops.
++  - General coding agent (exploring code, editing, testing): `40` to `60` is reasonable, especially with a small model that needs several tries.
++  - The smaller or weaker the model, the more likely it is to loop without ever concluding: pair a generous `maxTurns` with good loop detection rather than setting a huge value "just in case".
++
++---
++
++## 6. `maxOutput`: the most a tool may send back to the model
++
++**In plain words**: if a `bash` command returns 500,000 characters (a big log file, for example), we do not want it to fill the model's whole memory at once. This setting truncates the result before the model sees it.
++
++- **Default value**: `16000` characters.
++- **How it truncates**: not just by cutting the end. mini-me keeps the **beginning** of the output and up to 2000 characters of the **end**, because the useful information (an error, a summary) is often at the end of a long output.
++- **How to set it**:
++  - Small model with a small context window (8k-16k tokens): **lower** it, for example to `4000`-`8000`, so that one command cannot use up a third of the available memory.
++  - Model with a large context window, or an agent that really needs to see whole outputs (e.g. analysing a big diff): you can raise it to `20000`-`30000`, but remember that every output "costs" tokens and brings forward the moment the context compression (section 8) kicks in.
++
++---
++
++## 7. `agentsMd`: how the agent reads its project instructions
++
++**In plain words**: `AGENTS.md` (or an equivalent file) holds the project's own instructions, which the agent must follow. This block controls whether and how that file is loaded.
++
++```yaml
++agentsMd:
++  enabled: true
++  path: "AGENTS.md"
++  maxChars: 0
++```
++
++- **`enabled`**, default `true`: reads the file automatically.
++- **`path`**, default `"AGENTS.md"`: the name or path of the file to read.
++- **`maxChars`**, default `0` (= no limit).
++
++### The important point about `maxChars`
++
++It is **not** a truncation. When `AGENTS.md` is longer than `maxChars` characters, it is **not cut**: it is **left out entirely** (the source code says why: cutting in the middle could drop the very rule that matters). The start-up banner says so (`skipped (too long)`) rather than pretending the whole file was read.
++
++- **How to set it**:
++  - **Even without `maxChars`, mini-me warns you**: the start-up banner warns when `AGENTS.md` takes **20 % or more** of a known context window (estimate: number of characters ÷ 3.5). With a small model, that is the sign to shorten the file.
++  - **`maxChars` is a hard limit on top of that warning.** With a small model and a small window, a long `AGENTS.md` can take a large share of the memory before the conversation even starts. Setting `maxChars` guarantees it never goes beyond: above it, the file is left out, the banner says so, and you know it must be shortened.
++  - To compute a value: 20 % of the window × 3.5. Example: an 8192-token window → 20 % = 1638 tokens → about `maxChars: 5700`.
++  - If your `AGENTS.md` is short (a few hundred lines at most) and your model has a comfortable window (32k+), you can leave `0`.
++
++---
++
++## 8. `context`: automatic compression of the history
++
++**In plain words**: as the conversation goes on, the history (questions, answers, command results) grows. On a small model with limited memory, there comes a point where it no longer fits. This block decides **when** and **how** the older exchanges are summarised automatically to make room, without losing the thread.
++
++```yaml
++context:
++  enabled: false
++  threshold: 75
++  maxMessages: 80
++  keepLastTurns: 3
++  summaryMaxTokens: 1200
++  prompt: ""
++  showStats: true
++```
++
++| Sub-setting | Default | What it does | How to set it |
++|---|---|---|---|
++| `enabled` | `false` | Turns automatic compression on. Even when it is off, you can still compress by hand (`/compact`). | **Turn it on (`true`) for any small local model**: it is the main protection against a "full context" that makes the agent fail or degrade. |
++| `threshold` | `75` (%) | Share of the context window beyond which compression starts. 75 % deliberately leaves a quarter of the memory free for the next question, the tool results and the answer. | Not too low (you would compress too often and lose continuity); not too high (you risk filling up before compression can act). 70-80 % is a good range. |
++| `maxMessages` | `80` | Fallback trigger based on the *number* of messages, used when the window size is unknown (`contextWindow: 0` and a server that does not say). One command = 2 messages (the call + the result), so 80 ≈ 30 commands of history. | The code justifies 80 as roughly the point where a 12B local model starts to slow down. On a smaller model, you can lower it if the agent gets slower or confused before 80 messages. Set `0` to turn this trigger off when you are sure of `contextWindow`. |
++| `keepLastTurns` | `3` | Number of most recent turns kept **as they are** (not summarised): that is where the agent is actively working, and summarising it would make the agent redo what it has just done. | Keep at least `2`-`3`. Raise it a little (`4`-`5`) if the agent "forgets" a very recent action right after a compression. |
++| `summaryMaxTokens` | `1200` | Largest summary generated to replace the old exchanges. The cap stops a runaway model from writing a summary that itself fills the window it was meant to empty. | For a small model, do not raise it much: a summary must stay compact. `1200` suits most cases; go down to `600`-`800` to save even more room. |
++| `prompt` | `""` (built-in prompt) | Replaces the prompt used to ask for the summary. | Leave it empty unless you have a specific need (e.g. a summary that keeps a particular format). |
++| `showStats` | `true` | Prints an information line after each compression (how many tokens were saved, etc.). | Leave it on: it shows that compression does its job. Turn it off only for a quieter output. |
++
++**Practical tip**: the summary is requested **without the tools and without "reasoning" mode**, precisely so that `summaryMaxTokens` is not wasted on thinking instead of a useful summary.
++
++---
++
++## Summary: typical profiles
++
++| Situation | `firstTokenTimeout` | `watchdogTimeout` | `bashTimeout` | `maxTurns` | `maxOutput` | `context.enabled` |
++|---|---|---|---|---|---|---|
++| Small model (≤ 8B), short tasks/chat, no `bash` or commands under 20 s | `3m` (default) | `20s` (default) | `30s` (default) | `15` | `8000` | `true` |
++| Small/medium model, general coding agent | `5m` | `2m` (aligned on bashTimeout) | `2m` | `40` | `16000` | `true` |
++| Larger model or modest machine (CPU) | `10m` | `5m` | `5m` | `40`-`60` | `16000`-`24000` | `true` |
++
++In the first row, `watchdogTimeout` (20 s) is shorter than `bashTimeout` (30 s): those are the defaults, and they only fit when no command runs longer than 20 s. As soon as the agent runs longer commands, align the two as in the other rows (section 3).
++
++These profiles are starting points, not absolute truths: adjust them by watching how your model actually behaves (does it loop, is it cut too early, does the context fill up too fast).
++
++---
++
++## 9. Sampling: how the model picks its words
++
++**In plain words**: "sampling" is the set of settings that control how the model picks the next word among all the ones it finds plausible. It decides whether the model is **precise and predictable** or **creative and varied**. Unlike the settings above (timeouts, quotas), sampling has no fixed structure in mini-me: it is a free list of keys (`sampling:` in the YAML) passed almost as is to the model's server.
++
++```yaml
++sampling:
++  temperature: 0.0
++  top_p: 0.9
++  max_tokens: 4096
++```
++
++These are the only three keys mini-me sets by default. The others (`top_k`, `min_p`, `repeat_penalty`…) have no default: add them yourself if your server and model support them and you need them.
++
++### `temperature`: the "precise ↔ creative" dial
++
++**In plain words**: the closer it is to `0`, the more the model always picks the word it finds most likely (stable, reproducible answers, sometimes a little rigid). The higher it goes towards `1` (or beyond), the more it accepts less obvious words (more varied answers, but also more risk of mistakes and drift).
++
++- **mini-me default**: `0.0`, deliberately very low, because mini-me is designed as a **coding agent**, where precision and reproducibility matter, not creativity.
++- **How to set it for a small model**:
++  - An agent that runs commands, writes code, follows strict instructions: **keep `0.0`-`0.2`**. A small model already makes more mistakes and loops more than a large one; a low temperature reduces that risk.
++  - A conversational or creative agent, or one that must rephrase or brainstorm: go up to `0.5`-`0.8`. Beyond `0.8`, a small model more easily turns incoherent.
++
++### `top_p` (nucleus sampling): how wide the choice is
++
++**In plain words**: instead of considering every possible word, the model only looks at the smallest group of words whose combined probability reaches this share. `top_p: 0.9` means "only consider the words that together cover 90 % of the probability; ignore the long tail of unlikely ones".
++
++- **mini-me default**: `0.9`.
++- **How to set it**: together with a low `temperature`, `0.9` is already a good "safe" compromise for a small model. You can go down to `0.8` to cut odd detours further; there is no point going higher for a coding agent.
++
++### `top_k`: limiting the number of candidates (optional, no default in mini-me)
++
++**In plain words**: keep only the `k` most likely words at each step and ignore the rest, whatever `top_p` says.
++
++- **How to set it**: small models (often small Qwen, Gemma or Llama) do not all react to `top_k` the same way, and some model families explicitly recommend a value (for example `20`-`40`) in their model card. **Check the metadata or recommendations of the GGUF model you use** rather than guessing: a poorly chosen `top_k` can make a small model more repetitive or, on the contrary, more unstable.
++
++### `repeat_penalty` / `min_p`: against repetition (optional, no default in mini-me)
++
++**In plain words**: `repeat_penalty` penalises the model for reusing a word it used recently (useful against repetition loops, a classic weakness of small models). `min_p` is an alternative to `top_p` that drops the words whose probability is too low compared with the most likely word at that moment.
++
++- **How to set them**: these are typically the settings that **vary most from one model family to another**; there is no universal value. Good practice is to use the values the model card recommends (often in the GGUF metadata or the model's documentation) rather than improvising. If the agent repeats sentences or actions in a loop, this is often the first setting to adjust, together with mini-me's loop detector and `maxTurns` (section 5).
++
++### `max_tokens`: the longest an answer may be
++
++**In plain words**: how many tokens the model may generate in one answer before it is cut.
++
++- **mini-me default**: `4096`.
++- **How to set it**: for a small model with a small context window, check that `max_tokens` leaves enough room in the window for the prompt itself: `max_tokens` + prompt size must not exceed `contextWindow`. Lower it (`1024`-`2048`) if your answers must stay short (e.g. classification, extraction); keep the default for an agent that writes code or longer explanations.
++
++### In short: mini-me's sampling philosophy
++
++mini-me assumes that a **small local model is a coding agent first**, so its default sampling favours **precision and reproducibility** (`temperature: 0.0`) over creativity. It is the safest starting point to limit mistakes, hallucinated command results and loops; loosen it yourself if your use is more conversational or creative.
++
++> mini-me has no automatic "sampling profile" per model family today: the defaults are generic and deliberately conservative. When you switch models, check these settings again rather than keeping another model's out of habit.

added guides/raccourcis-clavier-tui.md +121 -0 Viewed

new file mode 100644
@@ -0,0 +1,121 @@
	1	+# Raccourcis clavier de la fenêtre (`mm -tui`)
	2	+
	3	+[English version](tui-keyboard-shortcuts.md)
	4	+
	5	+> Toutes les touches que la fenêtre (`mm -tui`) comprend, regroupées selon ce que vous êtes en train de faire. F1 en affiche une version courte dans la fenêtre. La barre d'état en bas rappelle toujours `F1 help · Ctrl-Y copy · F2 mouse · Ctrl-C quit`.
	6	+
	7	+## La fenêtre en deux parties
	8	+
	9	+Deux endroits peuvent recevoir les touches : la zone de saisie en bas, où vous tapez, et la conversation au-dessus. Tab fait passer le focus de l'un à l'autre. Au démarrage, le focus est sur la zone de saisie. Quand il est sur la conversation, les lettres ne font rien : appuyez sur Tab pour écrire à nouveau.
	10	+
	11	+## Écrire et envoyer
	12	+
	13	+\| Touche \| Effet \|
	14	+\|---\|---\|
	15	+\| `Entrée` \| Envoie le contenu de la zone. Une zone vide n'envoie rien. \|
	16	+\| `Ctrl-J` ou `Alt-Entrée` \| Un saut de ligne dans la zone, sans envoyer. Un terminal ne distingue pas `Maj-Entrée` de `Entrée` : il envoie. \|
	17	+\| `←` `→` \| Déplacent le curseur ; en début ou en fin de ligne, passent à la ligne précédente ou suivante. \|
	18	+\| `↑` `↓` \| Passent à la rangée du dessus ou du dessous dans la zone — une ligne longue se replie sur plusieurs rangées. Sur la première rangée, `↑` rappelle votre question précédente (voir plus bas). \|
	19	+\| `Début` `Fin` \| Début ou fin de la ligne. \|
	20	+\| `Retour arrière` `Suppr` \| Effacent le caractère avant ou sous le curseur. Un collage replié (`[Pasted #1 · …]`) s'efface d'un bloc. \|
	21	+\| `Échap` \| Quand rien ne tourne : vide la zone. \|
	22	+
	23	+## Pendant que l'agent travaille
	24	+
	25	+\| Touche \| Effet \|
	26	+\|---\|---\|
	27	+\| `Échap` \| Arrête la réponse en cours (comme `/abort`) et affiche `🛑 Aborting…`. Appuyé à nouveau quand le tour ne s'arrête pas, il vous indique d'utiliser Ctrl-C. \|
	28	+\| `Ctrl-C` \| Arrête la réponse en cours. Si elle a déjà reçu l'ordre de s'arrêter et ne l'a pas fait, `Ctrl-C` ferme mm. \|
	29	+\| `Entrée` \| Arrête la réponse en cours et envoie ce que vous avez tapé une fois qu'elle est arrêtée : vous pouvez changer d'avis sans attendre. \|
	30	+
	31	+## Rappeler une question précédente
	32	+
	33	+Demande `sessions.enabled: true` dans le YAML de l'agent.
	34	+
	35	+\| Touche \| Effet \|
	36	+\|---\|---\|
	37	+\| `↑` (première rangée de la zone) \| Remet votre question précédente dans la zone ; encore une fois pour celle d'avant — cette session d'abord, puis les sessions précédentes du projet. \|
	38	+\| `↓` (dernière rangée de la zone) \| Revient vers la question la plus récente ; au-delà, rend ce que vous étiez en train de taper. \|
	39	+\| `Échap` \| Efface la question rappelée, pour taper autre chose. \|
	40	+
	41	+Une question rappelée peut être modifiée avant d'être envoyée. Sans rien à rappeler, `↑` et `↓` font défiler la conversation.
	42	+
	43	+## Se déplacer dans la conversation
	44	+
	45	+\| Touche \| Effet \|
	46	+\|---\|---\|
	47	+\| `PgUp` `PgDn` \| Une page vers le haut ou le bas, où que soit le focus. \|
	48	+\| `↑` `↓` \| Une ligne, quand le focus est sur la conversation (`Tab`). \|
	49	+\| `Début` `Fin` \| Haut ou bas de la conversation, quand le focus est dessus. `Fin` suit aussi à nouveau la réponse pendant qu'elle s'écrit. \|
	50	+\| Molette \| Trois lignes vers le haut ou le bas — seulement après `F2` (voir plus bas). \|
	51	+\| `Ctrl-L` \| Efface la conversation affichée. Ce dont l'agent se souvient n'est pas touché : c'est `/new` qui le fait. \|
	52	+
	53	+## Compléter une commande, un fichier ou un skill
	54	+
	55	+Taper `/` au début de la zone, ou `@` ou `$` n'importe où, ouvre une liste de choix au-dessus de la zone : commandes, fichiers et dossiers, skills.
	56	+
	57	+\| Touche \| Effet \|
	58	+\|---\|---\|
	59	+\| `↑` `↓` \| Se déplacent dans la liste. \|
	60	+\| `Tab` \| Complète avec le choix en surbrillance. \|
	61	+\| `Entrée` \| Envoie quand ce que vous avez tapé est déjà complet ; sinon complète, comme `Tab`. \|
	62	+\| `Échap` \| Ferme la liste jusqu'à ce que vous tapiez autre chose. \|
	63	+
	64	+## Coller un texte long
	65	+
	66	+Collez comme d'habitude avec votre terminal (`Cmd-V`, `Ctrl-Maj-V`, le clic droit…). Un collage n'envoie jamais rien, même s'il contient des sauts de ligne. Au-delà de 3 lignes ou de 200 caractères, il s'affiche comme un seul jeton, `[Pasted #1 · 42 lines · 1.2k chars]` ; l'agent reçoit le texte complet. `Retour arrière` ou `Suppr` retire le jeton, et le texte avec lui.
	67	+
	68	+## Répondre à une permission
	69	+
	70	+Avec `yolo: false` (ou un outil MCP marqué `ask`), la zone est remplacée par une question comme `? bash: rm -rf build`. Seules ces touches marchent jusqu'à votre réponse :
	71	+
	72	+\| Touche \| Réponse \|
	73	+\|---\|---\|
	74	+\| `a` \| Autoriser cet appel, une fois. \|
	75	+\| `s` \| Autoriser cet outil pour le reste de la session. \|
	76	+\| `r` ou `Échap` \| Refuser cet appel. \|
	77	+\| `n` \| Ne jamais autoriser cet outil dans cette session. \|
	78	+
	79	+## Répondre aux questions de l'agent
	80	+
	81	+Quand l'agent vous pose une question (son outil `ask_user`), un petit formulaire remplace la zone. La ligne sous la question rappelle les touches.
	82	+
	83	+\| Type de question \| Touches \|
	84	+\|---\|---\|
	85	+\| Un choix \| `↑` `↓` (ou `Tab`) pour se déplacer, `Entrée` pour choisir — ou `1` à `9` pour choisir directement. \|
	86	+\| Plusieurs choix \| `↑` `↓` pour se déplacer, `Espace` pour cocher ou décocher, `Entrée` pour envoyer (au moins un coché). \|
	87	+\| Oui ou non \| `y` (ou `o`) oui, `n` non — ou `←` `→` puis `Entrée`. \|
	88	+\| Texte libre \| Tapez, `Retour arrière` pour corriger, `Entrée` pour envoyer. \|
	89	+\| Toutes \| `Échap` refuse de répondre. \|
	90	+
	91	+## Copier, souris, aide, quitter
	92	+
	93	+\| Touche \| Effet \|
	94	+\|---\|---\|
	95	+\| `Ctrl-Y` \| Copie la dernière réponse dans le presse-papiers, en texte brut (comme `/copy` ; `/copy 2` celle d'avant, `/copy all` toute la conversation). \|
	96	+\| `F2` \| Active ou désactive la capture de la souris. Désactivée (par défaut) : sélectionnez le texte à la souris comme dans n'importe quel terminal. Activée : la molette fait défiler la conversation, et `Maj`+glisser sélectionne. La barre d'état indique l'état. \|
	97	+\| `F1` \| Les commandes et les principales touches, dans la conversation (comme `/help`). \|
	98	+\| `Ctrl-C` \| Ferme mm quand rien ne tourne. `/quit` fait de même. \|
	99	+
	100	+## La fenêtre de `mm init`
	101	+
	102	+`mm init` ouvre sa propre fenêtre, dans le même style, pour écrire un nouvel agent.yaml (voir [Créer un agent avec `mm init`](../docs/fr/how-to/create-an-agent.md)).
	103	+
	104	+\| Touche \| Effet \|
	105	+\|---\|---\|
	106	+\| `↑` `↓` `Début` `Fin` \| Se déplacent dans les choix ; l'aperçu à droite suit le choix surligné. \|
	107	+\| `Entrée` \| Répond et passe à la question suivante ; sur le dernier écran, écrit le fichier. \|
	108	+\| `y` `n` \| Répondent à la question oui ou non. \|
	109	+\| `Échap` \| Revient d'une question en arrière, en reprenant sa réponse. \|
	110	+\| `PgUp` `PgDn` \| Font défiler l'aperçu. \|
	111	+\| `Tab` \| Sur un écran de moins de 100 colonnes : affiche l'aperçu à la place de la question, et inversement. \|
	112	+\| `←` `→` \| Dans une réponse de texte (l'endpoint, la variable de la clé, le nom, le fichier) : déplacent le curseur ; la saisie s'insère là. `Début` `Fin` (ou `Ctrl-A` `Ctrl-E`) vont au début et à la fin ; `Retour arrière` efface avant le curseur, `Suppr` après. \|
	113	+\| `Ctrl-U` \| Efface une réponse de texte. \|
	114	+\| `Ctrl-C` \| Quitte sans rien écrire. \|
	115	+
	116	+## Bon à savoir
	117	+
	118	+- Les touches dépendent du terminal. `Alt-Entrée`, `Début`, `Fin` et les touches de fonction dépendent de la façon dont le terminal les transmet ; sur un portable Mac, il faut souvent `Fn` pour `F1`, `F2`, `Début` et `Fin`. `Ctrl-J` marche toujours pour un saut de ligne.
	119	+- La fenêtre a besoin d'un vrai terminal. `mm -tui \| tee log.txt`, ou toute exécution où l'entrée ou la sortie n'est pas un terminal, revient au mode ligne, où aucune de ces touches ne s'applique.
	120	+
	121	+Voir aussi : [Utiliser le mode fenêtre](../docs/fr/how-to/use-the-window-mode.md), [Commandes et touches (référence)](../docs/fr/reference/slash-commands.md).

++# Raccourcis clavier de la fenêtre (`mm -tui`)
++
++*[English version](tui-keyboard-shortcuts.md)*
++
++> Toutes les touches que la fenêtre (`mm -tui`) comprend, regroupées selon ce que vous êtes en train de faire. **F1** en affiche une version courte dans la fenêtre. La barre d'état en bas rappelle toujours `F1 help · Ctrl-Y copy · F2 mouse · Ctrl-C quit`.
++
++## La fenêtre en deux parties
++
++Deux endroits peuvent recevoir les touches : la **zone de saisie** en bas, où vous tapez, et la **conversation** au-dessus. **Tab** fait passer le focus de l'un à l'autre. Au démarrage, le focus est sur la zone de saisie. Quand il est sur la conversation, les lettres ne font rien : appuyez sur Tab pour écrire à nouveau.
++
++## Écrire et envoyer
++
++| Touche | Effet |
++|---|---|
++| `Entrée` | Envoie le contenu de la zone. Une zone vide n'envoie rien. |
++| `Ctrl-J` ou `Alt-Entrée` | Un saut de ligne dans la zone, sans envoyer. Un terminal ne distingue pas `Maj-Entrée` de `Entrée` : il envoie. |
++| `←` `→` | Déplacent le curseur ; en début ou en fin de ligne, passent à la ligne précédente ou suivante. |
++| `↑` `↓` | Passent à la rangée du dessus ou du dessous dans la zone — une ligne longue se replie sur plusieurs rangées. Sur la première rangée, `↑` rappelle votre question précédente (voir plus bas). |
++| `Début` `Fin` | Début ou fin de la ligne. |
++| `Retour arrière` `Suppr` | Effacent le caractère avant ou sous le curseur. Un collage replié (`[Pasted #1 · …]`) s'efface d'un bloc. |
++| `Échap` | Quand rien ne tourne : vide la zone. |
++
++## Pendant que l'agent travaille
++
++| Touche | Effet |
++|---|---|
++| `Échap` | Arrête la réponse en cours (comme `/abort`) et affiche `🛑 Aborting…`. Appuyé à nouveau quand le tour ne s'arrête pas, il vous indique d'utiliser Ctrl-C. |
++| `Ctrl-C` | Arrête la réponse en cours. Si elle a déjà reçu l'ordre de s'arrêter et ne l'a pas fait, `Ctrl-C` ferme mm. |
++| `Entrée` | Arrête la réponse en cours et envoie ce que vous avez tapé une fois qu'elle est arrêtée : vous pouvez changer d'avis sans attendre. |
++
++## Rappeler une question précédente
++
++Demande `sessions.enabled: true` dans le YAML de l'agent.
++
++| Touche | Effet |
++|---|---|
++| `↑` (première rangée de la zone) | Remet votre question précédente dans la zone ; encore une fois pour celle d'avant — cette session d'abord, puis les sessions précédentes du projet. |
++| `↓` (dernière rangée de la zone) | Revient vers la question la plus récente ; au-delà, rend ce que vous étiez en train de taper. |
++| `Échap` | Efface la question rappelée, pour taper autre chose. |
++
++Une question rappelée peut être modifiée avant d'être envoyée. Sans rien à rappeler, `↑` et `↓` font défiler la conversation.
++
++## Se déplacer dans la conversation
++
++| Touche | Effet |
++|---|---|
++| `PgUp` `PgDn` | Une page vers le haut ou le bas, où que soit le focus. |
++| `↑` `↓` | Une ligne, quand le focus est sur la conversation (`Tab`). |
++| `Début` `Fin` | Haut ou bas de la conversation, quand le focus est dessus. `Fin` suit aussi à nouveau la réponse pendant qu'elle s'écrit. |
++| Molette | Trois lignes vers le haut ou le bas — seulement après `F2` (voir plus bas). |
++| `Ctrl-L` | Efface la conversation affichée. Ce dont l'agent se souvient n'est pas touché : c'est `/new` qui le fait. |
++
++## Compléter une commande, un fichier ou un skill
++
++Taper `/` au début de la zone, ou `@` ou `$` n'importe où, ouvre une liste de choix au-dessus de la zone : commandes, fichiers et dossiers, skills.
++
++| Touche | Effet |
++|---|---|
++| `↑` `↓` | Se déplacent dans la liste. |
++| `Tab` | Complète avec le choix en surbrillance. |
++| `Entrée` | Envoie quand ce que vous avez tapé est déjà complet ; sinon complète, comme `Tab`. |
++| `Échap` | Ferme la liste jusqu'à ce que vous tapiez autre chose. |
++
++## Coller un texte long
++
++Collez comme d'habitude avec votre terminal (`Cmd-V`, `Ctrl-Maj-V`, le clic droit…). Un collage n'envoie jamais rien, même s'il contient des sauts de ligne. Au-delà de 3 lignes ou de 200 caractères, il s'affiche comme un seul jeton, `[Pasted #1 · 42 lines · 1.2k chars]` ; l'agent reçoit le texte complet. `Retour arrière` ou `Suppr` retire le jeton, et le texte avec lui.
++
++## Répondre à une permission
++
++Avec `yolo: false` (ou un outil MCP marqué `ask`), la zone est remplacée par une question comme `? bash: rm -rf build`. Seules ces touches marchent jusqu'à votre réponse :
++
++| Touche | Réponse |
++|---|---|
++| `a` | Autoriser cet appel, une fois. |
++| `s` | Autoriser cet outil pour le reste de la session. |
++| `r` ou `Échap` | Refuser cet appel. |
++| `n` | Ne jamais autoriser cet outil dans cette session. |
++
++## Répondre aux questions de l'agent
++
++Quand l'agent vous pose une question (son outil `ask_user`), un petit formulaire remplace la zone. La ligne sous la question rappelle les touches.
++
++| Type de question | Touches |
++|---|---|
++| Un choix | `↑` `↓` (ou `Tab`) pour se déplacer, `Entrée` pour choisir — ou `1` à `9` pour choisir directement. |
++| Plusieurs choix | `↑` `↓` pour se déplacer, `Espace` pour cocher ou décocher, `Entrée` pour envoyer (au moins un coché). |
++| Oui ou non | `y` (ou `o`) oui, `n` non — ou `←` `→` puis `Entrée`. |
++| Texte libre | Tapez, `Retour arrière` pour corriger, `Entrée` pour envoyer. |
++| Toutes | `Échap` refuse de répondre. |
++
++## Copier, souris, aide, quitter
++
++| Touche | Effet |
++|---|---|
++| `Ctrl-Y` | Copie la dernière réponse dans le presse-papiers, en texte brut (comme `/copy` ; `/copy 2` celle d'avant, `/copy all` toute la conversation). |
++| `F2` | Active ou désactive la capture de la souris. **Désactivée** (par défaut) : sélectionnez le texte à la souris comme dans n'importe quel terminal. **Activée** : la molette fait défiler la conversation, et `Maj`+glisser sélectionne. La barre d'état indique l'état. |
++| `F1` | Les commandes et les principales touches, dans la conversation (comme `/help`). |
++| `Ctrl-C` | Ferme mm quand rien ne tourne. `/quit` fait de même. |
++
++## La fenêtre de `mm init`
++
++`mm init` ouvre sa propre fenêtre, dans le même style, pour écrire un nouvel agent.yaml (voir [Créer un agent avec `mm init`](../docs/fr/how-to/create-an-agent.md)).
++
++| Touche | Effet |
++|---|---|
++| `↑` `↓` `Début` `Fin` | Se déplacent dans les choix ; l'aperçu à droite suit le choix surligné. |
++| `Entrée` | Répond et passe à la question suivante ; sur le dernier écran, écrit le fichier. |
++| `y` `n` | Répondent à la question oui ou non. |
++| `Échap` | Revient d'une question en arrière, en reprenant sa réponse. |
++| `PgUp` `PgDn` | Font défiler l'aperçu. |
++| `Tab` | Sur un écran de moins de 100 colonnes : affiche l'aperçu à la place de la question, et inversement. |
++| `←` `→` | Dans une réponse de texte (l'endpoint, la variable de la clé, le nom, le fichier) : déplacent le curseur ; la saisie s'insère là. `Début` `Fin` (ou `Ctrl-A` `Ctrl-E`) vont au début et à la fin ; `Retour arrière` efface avant le curseur, `Suppr` après. |
++| `Ctrl-U` | Efface une réponse de texte. |
++| `Ctrl-C` | Quitte sans rien écrire. |
++
++## Bon à savoir
++
++- **Les touches dépendent du terminal.** `Alt-Entrée`, `Début`, `Fin` et les touches de fonction dépendent de la façon dont le terminal les transmet ; sur un portable Mac, il faut souvent `Fn` pour `F1`, `F2`, `Début` et `Fin`. `Ctrl-J` marche toujours pour un saut de ligne.
++- **La fenêtre a besoin d'un vrai terminal.** `mm -tui | tee log.txt`, ou toute exécution où l'entrée ou la sortie n'est pas un terminal, revient au mode ligne, où aucune de ces touches ne s'applique.
++
++Voir aussi : [Utiliser le mode fenêtre](../docs/fr/how-to/use-the-window-mode.md), [Commandes et touches (référence)](../docs/fr/reference/slash-commands.md).

added guides/reglages-agents-petits-modeles.md +217 -0 Viewed

new file mode 100644
@@ -0,0 +1,217 @@
	1	+# Guide des réglages pour agents mini-me (en langage simple)
	2	+
	3	+[English version](agent-settings-for-small-models.md)
	4	+
	5	+> Ce guide explique, sans jargon, ce que fait chaque réglage de configuration d'un agent mini-me, pourquoi il existe, quelle est sa valeur par défaut, et comment le régler quand on fait tourner un petit modèle de langage en local (celui qui tient sur ton laptop, pas un modèle géant dans le cloud).
	6	+
	7	+## Pourquoi ces réglages existent
	8	+
	9	+Un petit modèle local (quelques milliards de paramètres, tournant sur un CPU/GPU grand public) n'a pas les mêmes défauts qu'un gros modèle cloud :
	10	+
	11	+- il est lent — surtout pour lire un long prompt (le "prompt processing"),
	12	+- il a une mémoire (fenêtre de contexte) limitée — souvent 8k à 32k tokens, parfois moins,
	13	+- il boucle ou décroche plus facilement (répète la même commande, oublie ce qu'il a déjà lu, part en vrille dans un raisonnement),
	14	+- il peut halluciner un résultat de commande qu'il n'a jamais vraiment exécuté.
	15	+
	16	+Les réglages ci-dessous sont les garde-fous qui compensent ça : ils disent à l'agent "arrête-toi si tu es trop lent", "ne garde pas tout en mémoire", "ne tourne pas en rond indéfiniment", "ne renvoie pas un pavé de texte qui bouche ta propre mémoire".
	17	+
	18	+Ils se règlent dans le fichier YAML de l'agent (`agent.*.yaml`), sous les mêmes noms de clés.
	19	+
	20	+---
	21	+
	22	+## 1. `contextWindow` — la taille de la mémoire du modèle
	23	+
	24	+En clair : c'est la taille de la "mémoire de travail" du modèle, exprimée en tokens (un token ≈ 0,75 mot). Tout ce que l'agent a dit, lu, exécuté doit tenir dans cette mémoire. Quand elle est pleine, il faut faire de la place (voir section `context` plus bas).
	25	+
	26	+- Valeur par défaut : `0`, ce qui veut dire "je ne sais pas, demande au serveur". Si le serveur (llama.cpp, Docker Model Runner...) expose sa taille de contexte configurée, mini-me l'utilise automatiquement.
	27	+- Comment la régler : en général, ne la fixe pas toi-même si ton serveur peut la communiquer automatiquement — laisse `0`. Ne la renseigne à la main que si ton serveur ne la rapporte pas, et mets alors la vraie valeur que tu as configurée côté serveur (ex: `-c 8192` sur `llama-server` → `contextWindow: 8192`).
	28	+- Pour un petit modèle : les petits modèles sont souvent livrés avec une fenêtre annoncée de 32k ou plus, mais en pratique, la qualité se dégrade bien avant d'atteindre cette limite. Mieux vaut connaître la vraie valeur utilisable pour que les calculs de compression du contexte (section 8) soient fiables.
	29	+
	30	+---
	31	+
	32	+## 2. `firstTokenTimeout` — le temps qu'on laisse au modèle pour commencer à répondre
	33	+
	34	+En clair : avant même que le modèle produise son premier mot, le serveur doit lire tout le prompt (la question + l'historique + les instructions). Sur un petit modèle local, lire un prompt de 20-30k tokens peut prendre plusieurs minutes. Ce réglage dit : "j'attends jusqu'à combien de temps avant de considérer que ça a planté ?"
	35	+
	36	+- Valeur par défaut : `3 minutes`.
	37	+- Particularité : si le serveur (llama.cpp) donne des nouvelles de sa progression de lecture pendant ce temps, le chronomètre est remis à zéro à chaque nouvelle. Donc en pratique, tant que le serveur progresse, ça ne coupera pas — ce timeout protège surtout contre un vrai blocage silencieux.
	38	+- Comment la régler :
	39	+ - Modèle petit (≤ 8B) avec un bon GPU : la valeur par défaut (3 min) suffit généralement.
	40	+ - Modèle plus gros (15-30B) ou machine modeste (CPU seul, peu de VRAM), ou prompts très longs (gros `AGENTS.md`, beaucoup d'historique) : monte à `5m` voire `10m`.
	41	+ - Règle d'or : jamais plus court que `watchdogTimeout` (voir juste après) — sinon la protection n'a pas de sens.
	42	+
	43	+---
	44	+
	45	+## 3. `watchdogTimeout` — le chien de garde pendant que le modèle génère
	46	+
	47	+En clair : une fois que le modèle a commencé à répondre (ou à utiliser un outil), ce réglage surveille qu'il continue à produire quelque chose régulièrement. S'il reste silencieux plus longtemps que cette durée sans rien produire de nouveau, mini-me considère que la connexion est bloquée et coupe.
	48	+
	49	+- Valeur par défaut : `20 secondes`.
	50	+- Différence avec `firstTokenTimeout` : `firstTokenTimeout` surveille le démarrage (lecture du prompt), `watchdogTimeout` surveille la suite (génération token par token, ou l'exécution d'un outil). C'est pour ça que `watchdogTimeout` est beaucoup plus court.
	51	+- Comment la régler :
	52	+ - Si l'agent a accès à l'outil `bash` et que des commandes peuvent légitimement prendre du temps (build, tests, téléchargements), monte ce timeout en même temps que `bashTimeout` : pendant qu'une commande bash tourne, le chien de garde continue de compter, donc si `bashTimeout` vaut `2m`, `watchdogTimeout` doit valoir au moins `2m` aussi, sinon mini-me couperait la commande avant qu'elle finisse.
	53	+ - Pour un usage "chat" simple sans gros outils : la valeur par défaut convient très bien, y compris sur un petit modèle lent (c'est la génération token-par-token qui compte, pas la vitesse globale).
	54	+
	55	+---
	56	+
	57	+## 4. `bashTimeout` — combien de temps une commande shell a le droit de tourner
	58	+
	59	+En clair : quand l'agent exécute une commande (`bash`), c'est le temps maximum avant que mini-me la tue de force, même si elle n'a rien renvoyé.
	60	+
	61	+- Valeur par défaut : `30 secondes`.
	62	+- Comment la régler :
	63	+ - Tâches rapides (lire un fichier, `git status`, `ls`) : le défaut de 30s est largement suffisant.
	64	+ - Tâches lourdes attendues (compilation, tests, installation de dépendances, longue recherche) : augmente franchement, par exemple `2m`, `5m`, voire plus selon le projet.
	65	+ - Toujours augmenter `watchdogTimeout` en même temps (voir section 3) — c'est le piège le plus courant : une commande se fait tuer par le chien de garde alors que `bashTimeout` lui laissait le temps.
	66	+ - Ce réglage ne dépend pas vraiment de la taille du modèle, mais du type de projet sur lequel l'agent travaille.
	67	+
	68	+---
	69	+
	70	+## 5. `maxTurns` — combien d'allers-retours modèle ↔ outils sont autorisés pour une seule question
	71	+
	72	+En clair : pour répondre à une question, l'agent peut faire plusieurs tours : "je lance une commande" → "je regarde le résultat" → "j'en lance une autre" → etc. Ce réglage plafonne le nombre de ces tours avant que mini-me arrête l'agent (pour éviter qu'il boucle à l'infini).
	73	+
	74	+- Valeur par défaut : `10`.
	75	+- Valeur réellement utilisée dans les configurations livrées : `40` — l'expérience montre que 10 est souvent trop bas pour des tâches de code réalistes avec un petit modèle, qui a besoin de plus d'itérations (relire, corriger, retenter) qu'un gros modèle.
	76	+- Comment la régler :
	77	+ - Tâche étroite, une seule action attendue (répondre à une question factuelle, un seul appel d'outil) : `8` à `15` suffit, et ça protège mieux contre les boucles.
	78	+ - Agent de développement généraliste (explorer du code, éditer, tester) : `40` à `60` est raisonnable, surtout avec un petit modèle qui a besoin de plusieurs essais.
	79	+ - Plus le modèle est petit/faible, plus il risque de boucler sans jamais conclure — associe un `maxTurns` généreux à une bonne détection de boucle plutôt que de mettre une valeur énorme "au cas où".
	80	+
	81	+---
	82	+
	83	+## 6. `maxOutput` — la taille maximale de ce qu'un outil peut renvoyer au modèle
	84	+
	85	+En clair : si une commande `bash` renvoie 500 000 caractères (un gros fichier de log, par exemple), on ne veut pas que ça remplisse d'un coup toute la mémoire du modèle. Ce réglage tronque le résultat avant de le montrer au modèle.
	86	+
	87	+- Valeur par défaut : `16000` caractères.
	88	+- Comment ça tronque : pas juste en coupant à la fin — mini-me garde le début du résultat et jusqu'à 2000 caractères de la fin, car souvent l'information utile (erreur, résumé) est à la fin d'une sortie longue.
	89	+- Comment la régler :
	90	+ - Petit modèle à fenêtre de contexte réduite (8k-16k tokens) : baisse cette valeur, par exemple `4000` à `8000`, pour qu'une seule commande ne consomme pas un tiers de la mémoire disponible.
	91	+ - Modèle avec une grande fenêtre de contexte, ou agent qui a vraiment besoin de voir des sorties complètes (ex: analyser un gros diff) : tu peux monter à `20000`-`30000`, mais garde en tête que chaque sortie "coûte" en tokens et accélère le moment où la compression du contexte (section 8) se déclenche.
	92	+
	93	+---
	94	+
	95	+## 7. `agentsMd` — comment l'agent lit ses instructions de projet
	96	+
	97	+En clair : `AGENTS.md` (ou équivalent) contient les instructions propres au projet que l'agent doit suivre. Ce bloc de réglages contrôle si/comment ce fichier est chargé.
	98	+
	99	+```yaml
	100	+agentsMd:
	101	+ enabled: true
	102	+ path: "AGENTS.md"
	103	+ maxChars: 0
	104	+```
	105	+
	106	+- `enabled` — défaut : `true`. Active la lecture automatique du fichier.
	107	+- `path` — défaut : `"AGENTS.md"`. Le nom/chemin du fichier à lire.
	108	+- `maxChars` — défaut : `0` (= pas de limite).
	109	+
	110	+### Le point important sur `maxChars`
	111	+
	112	+Ce n'est pas une troncature. Si le fichier `AGENTS.md` dépasse `maxChars` caractères, il n'est pas coupé — il est entièrement ignoré (le code source dit explicitement : couper au milieu risquerait de supprimer justement la règle qui compte). La bannière de démarrage l'indique (`skipped (too long)`) plutôt que de faire semblant d'avoir lu le fichier en entier.
	113	+
	114	+- Comment la régler :
	115	+ - Même sans `maxChars`, mini-me te prévient : la bannière de démarrage avertit quand `AGENTS.md` occupe 20 % ou plus d'une fenêtre de contexte connue (estimation : nombre de caractères ÷ 3,5). Avec un petit modèle, c'est le signe qu'il faut raccourcir le fichier.
	116	+ - `maxChars` est une limite stricte en plus de cet avertissement. Avec un petit modèle à faible fenêtre, un `AGENTS.md` trop long peut consommer une grosse part de la mémoire avant même que la conversation commence. Fixer `maxChars` garantit qu'il ne la dépassera jamais : au-delà, le fichier est ignoré et la bannière le dit, et tu sais qu'il faut le raccourcir.
	117	+ - Pour calculer une valeur : 20 % de la fenêtre × 3,5. Exemple : fenêtre de 8192 tokens → 20 % = 1638 tokens → environ `maxChars: 5700`.
	118	+ - Si ton `AGENTS.md` est court (quelques centaines de lignes maximum) et que ton modèle a une fenêtre confortable (32k+), tu peux laisser `0`.
	119	+
	120	+---
	121	+
	122	+## 8. `context` — la compression automatique de l'historique
	123	+
	124	+En clair : au fur et à mesure que la conversation avance, l'historique (questions, réponses, résultats de commandes) grandit. Sur un petit modèle à mémoire limitée, il arrive un moment où tout ne tient plus. Ce bloc décide quand et comment résumer automatiquement les anciens échanges pour faire de la place, sans perdre le fil.
	125	+
	126	+```yaml
	127	+context:
	128	+ enabled: false
	129	+ threshold: 75
	130	+ maxMessages: 80
	131	+ keepLastTurns: 3
	132	+ summaryMaxTokens: 1200
	133	+ prompt: ""
	134	+ showStats: true
	135	+```
	136	+
	137	+\| Sous-réglage \| Défaut \| Ce qu'il fait \| Comment le régler \|
	138	+\|---\|---\|---\|---\|
	139	+\| `enabled` \| `false` \| Active la compression automatique. Même désactivé, tu peux toujours lancer une compression manuelle. \| Active-le (`true`) pour tout petit modèle local — c'est la protection principale contre le "contexte plein" qui fait planter ou dégrader l'agent. \|
	140	+\| `threshold` \| `75` (%) \| Pourcentage de la fenêtre de contexte à partir duquel la compression se déclenche. 75 % laisse volontairement un quart de la mémoire libre pour la prochaine question, les résultats d'outils et la réponse. \| Ne descends pas trop bas (tu compresserais trop souvent, donc tu perds en continuité) ; ne monte pas trop haut (tu risques de saturer avant que la compression ait pu agir). 70-80 % est une bonne plage. \|
	141	+\| `maxMessages` \| `80` \| Déclencheur de secours basé sur le nombre de messages, utilisé quand la taille de la fenêtre est inconnue (`contextWindow: 0` et serveur muet sur le sujet). Une commande = 2 messages (l'appel + le résultat), donc 80 ≈ 30 commandes d'historique. \| Le code justifie 80 ainsi : c'est à peu près le moment où un modèle local de 12B commence à ralentir. Sur un modèle plus petit, tu peux baisser cette valeur si tu remarques que l'agent devient plus lent ou confus avant d'atteindre 80 messages. Mets `0` pour désactiver ce déclencheur si tu es sûr de connaître `contextWindow`. \|
	142	+\| `keepLastTurns` \| `3` \| Nombre de derniers tours de conversation gardés intacts (non résumés) — c'est là que l'agent "travaille" activement, le résumer le ferait rejouer ce qu'il vient juste de faire. \| Garde au moins `2`-`3`. Monte-le un peu (`4`-`5`) si tu remarques que l'agent "oublie" une action toute récente juste après une compression. \|
	143	+\| `summaryMaxTokens` \| `1200` \| Taille maximale du résumé généré pour remplacer les vieux échanges. Ce plafond empêche un modèle qui dérape de produire un résumé qui lui-même remplit la fenêtre qu'on cherchait à vider. \| Pour un petit modèle, ne monte pas trop ce chiffre : un résumé doit rester compact. `1200` convient à la plupart des cas ; descends à `600`-`800` si tu veux économiser encore plus de place. \|
	144	+\| `prompt` \| `""` (prompt intégré) \| Permet de remplacer le prompt utilisé pour demander le résumé. \| Laisse vide sauf besoin spécifique (ex: vouloir que le résumé garde un format particulier). \|
	145	+\| `showStats` \| `true` \| Affiche une ligne d'info après chaque compression (combien de tokens économisés, etc.). \| Laisse activé, c'est utile pour vérifier que la compression fait bien son travail — désactive seulement si tu veux une sortie plus silencieuse. \|
	146	+
	147	+Astuce pratique : la compression envoie le résumé au modèle sans les outils actifs et sans le mode "raisonnement", justement pour que `summaryMaxTokens` ne soit pas gaspillé en réflexion plutôt qu'en résumé utile.
	148	+
	149	+---
	150	+
	151	+## Résumé — profils types
	152	+
	153	+\| Situation \| `firstTokenTimeout` \| `watchdogTimeout` \| `bashTimeout` \| `maxTurns` \| `maxOutput` \| `context.enabled` \|
	154	+\|---\|---\|---\|---\|---\|---\|---\|
	155	+\| Petit modèle (≤ 8B), tâches courtes/chat, sans `bash` ou avec des commandes de moins de 20 s \| `3m` (défaut) \| `20s` (défaut) \| `30s` (défaut) \| `15` \| `8000` \| `true` \|
	156	+\| Petit/moyen modèle, agent de code généraliste \| `5m` \| `2m` (aligné sur bashTimeout) \| `2m` \| `40` \| `16000` \| `true` \|
	157	+\| Modèle plus gros ou machine modeste (CPU) \| `10m` \| `5m` \| `5m` \| `40`-`60` \| `16000`-`24000` \| `true` \|
	158	+
	159	+Dans la première ligne, `watchdogTimeout` (20 s) est plus court que `bashTimeout` (30 s) : ce sont les valeurs par défaut, et elles ne conviennent que si aucune commande ne dure plus de 20 s. Dès que l'agent lance des commandes plus longues, aligne les deux comme dans les lignes suivantes (section 3).
	160	+
	161	+Ces profils sont des points de départ, pas des vérités absolues — ajuste en observant le comportement réel de ton modèle (est-ce qu'il boucle, est-ce qu'il se fait couper trop tôt, est-ce que le contexte se remplit trop vite).
	162	+
	163	+---
	164	+
	165	+## 9. Section sampling — comment le modèle choisit ses mots
	166	+
	167	+En clair : le "sampling" (échantillonnage), ce sont les réglages qui contrôlent la façon dont le modèle pioche le mot suivant parmi toutes les possibilités qu'il juge plausibles. C'est la partie qui décide si le modèle est précis et prévisible ou créatif et varié. Contrairement aux réglages précédents (timeouts, quotas), le sampling n'a pas de struct figée dans mini-me : c'est une liste libre de clés (`sampling:` dans le YAML) transmise quasiment telle quelle au serveur du modèle.
	168	+
	169	+```yaml
	170	+sampling:
	171	+ temperature: 0.0
	172	+ top_p: 0.9
	173	+ max_tokens: 4096
	174	+```
	175	+
	176	+Ce sont les trois seules clés définies par défaut dans mini-me. Les autres (`top_k`, `min_p`, `repeat_penalty`...) ne sont pas fixées par défaut — à toi de les ajouter si ton serveur/modèle les supporte et si tu en as besoin.
	177	+
	178	+### `temperature` — le curseur "précis ↔ créatif"
	179	+
	180	+En clair : plus elle est proche de `0`, plus le modèle choisit systématiquement le mot qu'il juge le plus probable (réponses stables, reproductibles, parfois un peu rigides). Plus elle monte vers `1` (ou au-delà), plus il accepte de piocher des mots moins évidents (réponses plus variées, mais aussi plus de risques d'erreurs ou d'écarts).
	181	+
	182	+- Défaut mini-me : `0.0` — volontairement très bas, car mini-me est pensé pour un agent de code, où on veut de la précision et de la reproductibilité, pas de la créativité.
	183	+- Comment la régler pour un petit modèle :
	184	+ - Agent qui exécute des commandes, écrit du code, suit des instructions strictes : garde `0.0`-`0.2`. Un petit modèle est déjà plus sujet aux erreurs et aux boucles qu'un gros modèle ; une température basse réduit ce risque.
	185	+ - Agent conversationnel, créatif, ou qui doit reformuler/brainstormer : monte à `0.5`-`0.8`. Au-delà de `0.8`, un petit modèle part plus facilement en incohérence.
	186	+
	187	+### `top_p` (nucleus sampling) — la largeur du choix
	188	+
	189	+En clair : au lieu de considérer tous les mots possibles, le modèle ne regarde que le plus petit groupe de mots dont la probabilité cumulée atteint ce pourcentage. `top_p: 0.9` veut dire "ne considère que les mots qui, ensemble, couvrent 90 % de la probabilité — ignore la longue traîne improbable".
	190	+
	191	+- Défaut mini-me : `0.9`.
	192	+- Comment la régler : combiné à une `temperature` basse, `0.9` est déjà un bon compromis "sûr" pour un petit modèle. Tu peux descendre à `0.8` si tu veux encore réduire les écarts bizarres ; inutile de monter plus haut pour un agent de code.
	193	+
	194	+### `top_k` — limiter le nombre de candidats (optionnel, pas de défaut dans mini-me)
	195	+
	196	+En clair : ne garde que les `k` mots les plus probables à chaque étape, et ignore tout le reste, quel que soit `top_p`.
	197	+
	198	+- Comment la régler : les petits modèles (souvent Qwen, Gemma, Llama en petites tailles) n'ont pas tous la même sensibilité à `top_k` — certaines familles de modèles recommandent explicitement une valeur (par exemple `20`-`40`) dans leur fiche technique. Vérifie les métadonnées/recommandations du modèle GGUF que tu utilises plutôt que de deviner : un `top_k` mal choisi peut rendre un petit modèle plus répétitif ou au contraire plus instable.
	199	+
	200	+### `repeat_penalty` / `min_p` — anti-répétition (optionnel, pas de défaut dans mini-me)
	201	+
	202	+En clair : `repeat_penalty` pénalise le modèle s'il réutilise un mot déjà employé récemment (utile contre les boucles de répétition, un défaut classique des petits modèles). `min_p` est une alternative à `top_p` qui élimine les mots dont la probabilité est trop faible par rapport au mot le plus probable du moment.
	203	+
	204	+- Comment les régler : ce sont typiquement les réglages qui varient le plus d'une famille de modèle à l'autre — il n'existe pas de valeur universelle. La bonne pratique est de reprendre les valeurs recommandées par la fiche du modèle (souvent indiquées dans les métadonnées GGUF ou la documentation du modèle) plutôt que d'improviser. Si l'agent répète des phrases ou des actions en boucle, c'est souvent le premier réglage à ajuster, avec le détecteur de boucle de mini-me et `maxTurns` (section 5).
	205	+
	206	+### `max_tokens` — la longueur maximale d'une réponse
	207	+
	208	+En clair : combien de tokens le modèle a le droit de générer en une seule réponse avant d'être coupé.
	209	+
	210	+- Défaut mini-me : `4096`.
	211	+- Comment la régler : pour un petit modèle avec une fenêtre de contexte réduite, vérifie que `max_tokens` laisse assez de place dans la fenêtre pour le prompt lui-même — `max_tokens` + taille du prompt ne doit pas dépasser `contextWindow`. Baisse-le (`1024`-`2048`) si tes réponses doivent rester courtes (ex: classification, extraction) ; garde la valeur par défaut pour un agent qui doit écrire du code ou des explications plus longues.
	212	+
	213	+### En résumé — philosophie du sampling dans mini-me
	214	+
	215	+mini-me part du principe qu'un petit modèle local est un agent de code avant tout, donc ses réglages de sampling par défaut privilégient la précision et la reproductibilité (`temperature: 0.0`) plutôt que la créativité. C'est le point de départ le plus sûr pour limiter les erreurs, les hallucinations de résultats de commandes et les boucles — quitte à l'assouplir toi-même si ton usage est plus conversationnel ou créatif.
	216	+
	217	+> Il n'existe pas aujourd'hui dans mini-me de "profil de sampling" automatique par famille de modèle — les valeurs par défaut sont génériques et volontairement conservatrices. Si tu changes de modèle, pense à revérifier ces réglages plutôt que de garder ceux d'un autre modèle par habitude.

++# Guide des réglages pour agents mini-me (en langage simple)
++
++*[English version](agent-settings-for-small-models.md)*
++
++> Ce guide explique, sans jargon, ce que fait chaque réglage de configuration d'un agent mini-me, pourquoi il existe, quelle est sa valeur par défaut, et comment le régler **quand on fait tourner un petit modèle de langage en local** (celui qui tient sur ton laptop, pas un modèle géant dans le cloud).
++
++## Pourquoi ces réglages existent
++
++Un petit modèle local (quelques milliards de paramètres, tournant sur un CPU/GPU grand public) n'a pas les mêmes défauts qu'un gros modèle cloud :
++
++- il est **lent** — surtout pour lire un long prompt (le "prompt processing"),
++- il a une **mémoire (fenêtre de contexte) limitée** — souvent 8k à 32k tokens, parfois moins,
++- il **boucle ou décroche** plus facilement (répète la même commande, oublie ce qu'il a déjà lu, part en vrille dans un raisonnement),
++- il peut **halluciner** un résultat de commande qu'il n'a jamais vraiment exécuté.
++
++Les réglages ci-dessous sont les garde-fous qui compensent ça : ils disent à l'agent "arrête-toi si tu es trop lent", "ne garde pas tout en mémoire", "ne tourne pas en rond indéfiniment", "ne renvoie pas un pavé de texte qui bouche ta propre mémoire".
++
++Ils se règlent dans le fichier YAML de l'agent (`agent.*.yaml`), sous les mêmes noms de clés.
++
++---
++
++## 1. `contextWindow` — la taille de la mémoire du modèle
++
++**En clair** : c'est la taille de la "mémoire de travail" du modèle, exprimée en tokens (un token ≈ 0,75 mot). Tout ce que l'agent a dit, lu, exécuté doit tenir dans cette mémoire. Quand elle est pleine, il faut faire de la place (voir section `context` plus bas).
++
++- **Valeur par défaut** : `0`, ce qui veut dire "je ne sais pas, demande au serveur". Si le serveur (llama.cpp, Docker Model Runner...) expose sa taille de contexte configurée, mini-me l'utilise automatiquement.
++- **Comment la régler** : en général, **ne la fixe pas toi-même** si ton serveur peut la communiquer automatiquement — laisse `0`. Ne la renseigne à la main que si ton serveur ne la rapporte pas, et mets alors la vraie valeur que tu as configurée côté serveur (ex: `-c 8192` sur `llama-server` → `contextWindow: 8192`).
++- **Pour un petit modèle** : les petits modèles sont souvent livrés avec une fenêtre annoncée de 32k ou plus, mais **en pratique, la qualité se dégrade bien avant** d'atteindre cette limite. Mieux vaut connaître la vraie valeur utilisable pour que les calculs de compression du contexte (section 8) soient fiables.
++
++---
++
++## 2. `firstTokenTimeout` — le temps qu'on laisse au modèle pour *commencer* à répondre
++
++**En clair** : avant même que le modèle produise son premier mot, le serveur doit *lire* tout le prompt (la question + l'historique + les instructions). Sur un petit modèle local, lire un prompt de 20-30k tokens peut prendre plusieurs minutes. Ce réglage dit : "j'attends jusqu'à combien de temps avant de considérer que ça a planté ?"
++
++- **Valeur par défaut** : `3 minutes`.
++- **Particularité** : si le serveur (llama.cpp) donne des nouvelles de sa progression de lecture pendant ce temps, le chronomètre est **remis à zéro** à chaque nouvelle. Donc en pratique, tant que le serveur progresse, ça ne coupera pas — ce timeout protège surtout contre un vrai blocage silencieux.
++- **Comment la régler** :
++  - Modèle petit (≤ 8B) avec un bon GPU : la valeur par défaut (3 min) suffit généralement.
++  - Modèle plus gros (15-30B) ou machine modeste (CPU seul, peu de VRAM), ou prompts très longs (gros `AGENTS.md`, beaucoup d'historique) : monte à `5m` voire `10m`.
++  - Règle d'or : **jamais plus court que `watchdogTimeout`** (voir juste après) — sinon la protection n'a pas de sens.
++
++---
++
++## 3. `watchdogTimeout` — le chien de garde pendant que le modèle *génère*
++
++**En clair** : une fois que le modèle a commencé à répondre (ou à utiliser un outil), ce réglage surveille qu'il continue à produire quelque chose régulièrement. S'il reste silencieux plus longtemps que cette durée *sans rien produire de nouveau*, mini-me considère que la connexion est bloquée et coupe.
++
++- **Valeur par défaut** : `20 secondes`.
++- **Différence avec `firstTokenTimeout`** : `firstTokenTimeout` surveille le **démarrage** (lecture du prompt), `watchdogTimeout` surveille la **suite** (génération token par token, ou l'exécution d'un outil). C'est pour ça que `watchdogTimeout` est beaucoup plus court.
++- **Comment la régler** :
++  - Si l'agent a accès à l'outil `bash` et que des commandes peuvent légitimement prendre du temps (build, tests, téléchargements), **monte ce timeout en même temps que `bashTimeout`** : pendant qu'une commande bash tourne, le chien de garde continue de compter, donc si `bashTimeout` vaut `2m`, `watchdogTimeout` doit valoir au moins `2m` aussi, sinon mini-me couperait la commande avant qu'elle finisse.
++  - Pour un usage "chat" simple sans gros outils : la valeur par défaut convient très bien, y compris sur un petit modèle lent (c'est la génération token-par-token qui compte, pas la vitesse globale).
++
++---
++
++## 4. `bashTimeout` — combien de temps une commande shell a le droit de tourner
++
++**En clair** : quand l'agent exécute une commande (`bash`), c'est le temps maximum avant que mini-me la tue de force, même si elle n'a rien renvoyé.
++
++- **Valeur par défaut** : `30 secondes`.
++- **Comment la régler** :
++  - Tâches rapides (lire un fichier, `git status`, `ls`) : le défaut de 30s est largement suffisant.
++  - Tâches lourdes attendues (compilation, tests, installation de dépendances, longue recherche) : augmente franchement, par exemple `2m`, `5m`, voire plus selon le projet.
++  - **Toujours augmenter `watchdogTimeout` en même temps** (voir section 3) — c'est le piège le plus courant : une commande se fait tuer par le chien de garde alors que `bashTimeout` lui laissait le temps.
++  - Ce réglage ne dépend pas vraiment de la taille du modèle, mais du type de projet sur lequel l'agent travaille.
++
++---
++
++## 5. `maxTurns` — combien d'allers-retours modèle ↔ outils sont autorisés pour une seule question
++
++**En clair** : pour répondre à une question, l'agent peut faire plusieurs tours : "je lance une commande" → "je regarde le résultat" → "j'en lance une autre" → etc. Ce réglage plafonne le nombre de ces tours avant que mini-me arrête l'agent (pour éviter qu'il boucle à l'infini).
++
++- **Valeur par défaut** : `10`.
++- **Valeur réellement utilisée dans les configurations livrées** : `40` — l'expérience montre que 10 est souvent trop bas pour des tâches de code réalistes avec un petit modèle, qui a besoin de plus d'itérations (relire, corriger, retenter) qu'un gros modèle.
++- **Comment la régler** :
++  - Tâche étroite, une seule action attendue (répondre à une question factuelle, un seul appel d'outil) : `8` à `15` suffit, et ça protège mieux contre les boucles.
++  - Agent de développement généraliste (explorer du code, éditer, tester) : `40` à `60` est raisonnable, surtout avec un petit modèle qui a besoin de plusieurs essais.
++  - Plus le modèle est petit/faible, plus il risque de boucler sans jamais conclure — associe un `maxTurns` généreux à une bonne détection de boucle plutôt que de mettre une valeur énorme "au cas où".
++
++---
++
++## 6. `maxOutput` — la taille maximale de ce qu'un outil peut renvoyer au modèle
++
++**En clair** : si une commande `bash` renvoie 500 000 caractères (un gros fichier de log, par exemple), on ne veut pas que ça remplisse d'un coup toute la mémoire du modèle. Ce réglage tronque le résultat avant de le montrer au modèle.
++
++- **Valeur par défaut** : `16000` caractères.
++- **Comment ça tronque** : pas juste en coupant à la fin — mini-me garde le **début** du résultat et jusqu'à 2000 caractères de la **fin**, car souvent l'information utile (erreur, résumé) est à la fin d'une sortie longue.
++- **Comment la régler** :
++  - Petit modèle à fenêtre de contexte réduite (8k-16k tokens) : **baisse** cette valeur, par exemple `4000` à `8000`, pour qu'une seule commande ne consomme pas un tiers de la mémoire disponible.
++  - Modèle avec une grande fenêtre de contexte, ou agent qui a vraiment besoin de voir des sorties complètes (ex: analyser un gros diff) : tu peux monter à `20000`-`30000`, mais garde en tête que chaque sortie "coûte" en tokens et accélère le moment où la compression du contexte (section 8) se déclenche.
++
++---
++
++## 7. `agentsMd` — comment l'agent lit ses instructions de projet
++
++**En clair** : `AGENTS.md` (ou équivalent) contient les instructions propres au projet que l'agent doit suivre. Ce bloc de réglages contrôle si/comment ce fichier est chargé.
++
++```yaml
++agentsMd:
++  enabled: true
++  path: "AGENTS.md"
++  maxChars: 0
++```
++
++- **`enabled`** — défaut : `true`. Active la lecture automatique du fichier.
++- **`path`** — défaut : `"AGENTS.md"`. Le nom/chemin du fichier à lire.
++- **`maxChars`** — défaut : `0` (= pas de limite).
++
++### Le point important sur `maxChars`
++
++Ce n'est **pas** une troncature. Si le fichier `AGENTS.md` dépasse `maxChars` caractères, il n'est **pas coupé** — il est **entièrement ignoré** (le code source dit explicitement : couper au milieu risquerait de supprimer justement la règle qui compte). La bannière de démarrage l'indique (`skipped (too long)`) plutôt que de faire semblant d'avoir lu le fichier en entier.
++
++- **Comment la régler** :
++  - **Même sans `maxChars`, mini-me te prévient** : la bannière de démarrage avertit quand `AGENTS.md` occupe **20 % ou plus** d'une fenêtre de contexte connue (estimation : nombre de caractères ÷ 3,5). Avec un petit modèle, c'est le signe qu'il faut raccourcir le fichier.
++  - **`maxChars` est une limite stricte en plus de cet avertissement.** Avec un petit modèle à faible fenêtre, un `AGENTS.md` trop long peut consommer une grosse part de la mémoire avant même que la conversation commence. Fixer `maxChars` garantit qu'il ne la dépassera jamais : au-delà, le fichier est ignoré et la bannière le dit, et tu sais qu'il faut le raccourcir.
++  - Pour calculer une valeur : 20 % de la fenêtre × 3,5. Exemple : fenêtre de 8192 tokens → 20 % = 1638 tokens → environ `maxChars: 5700`.
++  - Si ton `AGENTS.md` est court (quelques centaines de lignes maximum) et que ton modèle a une fenêtre confortable (32k+), tu peux laisser `0`.
++
++---
++
++## 8. `context` — la compression automatique de l'historique
++
++**En clair** : au fur et à mesure que la conversation avance, l'historique (questions, réponses, résultats de commandes) grandit. Sur un petit modèle à mémoire limitée, il arrive un moment où tout ne tient plus. Ce bloc décide **quand** et **comment** résumer automatiquement les anciens échanges pour faire de la place, sans perdre le fil.
++
++```yaml
++context:
++  enabled: false
++  threshold: 75
++  maxMessages: 80
++  keepLastTurns: 3
++  summaryMaxTokens: 1200
++  prompt: ""
++  showStats: true
++```
++
++| Sous-réglage | Défaut | Ce qu'il fait | Comment le régler |
++|---|---|---|---|
++| `enabled` | `false` | Active la compression automatique. Même désactivé, tu peux toujours lancer une compression manuelle. | **Active-le (`true`) pour tout petit modèle local** — c'est la protection principale contre le "contexte plein" qui fait planter ou dégrader l'agent. |
++| `threshold` | `75` (%) | Pourcentage de la fenêtre de contexte à partir duquel la compression se déclenche. 75 % laisse volontairement un quart de la mémoire libre pour la prochaine question, les résultats d'outils et la réponse. | Ne descends pas trop bas (tu compresserais trop souvent, donc tu perds en continuité) ; ne monte pas trop haut (tu risques de saturer avant que la compression ait pu agir). 70-80 % est une bonne plage. |
++| `maxMessages` | `80` | Déclencheur de secours basé sur le *nombre* de messages, utilisé quand la taille de la fenêtre est inconnue (`contextWindow: 0` et serveur muet sur le sujet). Une commande = 2 messages (l'appel + le résultat), donc 80 ≈ 30 commandes d'historique. | Le code justifie 80 ainsi : c'est à peu près le moment où un modèle local de 12B commence à ralentir. Sur un modèle plus petit, tu peux baisser cette valeur si tu remarques que l'agent devient plus lent ou confus avant d'atteindre 80 messages. Mets `0` pour désactiver ce déclencheur si tu es sûr de connaître `contextWindow`. |
++| `keepLastTurns` | `3` | Nombre de derniers tours de conversation gardés **intacts** (non résumés) — c'est là que l'agent "travaille" activement, le résumer le ferait rejouer ce qu'il vient juste de faire. | Garde au moins `2`-`3`. Monte-le un peu (`4`-`5`) si tu remarques que l'agent "oublie" une action toute récente juste après une compression. |
++| `summaryMaxTokens` | `1200` | Taille maximale du résumé généré pour remplacer les vieux échanges. Ce plafond empêche un modèle qui dérape de produire un résumé qui lui-même remplit la fenêtre qu'on cherchait à vider. | Pour un petit modèle, ne monte pas trop ce chiffre : un résumé doit rester compact. `1200` convient à la plupart des cas ; descends à `600`-`800` si tu veux économiser encore plus de place. |
++| `prompt` | `""` (prompt intégré) | Permet de remplacer le prompt utilisé pour demander le résumé. | Laisse vide sauf besoin spécifique (ex: vouloir que le résumé garde un format particulier). |
++| `showStats` | `true` | Affiche une ligne d'info après chaque compression (combien de tokens économisés, etc.). | Laisse activé, c'est utile pour vérifier que la compression fait bien son travail — désactive seulement si tu veux une sortie plus silencieuse. |
++
++**Astuce pratique** : la compression envoie le résumé au modèle **sans les outils actifs et sans le mode "raisonnement"**, justement pour que `summaryMaxTokens` ne soit pas gaspillé en réflexion plutôt qu'en résumé utile.
++
++---
++
++## Résumé — profils types
++
++| Situation | `firstTokenTimeout` | `watchdogTimeout` | `bashTimeout` | `maxTurns` | `maxOutput` | `context.enabled` |
++|---|---|---|---|---|---|---|
++| Petit modèle (≤ 8B), tâches courtes/chat, sans `bash` ou avec des commandes de moins de 20 s | `3m` (défaut) | `20s` (défaut) | `30s` (défaut) | `15` | `8000` | `true` |
++| Petit/moyen modèle, agent de code généraliste | `5m` | `2m` (aligné sur bashTimeout) | `2m` | `40` | `16000` | `true` |
++| Modèle plus gros ou machine modeste (CPU) | `10m` | `5m` | `5m` | `40`-`60` | `16000`-`24000` | `true` |
++
++Dans la première ligne, `watchdogTimeout` (20 s) est plus court que `bashTimeout` (30 s) : ce sont les valeurs par défaut, et elles ne conviennent que si aucune commande ne dure plus de 20 s. Dès que l'agent lance des commandes plus longues, aligne les deux comme dans les lignes suivantes (section 3).
++
++Ces profils sont des points de départ, pas des vérités absolues — ajuste en observant le comportement réel de ton modèle (est-ce qu'il boucle, est-ce qu'il se fait couper trop tôt, est-ce que le contexte se remplit trop vite).
++
++---
++
++## 9. Section sampling — comment le modèle choisit ses mots
++
++**En clair** : le "sampling" (échantillonnage), ce sont les réglages qui contrôlent la façon dont le modèle pioche le mot suivant parmi toutes les possibilités qu'il juge plausibles. C'est la partie qui décide si le modèle est **précis et prévisible** ou **créatif et varié**. Contrairement aux réglages précédents (timeouts, quotas), le sampling n'a pas de struct figée dans mini-me : c'est une liste libre de clés (`sampling:` dans le YAML) transmise quasiment telle quelle au serveur du modèle.
++
++```yaml
++sampling:
++  temperature: 0.0
++  top_p: 0.9
++  max_tokens: 4096
++```
++
++Ce sont les trois seules clés définies par défaut dans mini-me. Les autres (`top_k`, `min_p`, `repeat_penalty`...) ne sont pas fixées par défaut — à toi de les ajouter si ton serveur/modèle les supporte et si tu en as besoin.
++
++### `temperature` — le curseur "précis ↔ créatif"
++
++**En clair** : plus elle est proche de `0`, plus le modèle choisit systématiquement le mot qu'il juge le plus probable (réponses stables, reproductibles, parfois un peu rigides). Plus elle monte vers `1` (ou au-delà), plus il accepte de piocher des mots moins évidents (réponses plus variées, mais aussi plus de risques d'erreurs ou d'écarts).
++
++- **Défaut mini-me** : `0.0` — volontairement très bas, car mini-me est pensé pour un **agent de code**, où on veut de la précision et de la reproductibilité, pas de la créativité.
++- **Comment la régler pour un petit modèle** :
++  - Agent qui exécute des commandes, écrit du code, suit des instructions strictes : **garde `0.0`-`0.2`**. Un petit modèle est déjà plus sujet aux erreurs et aux boucles qu'un gros modèle ; une température basse réduit ce risque.
++  - Agent conversationnel, créatif, ou qui doit reformuler/brainstormer : monte à `0.5`-`0.8`. Au-delà de `0.8`, un petit modèle part plus facilement en incohérence.
++
++### `top_p` (nucleus sampling) — la largeur du choix
++
++**En clair** : au lieu de considérer tous les mots possibles, le modèle ne regarde que le plus petit groupe de mots dont la probabilité cumulée atteint ce pourcentage. `top_p: 0.9` veut dire "ne considère que les mots qui, ensemble, couvrent 90 % de la probabilité — ignore la longue traîne improbable".
++
++- **Défaut mini-me** : `0.9`.
++- **Comment la régler** : combiné à une `temperature` basse, `0.9` est déjà un bon compromis "sûr" pour un petit modèle. Tu peux descendre à `0.8` si tu veux encore réduire les écarts bizarres ; inutile de monter plus haut pour un agent de code.
++
++### `top_k` — limiter le nombre de candidats (optionnel, pas de défaut dans mini-me)
++
++**En clair** : ne garde que les `k` mots les plus probables à chaque étape, et ignore tout le reste, quel que soit `top_p`.
++
++- **Comment la régler** : les petits modèles (souvent Qwen, Gemma, Llama en petites tailles) n'ont pas tous la même sensibilité à `top_k` — certaines familles de modèles recommandent explicitement une valeur (par exemple `20`-`40`) dans leur fiche technique. **Vérifie les métadonnées/recommandations du modèle GGUF que tu utilises** plutôt que de deviner : un `top_k` mal choisi peut rendre un petit modèle plus répétitif ou au contraire plus instable.
++
++### `repeat_penalty` / `min_p` — anti-répétition (optionnel, pas de défaut dans mini-me)
++
++**En clair** : `repeat_penalty` pénalise le modèle s'il réutilise un mot déjà employé récemment (utile contre les boucles de répétition, un défaut classique des petits modèles). `min_p` est une alternative à `top_p` qui élimine les mots dont la probabilité est trop faible par rapport au mot le plus probable du moment.
++
++- **Comment les régler** : ce sont typiquement les réglages qui **varient le plus d'une famille de modèle à l'autre** — il n'existe pas de valeur universelle. La bonne pratique est de reprendre les valeurs recommandées par la fiche du modèle (souvent indiquées dans les métadonnées GGUF ou la documentation du modèle) plutôt que d'improviser. Si l'agent répète des phrases ou des actions en boucle, c'est souvent le premier réglage à ajuster, avec le détecteur de boucle de mini-me et `maxTurns` (section 5).
++
++### `max_tokens` — la longueur maximale d'une réponse
++
++**En clair** : combien de tokens le modèle a le droit de générer en une seule réponse avant d'être coupé.
++
++- **Défaut mini-me** : `4096`.
++- **Comment la régler** : pour un petit modèle avec une fenêtre de contexte réduite, vérifie que `max_tokens` laisse assez de place dans la fenêtre pour le prompt lui-même — `max_tokens` + taille du prompt ne doit pas dépasser `contextWindow`. Baisse-le (`1024`-`2048`) si tes réponses doivent rester courtes (ex: classification, extraction) ; garde la valeur par défaut pour un agent qui doit écrire du code ou des explications plus longues.
++
++### En résumé — philosophie du sampling dans mini-me
++
++mini-me part du principe qu'un **petit modèle local est un agent de code avant tout**, donc ses réglages de sampling par défaut privilégient la **précision et la reproductibilité** (`temperature: 0.0`) plutôt que la créativité. C'est le point de départ le plus sûr pour limiter les erreurs, les hallucinations de résultats de commandes et les boucles — quitte à l'assouplir toi-même si ton usage est plus conversationnel ou créatif.
++
++> Il n'existe pas aujourd'hui dans mini-me de "profil de sampling" automatique par famille de modèle — les valeurs par défaut sont génériques et volontairement conservatrices. Si tu changes de modèle, pense à revérifier ces réglages plutôt que de garder ceux d'un autre modèle par habitude.

added guides/tui-keyboard-shortcuts.md +121 -0 Viewed

new file mode 100644
@@ -0,0 +1,121 @@
	1	+# Keyboard shortcuts of the window (`mm -tui`)
	2	+
	3	+[Version française](raccourcis-clavier-tui.md)
	4	+
	5	+> Every key the window (`mm -tui`) understands, grouped by what you are doing. F1 shows a short version inside the window. The status bar at the bottom always shows `F1 help · Ctrl-Y copy · F2 mouse · Ctrl-C quit`.
	6	+
	7	+## The window in two parts
	8	+
	9	+The window has two places that can take the keys: the box at the bottom, where you type, and the conversation above it. Tab moves the focus from one to the other. At start-up the focus is on the box. While the focus is on the conversation, letters do nothing: press Tab to type again.
	10	+
	11	+## Type and send
	12	+
	13	+\| Key \| What it does \|
	14	+\|---\|---\|
	15	+\| `Enter` \| Sends what is in the box. An empty box sends nothing. \|
	16	+\| `Ctrl-J` or `Alt-Enter` \| A new line in the box, without sending. `Shift-Enter` cannot be told apart from `Enter` by a terminal, so it sends. \|
	17	+\| `←` `→` \| Move the cursor; at the start or end of a line, go to the previous or next line. \|
	18	+\| `↑` `↓` \| Move to the row above or below in the box — a long line wraps over several rows. On the first row, `↑` recalls your previous question (see below). \|
	19	+\| `Home` `End` \| Start or end of the line. \|
	20	+\| `Backspace` `Delete` \| Delete the character before or under the cursor. A collapsed paste (`[Pasted #1 · …]`) is deleted whole. \|
	21	+\| `Esc` \| When nothing is running: clears the box. \|
	22	+
	23	+## While the agent is working
	24	+
	25	+\| Key \| What it does \|
	26	+\|---\|---\|
	27	+\| `Esc` \| Stops the answer in progress (same as `/abort`) and says `🛑 Aborting…`. Pressed again when the turn does not stop, it tells you to use Ctrl-C. \|
	28	+\| `Ctrl-C` \| Stops the answer in progress. If it has already been asked to stop and has not, `Ctrl-C` closes mm. \|
	29	+\| `Enter` \| Stops the answer in progress and sends what you typed once it has stopped: you can change your mind without waiting. \|
	30	+
	31	+## Recall an earlier question
	32	+
	33	+Needs `sessions.enabled: true` in the agent's YAML.
	34	+
	35	+\| Key \| What it does \|
	36	+\|---\|---\|
	37	+\| `↑` (first row of the box) \| Puts your previous question in the box; again for the one before — this session first, then the project's earlier sessions. \|
	38	+\| `↓` (last row of the box) \| Goes back towards the newest question; past it, gives back what you were typing. \|
	39	+\| `Esc` \| Clears the recalled question, to type something else. \|
	40	+
	41	+A recalled question can be edited before you send it. With nothing to recall, `↑` and `↓` scroll the conversation instead.
	42	+
	43	+## Move through the conversation
	44	+
	45	+\| Key \| What it does \|
	46	+\|---\|---\|
	47	+\| `PgUp` `PgDn` \| One page up or down, wherever the focus is. \|
	48	+\| `↑` `↓` \| One line, when the focus is on the conversation (`Tab`). \|
	49	+\| `Home` `End` \| Top or bottom of the conversation, when the focus is on it. `End` also follows the answer again as it is written. \|
	50	+\| Mouse wheel \| Three lines up or down — only after `F2` (see below). \|
	51	+\| `Ctrl-L` \| Clears the displayed conversation. What the agent remembers is not touched: `/new` does that. \|
	52	+
	53	+## Complete a command, a file or a skill
	54	+
	55	+Typing `/` at the start of the box, `@` or `$` anywhere opens a list of choices above the box: commands, files and folders, skills.
	56	+
	57	+\| Key \| What it does \|
	58	+\|---\|---\|
	59	+\| `↑` `↓` \| Move in the list. \|
	60	+\| `Tab` \| Completes with the highlighted choice. \|
	61	+\| `Enter` \| Sends when what you typed is already complete; otherwise completes, like `Tab`. \|
	62	+\| `Esc` \| Closes the list until you type something else. \|
	63	+
	64	+## Paste long text
	65	+
	66	+Paste as usual with your terminal (`Cmd-V`, `Ctrl-Shift-V`, the right click…). A paste never sends anything, even when it holds line breaks. Longer than 3 lines or 200 characters, it shows as one token, `[Pasted #1 · 42 lines · 1.2k chars]`; the agent receives the whole text. `Backspace` or `Delete` removes the token, and the text with it.
	67	+
	68	+## Answer a permission
	69	+
	70	+With `yolo: false` (or an MCP tool marked `ask`), the box is replaced by a question such as `? bash: rm -rf build`. Only these keys work until you answer:
	71	+
	72	+\| Key \| Answer \|
	73	+\|---\|---\|
	74	+\| `a` \| Allow this call, once. \|
	75	+\| `s` \| Allow this tool for the rest of the session. \|
	76	+\| `r` or `Esc` \| Refuse this call. \|
	77	+\| `n` \| Never allow this tool in this session. \|
	78	+
	79	+## Answer the agent's questions
	80	+
	81	+When the agent asks you something (its `ask_user` tool), a small form replaces the box. The line under the question reminds you of the keys.
	82	+
	83	+\| Kind of question \| Keys \|
	84	+\|---\|---\|
	85	+\| Pick one \| `↑` `↓` (or `Tab`) to move, `Enter` to choose — or `1` to `9` to choose directly. \|
	86	+\| Pick several \| `↑` `↓` to move, `Space` to tick or untick, `Enter` to send (at least one ticked). \|
	87	+\| Yes or no \| `y` (or `o`) yes, `n` no — or `←` `→` then `Enter`. \|
	88	+\| Free text \| Type, `Backspace` to correct, `Enter` to send. \|
	89	+\| Any \| `Esc` declines to answer. \|
	90	+
	91	+## Copy, mouse, help, quit
	92	+
	93	+\| Key \| What it does \|
	94	+\|---\|---\|
	95	+\| `Ctrl-Y` \| Copies the last answer to the clipboard, as plain text (same as `/copy`; `/copy 2` the one before, `/copy all` the whole conversation). \|
	96	+\| `F2` \| Turns mouse capture on or off. Off (the default): select text with the mouse as in any terminal. On: the wheel scrolls the conversation, and `Shift`+drag selects. The status bar says which. \|
	97	+\| `F1` \| The commands and the main keys, in the conversation (same as `/help`). \|
	98	+\| `Ctrl-C` \| Closes mm when nothing is running. `/quit` does the same. \|
	99	+
	100	+## The `mm init` window
	101	+
	102	+`mm init` opens a window of its own, in the same style, to write a new agent.yaml (see [Create an agent with `mm init`](../docs/en/how-to/create-an-agent.md)).
	103	+
	104	+\| Key \| What it does \|
	105	+\|---\|---\|
	106	+\| `↑` `↓` `Home` `End` \| Move through the choices; the preview on the right follows the highlighted one. \|
	107	+\| `Enter` \| Answer and go to the next question; on the last screen, write the file. \|
	108	+\| `y` `n` \| Answer the yes-or-no question. \|
	109	+\| `Esc` \| Go back one question, taking its answer back. \|
	110	+\| `PgUp` `PgDn` \| Scroll the preview. \|
	111	+\| `Tab` \| On a screen narrower than 100 columns: show the preview in place of the question, and back. \|
	112	+\| `←` `→` \| In a text answer (the endpoint, the key's variable, the name, the file): move the cursor; typing inserts there. `Home` `End` (or `Ctrl-A` `Ctrl-E`) go to the start and the end; `Backspace` deletes before the cursor, `Delete` after it. \|
	113	+\| `Ctrl-U` \| Clear a text answer. \|
	114	+\| `Ctrl-C` \| Quit without writing anything. \|
	115	+
	116	+## Good to know
	117	+
	118	+- Keys depend on the terminal. `Alt-Enter`, `Home`, `End` and the function keys depend on how the terminal reports them; on a Mac laptop, `Fn` is often needed for `F1`, `F2`, `Home` and `End`. `Ctrl-J` always works for a new line.
	119	+- The window needs a real terminal. `mm -tui \| tee log.txt`, or any run where the input or the output is not a terminal, falls back to the line mode, where none of these keys apply.
	120	+
	121	+See also: [How to use the window mode](../docs/en/how-to/use-the-window-mode.md), [Slash commands and keys (reference)](../docs/en/reference/slash-commands.md).

++# Keyboard shortcuts of the window (`mm -tui`)
++
++*[Version française](raccourcis-clavier-tui.md)*
++
++> Every key the window (`mm -tui`) understands, grouped by what you are doing. **F1** shows a short version inside the window. The status bar at the bottom always shows `F1 help · Ctrl-Y copy · F2 mouse · Ctrl-C quit`.
++
++## The window in two parts
++
++The window has two places that can take the keys: the **box** at the bottom, where you type, and the **conversation** above it. **Tab** moves the focus from one to the other. At start-up the focus is on the box. While the focus is on the conversation, letters do nothing: press Tab to type again.
++
++## Type and send
++
++| Key | What it does |
++|---|---|
++| `Enter` | Sends what is in the box. An empty box sends nothing. |
++| `Ctrl-J` or `Alt-Enter` | A new line in the box, without sending. `Shift-Enter` cannot be told apart from `Enter` by a terminal, so it sends. |
++| `←` `→` | Move the cursor; at the start or end of a line, go to the previous or next line. |
++| `↑` `↓` | Move to the row above or below in the box — a long line wraps over several rows. On the first row, `↑` recalls your previous question (see below). |
++| `Home` `End` | Start or end of the line. |
++| `Backspace` `Delete` | Delete the character before or under the cursor. A collapsed paste (`[Pasted #1 · …]`) is deleted whole. |
++| `Esc` | When nothing is running: clears the box. |
++
++## While the agent is working
++
++| Key | What it does |
++|---|---|
++| `Esc` | Stops the answer in progress (same as `/abort`) and says `🛑 Aborting…`. Pressed again when the turn does not stop, it tells you to use Ctrl-C. |
++| `Ctrl-C` | Stops the answer in progress. If it has already been asked to stop and has not, `Ctrl-C` closes mm. |
++| `Enter` | Stops the answer in progress and sends what you typed once it has stopped: you can change your mind without waiting. |
++
++## Recall an earlier question
++
++Needs `sessions.enabled: true` in the agent's YAML.
++
++| Key | What it does |
++|---|---|
++| `↑` (first row of the box) | Puts your previous question in the box; again for the one before — this session first, then the project's earlier sessions. |
++| `↓` (last row of the box) | Goes back towards the newest question; past it, gives back what you were typing. |
++| `Esc` | Clears the recalled question, to type something else. |
++
++A recalled question can be edited before you send it. With nothing to recall, `↑` and `↓` scroll the conversation instead.
++
++## Move through the conversation
++
++| Key | What it does |
++|---|---|
++| `PgUp` `PgDn` | One page up or down, wherever the focus is. |
++| `↑` `↓` | One line, when the focus is on the conversation (`Tab`). |
++| `Home` `End` | Top or bottom of the conversation, when the focus is on it. `End` also follows the answer again as it is written. |
++| Mouse wheel | Three lines up or down — only after `F2` (see below). |
++| `Ctrl-L` | Clears the displayed conversation. What the agent remembers is not touched: `/new` does that. |
++
++## Complete a command, a file or a skill
++
++Typing `/` at the start of the box, `@` or `$` anywhere opens a list of choices above the box: commands, files and folders, skills.
++
++| Key | What it does |
++|---|---|
++| `↑` `↓` | Move in the list. |
++| `Tab` | Completes with the highlighted choice. |
++| `Enter` | Sends when what you typed is already complete; otherwise completes, like `Tab`. |
++| `Esc` | Closes the list until you type something else. |
++
++## Paste long text
++
++Paste as usual with your terminal (`Cmd-V`, `Ctrl-Shift-V`, the right click…). A paste never sends anything, even when it holds line breaks. Longer than 3 lines or 200 characters, it shows as one token, `[Pasted #1 · 42 lines · 1.2k chars]`; the agent receives the whole text. `Backspace` or `Delete` removes the token, and the text with it.
++
++## Answer a permission
++
++With `yolo: false` (or an MCP tool marked `ask`), the box is replaced by a question such as `? bash: rm -rf build`. Only these keys work until you answer:
++
++| Key | Answer |
++|---|---|
++| `a` | Allow this call, once. |
++| `s` | Allow this tool for the rest of the session. |
++| `r` or `Esc` | Refuse this call. |
++| `n` | Never allow this tool in this session. |
++
++## Answer the agent's questions
++
++When the agent asks you something (its `ask_user` tool), a small form replaces the box. The line under the question reminds you of the keys.
++
++| Kind of question | Keys |
++|---|---|
++| Pick one | `↑` `↓` (or `Tab`) to move, `Enter` to choose — or `1` to `9` to choose directly. |
++| Pick several | `↑` `↓` to move, `Space` to tick or untick, `Enter` to send (at least one ticked). |
++| Yes or no | `y` (or `o`) yes, `n` no — or `←` `→` then `Enter`. |
++| Free text | Type, `Backspace` to correct, `Enter` to send. |
++| Any | `Esc` declines to answer. |
++
++## Copy, mouse, help, quit
++
++| Key | What it does |
++|---|---|
++| `Ctrl-Y` | Copies the last answer to the clipboard, as plain text (same as `/copy`; `/copy 2` the one before, `/copy all` the whole conversation). |
++| `F2` | Turns mouse capture on or off. **Off** (the default): select text with the mouse as in any terminal. **On**: the wheel scrolls the conversation, and `Shift`+drag selects. The status bar says which. |
++| `F1` | The commands and the main keys, in the conversation (same as `/help`). |
++| `Ctrl-C` | Closes mm when nothing is running. `/quit` does the same. |
++
++## The `mm init` window
++
++`mm init` opens a window of its own, in the same style, to write a new agent.yaml (see [Create an agent with `mm init`](../docs/en/how-to/create-an-agent.md)).
++
++| Key | What it does |
++|---|---|
++| `↑` `↓` `Home` `End` | Move through the choices; the preview on the right follows the highlighted one. |
++| `Enter` | Answer and go to the next question; on the last screen, write the file. |
++| `y` `n` | Answer the yes-or-no question. |
++| `Esc` | Go back one question, taking its answer back. |
++| `PgUp` `PgDn` | Scroll the preview. |
++| `Tab` | On a screen narrower than 100 columns: show the preview in place of the question, and back. |
++| `←` `→` | In a text answer (the endpoint, the key's variable, the name, the file): move the cursor; typing inserts there. `Home` `End` (or `Ctrl-A` `Ctrl-E`) go to the start and the end; `Backspace` deletes before the cursor, `Delete` after it. |
++| `Ctrl-U` | Clear a text answer. |
++| `Ctrl-C` | Quit without writing anything. |
++
++## Good to know
++
++- **Keys depend on the terminal.** `Alt-Enter`, `Home`, `End` and the function keys depend on how the terminal reports them; on a Mac laptop, `Fn` is often needed for `F1`, `F2`, `Home` and `End`. `Ctrl-J` always works for a new line.
++- **The window needs a real terminal.** `mm -tui | tee log.txt`, or any run where the input or the output is not a terminal, falls back to the line mode, where none of these keys apply.
++
++See also: [How to use the window mode](../docs/en/how-to/use-the-window-mode.md), [Slash commands and keys (reference)](../docs/en/reference/slash-commands.md).

modified internal/version/version.go +1 -1 Viewed

@@ -4,7 +4,7 @@
4	4	// question without anyone having to remember a step:
5	5	//
6	6	// 1. A release binary carries its tag, stamped at link time by
7		-// 02-build-releases.sh:
	7	+// local-ci-2-build.sh:
8	8	//
9	9	// go build -ldflags "-X mm/internal/version.stamped=v0.0.3"
10	10	//

  // question without anyone having to remember a step:
  //
  //  1. A release binary carries its tag, stamped at link time by
--//     02-build-releases.sh:
++//     local-ci-2-build.sh:
  //
  //     go build -ldflags "-X mm/internal/version.stamped=v0.0.3"
  //

modified local-ci-1-check.sh +5 -1 Viewed

@@ -3,7 +3,11 @@
3	3	source "$(dirname "$0")/local-ci-0-common.sh"
4	4
5	5	echo "==> gofmt"
6		-unformatted="$(git ls-files '*.go' \| xargs gofmt -l)"
	6	+# The files on disk, not git's index: a folder moved but not yet staged is still
	7	+# in the index under its old path, and gofmt stops on a path that is gone.
	8	+unformatted="$(git ls-files --cached --others --exclude-standard '*.go' \| while read -r file; do
	9	+ [ -f "${file}" ] && printf '%s\0' "${file}"
	10	+done \| xargs -0 gofmt -l)"
7	11	if [ -n "${unformatted}" ]; then
8	12	echo "❌ not formatted:"
9	13	echo "${unformatted}"

  source "$(dirname "$0")/local-ci-0-common.sh"
  echo "==> gofmt"
--unformatted="$(git ls-files '*.go' | xargs gofmt -l)"
++# The files on disk, not git's index: a folder moved but not yet staged is still
++# in the index under its old path, and gofmt stops on a path that is gone.
++unformatted="$(git ls-files --cached --others --exclude-standard '*.go' | while read -r file; do
++	[ -f "${file}" ] && printf '%s\0' "${file}"
++done | xargs -0 gofmt -l)"
  if [ -n "${unformatted}" ]; then
  	echo "❌ not formatted:"
  	echo "${unformatted}"

modified local-ci-2-build.sh +150 -1 Viewed

@@ -1,6 +1,155 @@
1	1	#!/usr/bin/env bash
2	2	# local-ci-2-build.sh — the binaries for every platform, in release/<TAG>/.
	3	+#
	4	+# Only the Go toolchain is needed: every binary is a plain `go build`.
	5	+#
	6	+# What ends up in release/<TAG>/:
	7	+# mm-<version>-<os>-<arch>[.exe] one binary per platform
	8	+# SHA256SUMS checksums of the binaries
	9	+# README.md download table + how to run
3	10	source "$(dirname "$0")/local-ci-0-common.sh"
4	11
5		-bash ./02-build-releases.sh "${TAG}"
	12	+ABOUT="${ABOUT:-Mini Me ${TAG}}"
	13	+
	14	+# A tag that is not vMAJOR.MINOR.PATCH[-prerelease] is a typo — measured: a
	15	+# .release.env with "v0.o.0" (letter o) would otherwise build and stage
	16	+# binaries nobody can name.
	17	+if ! [[ "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
	18	+ echo "❌ TAG must look like v1.2.3 or v1.2.3-rc.1, got '${TAG}' (check .release.env)"
	19	+ exit 1
	20	+fi
	21	+
	22	+# The platforms a release is built for. Add or remove a line and everything
	23	+# below follows: the builds, the checksums and the README.
	24	+PLATFORMS=(
	25	+ "darwin/arm64"
	26	+ "linux/amd64"
	27	+ "linux/arm64"
	28	+ "windows/amd64"
	29	+ "windows/arm64"
	30	+)
	31	+
	32	+# The tag is "v0.2.0"; the assets carry the bare version, "0.2.0".
	33	+VERSION="${TAG#v}"
	34	+RELEASES_DIR="release/${TAG}"
	35	+
	36	+# -trimpath keeps this machine's paths out of binaries that go to strangers;
	37	+# -s -w drops the symbol table and DWARF, about a third of the size. -X stamps
	38	+# the tag into the binary, which is what `mm --version`, the start-up banner
	39	+# and the window's status bar report: without it they fall back to the commit
	40	+# Go embeds, and a downloaded release would not know its own name.
	41	+BUILD_FLAGS=(-trimpath -ldflags "-s -w -X mm/internal/version.stamped=${TAG}")
	42	+
	43	+echo "🚀 Building Mini Me ${TAG} — ${ABOUT}"
	44	+echo "🐹 $(go version)"
	45	+
	46	+rm -rf "${RELEASES_DIR}"
	47	+mkdir -p "${RELEASES_DIR}"
	48	+
	49	+# assetName is what the binary for a platform is called once staged. Windows
	50	+# executables carry .exe, or Windows will not run them.
	51	+assetName() {
	52	+ local goos=$1 goarch=$2
	53	+ local name="mm-${VERSION}-${goos}-${goarch}"
	54	+ if [ "${goos}" = "windows" ]; then
	55	+ name="${name}.exe"
	56	+ fi
	57	+ printf '%s\n' "${name}"
	58	+}
	59	+
	60	+echo ""
	61	+echo "🔨 Cross-compiling for ${#PLATFORMS[@]} platforms..."
	62	+
	63	+for platform in "${PLATFORMS[@]}"; do
	64	+ goos="${platform%/*}"
	65	+ goarch="${platform#*/}"
	66	+ asset="$(assetName "${goos}" "${goarch}")"
	67	+
	68	+ # CGO_ENABLED=0: nothing to link against on the other side of a
	69	+ # cross-compile, and mm needs no C — genkit, tcell and the ACP SDK are pure
	70	+ # Go. Without it, a darwin build from a Linux box fails at link time.
	71	+ if ! CGO_ENABLED=0 GOOS="${goos}" GOARCH="${goarch}" \
	72	+ go build "${BUILD_FLAGS[@]}" -o "${RELEASES_DIR}/${asset}" .; then
	73	+ echo " ❌ ${platform}"
	74	+ exit 1
	75	+ fi
	76	+ echo " ✅ ${asset}"
	77	+done
	78	+
	79	+# The binary for this machine is the only one that can run here, and running
	80	+# it is the one proof that what ships starts at all: -h prints the usage and
	81	+# exits 0 before any config or model server is looked for.
	82	+HOST_ASSET="$(assetName "$(go env GOOS)" "$(go env GOARCH)")"
	83	+if [ -x "${RELEASES_DIR}/${HOST_ASSET}" ]; then
	84	+ if ! "${RELEASES_DIR}/${HOST_ASSET}" -h >/dev/null 2>&1; then
	85	+ echo " ❌ ${HOST_ASSET} does not start (mm -h failed)"
	86	+ exit 1
	87	+ fi
	88	+ # The stamp is a string passed to the linker: a renamed package or variable
	89	+ # does not fail the build, it silently leaves the binary reporting a commit
	90	+ # hash. Ask the binary itself, here, while the release can still be stopped.
	91	+ if ! "${RELEASES_DIR}/${HOST_ASSET}" --version \| grep -q -- "${TAG}"; then
	92	+ echo " ❌ ${HOST_ASSET} does not report ${TAG}: $("${RELEASES_DIR}/${HOST_ASSET}" --version)"
	93	+ echo " 💡 check -X mm/internal/version.stamped in BUILD_FLAGS"
	94	+ exit 1
	95	+ fi
	96	+ echo " ✅ ${HOST_ASSET} starts and reports ${TAG}"
	97	+fi
	98	+
	99	+# checksum runs whichever of the two tools this machine has: sha256sum on
	100	+# Linux, shasum on macOS.
	101	+checksum() {
	102	+ if command -v sha256sum >/dev/null 2>&1; then
	103	+ sha256sum "$@"
	104	+ else
	105	+ shasum -a 256 "$@"
	106	+ fi
	107	+}
	108	+
	109	+# One SHA256SUMS for every platform, names only (no directory), which is what
	110	+# `sha256sum -c` expects to read next to the downloaded files.
	111	+(cd "${RELEASES_DIR}" && checksum mm-"${VERSION}"-* >SHA256SUMS)
	112	+echo " ✅ SHA256SUMS"
	113	+
	114	+# downloadTable lists the platforms as a Markdown table, so the README grows
	115	+# and shrinks with PLATFORMS rather than repeating it by hand.
	116	+downloadTable() {
	117	+ printf '\| Platform \| Download \|\n\|---\|---\|\n'
	118	+ for platform in "${PLATFORMS[@]}"; do
	119	+ local goos="${platform%/}" goarch="${platform#/}"
	120	+ # shellcheck disable=SC2016 # the backticks are Markdown code spans, not a command substitution
	121	+ printf '\| %s \| `%s` \|\n' "${platform}" "$(assetName "${goos}" "${goarch}")"
	122	+ done
	123	+}
	124	+
	125	+cat >"${RELEASES_DIR}/README.md" <<EOM
	126	+# Mini Me ${TAG}
	127	+
	128	+${ABOUT}
	129	+
	130	+Built with $(go env GOVERSION), CGO disabled. No runtime dependency besides a
	131	+model server (Docker Model Runner or llama-server).
	132	+
	133	+$(downloadTable)
	134	+
	135	+## Running it
	136	+
	137	+ chmod +x mm-${VERSION}-<platform>
	138	+ ./mm-${VERSION}-<platform> agent.yaml # line mode
	139	+ ./mm-${VERSION}-<platform> -tui agent.yaml # window mode
	140	+ ./mm-${VERSION}-<platform> -acp # from an editor (Zed, …)
	141	+
	142	+On macOS, an unsigned download is quarantined until you say otherwise:
	143	+
	144	+ xattr -d com.apple.quarantine mm-${VERSION}-darwin-arm64
	145	+
	146	+## Verifying the download
	147	+
	148	+ sha256sum -c SHA256SUMS --ignore-missing # shasum -a 256 -c on macOS
	149	+EOM
	150	+echo " ✅ README.md"
	151	+
	152	+echo ""
	153	+echo "✨ Build complete!"
	154	+ls -lh "${RELEASES_DIR}"
6	155	echo "✅ ${assets_dir}/ is ready"

  #!/usr/bin/env bash
  # local-ci-2-build.sh — the binaries for every platform, in release/<TAG>/.
++#
++# Only the Go toolchain is needed: every binary is a plain `go build`.
++#
++# What ends up in release/<TAG>/:
++#   mm-<version>-<os>-<arch>[.exe]   one binary per platform
++#   SHA256SUMS                       checksums of the binaries
++#   README.md                        download table + how to run
  source "$(dirname "$0")/local-ci-0-common.sh"
--bash ./02-build-releases.sh "${TAG}"
++ABOUT="${ABOUT:-Mini Me ${TAG}}"
++
++# A tag that is not vMAJOR.MINOR.PATCH[-prerelease] is a typo — measured: a
++# .release.env with "v0.o.0" (letter o) would otherwise build and stage
++# binaries nobody can name.
++if ! [[ "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
++	echo "❌ TAG must look like v1.2.3 or v1.2.3-rc.1, got '${TAG}' (check .release.env)"
++	exit 1
++fi
++
++# The platforms a release is built for. Add or remove a line and everything
++# below follows: the builds, the checksums and the README.
++PLATFORMS=(
++	"darwin/arm64"
++	"linux/amd64"
++	"linux/arm64"
++	"windows/amd64"
++	"windows/arm64"
++)
++
++# The tag is "v0.2.0"; the assets carry the bare version, "0.2.0".
++VERSION="${TAG#v}"
++RELEASES_DIR="release/${TAG}"
++
++# -trimpath keeps this machine's paths out of binaries that go to strangers;
++# -s -w drops the symbol table and DWARF, about a third of the size. -X stamps
++# the tag into the binary, which is what `mm --version`, the start-up banner
++# and the window's status bar report: without it they fall back to the commit
++# Go embeds, and a downloaded release would not know its own name.
++BUILD_FLAGS=(-trimpath -ldflags "-s -w -X mm/internal/version.stamped=${TAG}")
++
++echo "🚀 Building Mini Me ${TAG} — ${ABOUT}"
++echo "🐹 $(go version)"
++
++rm -rf "${RELEASES_DIR}"
++mkdir -p "${RELEASES_DIR}"
++
++# assetName is what the binary for a platform is called once staged. Windows
++# executables carry .exe, or Windows will not run them.
++assetName() {
++	local goos=$1 goarch=$2
++	local name="mm-${VERSION}-${goos}-${goarch}"
++	if [ "${goos}" = "windows" ]; then
++		name="${name}.exe"
++	fi
++	printf '%s\n' "${name}"
++}
++
++echo ""
++echo "🔨 Cross-compiling for ${#PLATFORMS[@]} platforms..."
++
++for platform in "${PLATFORMS[@]}"; do
++	goos="${platform%/*}"
++	goarch="${platform#*/}"
++	asset="$(assetName "${goos}" "${goarch}")"
++
++	# CGO_ENABLED=0: nothing to link against on the other side of a
++	# cross-compile, and mm needs no C — genkit, tcell and the ACP SDK are pure
++	# Go. Without it, a darwin build from a Linux box fails at link time.
++	if ! CGO_ENABLED=0 GOOS="${goos}" GOARCH="${goarch}" \
++		go build "${BUILD_FLAGS[@]}" -o "${RELEASES_DIR}/${asset}" .; then
++		echo "   ❌ ${platform}"
++		exit 1
++	fi
++	echo "   ✅ ${asset}"
++done
++
++# The binary for this machine is the only one that can run here, and running
++# it is the one proof that what ships starts at all: -h prints the usage and
++# exits 0 before any config or model server is looked for.
++HOST_ASSET="$(assetName "$(go env GOOS)" "$(go env GOARCH)")"
++if [ -x "${RELEASES_DIR}/${HOST_ASSET}" ]; then
++	if ! "${RELEASES_DIR}/${HOST_ASSET}" -h >/dev/null 2>&1; then
++		echo "   ❌ ${HOST_ASSET} does not start (mm -h failed)"
++		exit 1
++	fi
++	# The stamp is a string passed to the linker: a renamed package or variable
++	# does not fail the build, it silently leaves the binary reporting a commit
++	# hash. Ask the binary itself, here, while the release can still be stopped.
++	if ! "${RELEASES_DIR}/${HOST_ASSET}" --version | grep -q -- "${TAG}"; then
++		echo "   ❌ ${HOST_ASSET} does not report ${TAG}: $("${RELEASES_DIR}/${HOST_ASSET}" --version)"
++		echo "   💡 check -X mm/internal/version.stamped in BUILD_FLAGS"
++		exit 1
++	fi
++	echo "   ✅ ${HOST_ASSET} starts and reports ${TAG}"
++fi
++
++# checksum runs whichever of the two tools this machine has: sha256sum on
++# Linux, shasum on macOS.
++checksum() {
++	if command -v sha256sum >/dev/null 2>&1; then
++		sha256sum "$@"
++	else
++		shasum -a 256 "$@"
++	fi
++}
++
++# One SHA256SUMS for every platform, names only (no directory), which is what
++# `sha256sum -c` expects to read next to the downloaded files.
++(cd "${RELEASES_DIR}" && checksum mm-"${VERSION}"-* >SHA256SUMS)
++echo "   ✅ SHA256SUMS"
++
++# downloadTable lists the platforms as a Markdown table, so the README grows
++# and shrinks with PLATFORMS rather than repeating it by hand.
++downloadTable() {
++	printf '| Platform | Download |\n|---|---|\n'
++	for platform in "${PLATFORMS[@]}"; do
++		local goos="${platform%/*}" goarch="${platform#*/}"
++		# shellcheck disable=SC2016 # the backticks are Markdown code spans, not a command substitution
++		printf '| %s | `%s` |\n' "${platform}" "$(assetName "${goos}" "${goarch}")"
++	done
++}
++
++cat >"${RELEASES_DIR}/README.md" <<EOM
++# Mini Me ${TAG}
++
++${ABOUT}
++
++Built with $(go env GOVERSION), CGO disabled. No runtime dependency besides a
++model server (Docker Model Runner or llama-server).
++
++$(downloadTable)
++
++## Running it
++
++    chmod +x mm-${VERSION}-<platform>
++    ./mm-${VERSION}-<platform> agent.yaml          # line mode
++    ./mm-${VERSION}-<platform> -tui agent.yaml     # window mode
++    ./mm-${VERSION}-<platform> -acp                # from an editor (Zed, …)
++
++On macOS, an unsigned download is quarantined until you say otherwise:
++
++    xattr -d com.apple.quarantine mm-${VERSION}-darwin-arm64
++
++## Verifying the download
++
++    sha256sum -c SHA256SUMS --ignore-missing     # shasum -a 256 -c on macOS
++EOM
++echo "   ✅ README.md"
++
++echo ""
++echo "✨ Build complete!"
++ls -lh "${RELEASES_DIR}"
  echo "✅ ${assets_dir}/ is ready"

modified release-notes/v1.0.1.en.md +1 -1 Viewed

@@ -82,7 +82,7 @@ Messages typed during an answer wait their turn, the window shows when the model
82	82	- [`demos/auto-pull/`](../demos/auto-pull/): `autoPull` with SmolLM2-135M. It has a single agent, a team, and a misspelt repository name.
83	83	- [`demos/coding-helpers-unload-option/`](../demos/coding-helpers-unload-option/): `unloadModels: true` on `mmConfigs` entries.
84	84	- [`demos/coding-helpers/`](../demos/coding-helpers/): it now uses `preAsk` / `postAsk` unload hooks, so its models are never loaded together. A Rust question took 37 s.
85		-- [`dev.team/`](../dev.team/): a team of five agents for a 32 GB laptop (coordinator, reformulator, coder, reviewer, tutor), with diagrams and a Docker sandbox set-up for Zed. Bug fixes, lessons and reviews worked in the measurements. New features did not yet.
	85	+- [`demos/dev.team/`](../demos/dev.team/): a team of five agents for a 32 GB laptop (coordinator, reformulator, coder, reviewer, tutor), with diagrams and a Docker sandbox set-up for Zed. Bug fixes, lessons and reviews worked in the measurements. New features did not yet.
86	86
87	87	## Documentation
88	88

  - [`demos/auto-pull/`](../demos/auto-pull/): `autoPull` with SmolLM2-135M. It has a single agent, a team, and a misspelt repository name.
  - [`demos/coding-helpers-unload-option/`](../demos/coding-helpers-unload-option/): `unloadModels: true` on `mmConfigs` entries.
  - [`demos/coding-helpers/`](../demos/coding-helpers/): it now uses `preAsk` / `postAsk` unload hooks, so its models are never loaded together. A Rust question took 37 s.
--- [`dev.team/`](../dev.team/): a team of five agents for a 32 GB laptop (coordinator, reformulator, coder, reviewer, tutor), with diagrams and a Docker sandbox set-up for Zed. Bug fixes, lessons and reviews worked in the measurements. New features did not yet.
++- [`demos/dev.team/`](../demos/dev.team/): a team of five agents for a 32 GB laptop (coordinator, reformulator, coder, reviewer, tutor), with diagrams and a Docker sandbox set-up for Zed. Bug fixes, lessons and reviews worked in the measurements. New features did not yet.
  ## Documentation

modified release-notes/v1.0.1.fr.md +1 -1 Viewed

@@ -87,7 +87,7 @@ Les messages tapés pendant une réponse attendent leur tour. La fenêtre signal
87	87	- [`demos/auto-pull/`](../demos/auto-pull/) : `autoPull` avec SmolLM2-135M, avec un agent seul, une équipe, et un nom de dépôt mal orthographié.
88	88	- [`demos/coding-helpers-unload-option/`](../demos/coding-helpers-unload-option/) : `unloadModels: true` sur les entrées `mmConfigs`.
89	89	- [`demos/coding-helpers/`](../demos/coding-helpers/) : ses hooks de déchargement `preAsk` / `postAsk` font que ses modèles ne sont jamais chargés ensemble. Une question Rust a pris 37 s.
90		-- [`dev.team/`](../dev.team/) : une équipe de cinq agents pour un portable de 32 Go (coordinateur, reformulateur, codeur, relecteur, tuteur), avec diagrammes et une configuration de bac à sable Docker pour Zed. Mesures :
	90	+- [`demos/dev.team/`](../demos/dev.team/) : une équipe de cinq agents pour un portable de 32 Go (coordinateur, reformulateur, codeur, relecteur, tuteur), avec diagrammes et une configuration de bac à sable Docker pour Zed. Mesures :
91	91	- les corrections de bugs, les leçons et les relectures fonctionnent ;
92	92	- les nouvelles fonctionnalités, pas encore.
93	93

  - [`demos/auto-pull/`](../demos/auto-pull/) : `autoPull` avec SmolLM2-135M, avec un agent seul, une équipe, et un nom de dépôt mal orthographié.
  - [`demos/coding-helpers-unload-option/`](../demos/coding-helpers-unload-option/) : `unloadModels: true` sur les entrées `mmConfigs`.
  - [`demos/coding-helpers/`](../demos/coding-helpers/) : ses hooks de déchargement `preAsk` / `postAsk` font que ses modèles ne sont jamais chargés ensemble. Une question Rust a pris 37 s.
--- [`dev.team/`](../dev.team/) : une équipe de cinq agents pour un portable de 32 Go (coordinateur, reformulateur, codeur, relecteur, tuteur), avec diagrammes et une configuration de bac à sable Docker pour Zed. Mesures :
++- [`demos/dev.team/`](../demos/dev.team/) : une équipe de cinq agents pour un portable de 32 Go (coordinateur, reformulateur, codeur, relecteur, tuteur), avec diagrammes et une configuration de bac à sable Docker pour Zed. Mesures :
    - les corrections de bugs, les leçons et les relectures fonctionnent ;
    - les nouvelles fonctionnalités, pas encore.

🛟 Updated.