rickub
bots-garden/sidekickspublic Fork
⑂ 2e8042b
Branches
feature/1st-release feature/clear-history feature/file-preview feature/initialize feature/m1-foundations feature/m2-chat feature/m3-channels-multi-agents feature/m4-agents-workspace main
Tags
license m1-foundation-start specifications v0.1.0 v1.0.0 v1.0.0-macos v1.1.0 v1.2.0 View all branches → View all tags →
Commits
⬇ Clone ▾
git clone https://git.rickub.com/bots-garden/sidekicks.git
git clone ssh://git@rickub.com/bots-garden/sidekicks.git

Host key fingerprint (ed25519): SHA256:iycHnxEyq0Q7uyVpB7JlznP0G7JrTPXLYRcAU5CSLhc — verify it before your first connect.

Download ZIP

🛟 Updated.

k33g committed 2026-10-29T10:18:12+01:00 Browse files
2e8042b parent: d216d2b
modified .memory/handoffs/2026-10-29-milestone-initialize.md +1 -1
@@ -11,7 +11,7 @@ Initialize is implemented on branch `feature/initialize` (not committed by the a
1111
1212 ## Next steps
1313
14-1. Owner: review, commit, run the macOS check of #3.
14+1. Owner: review, commit, then follow `docs/fr/how-to/tester-la-milestone-initialize-sous-macos.md` (EN: `docs/en/how-to/test-milestone-initialize-on-macos.md`) — parts 4–5 close #3 and the milestone.
1515 2. Owner: decide whether to run the qlty gate (needs a sandbox with the dev-toolkit kit) before M1.
1616 3. Start M1 with #8 (project from `wails3 init -t svelte`, merged into the existing root `go.mod`; keep the Makefile as entry point; licence headers), then #9 (loader on top of `schema`), #10 (`internal/acp` wrapping coder/acp-go-sdk; `realagents` build tag), #11, #12, #13.
1717
@@ -11,7 +11,7 @@ Initialize is implemented on branch `feature/initialize` (not committed by the a
11 11
12 ## Next steps12 ## Next steps
13 13
14-1. Owner: review, commit, run the macOS check of #3.14+1. Owner: review, commit, then follow `docs/fr/how-to/tester-la-milestone-initialize-sous-macos.md` (EN: `docs/en/how-to/test-milestone-initialize-on-macos.md`) — parts 4–5 close #3 and the milestone.
15 2. Owner: decide whether to run the qlty gate (needs a sandbox with the dev-toolkit kit) before M1.15 2. Owner: decide whether to run the qlty gate (needs a sandbox with the dev-toolkit kit) before M1.
16 3. Start M1 with #8 (project from `wails3 init -t svelte`, merged into the existing root `go.mod`; keep the Makefile as entry point; licence headers), then #9 (loader on top of `schema`), #10 (`internal/acp` wrapping coder/acp-go-sdk; `realagents` build tag), #11, #12, #13.16 3. Start M1 with #8 (project from `wails3 init -t svelte`, merged into the existing root `go.mod`; keep the Makefile as entry point; licence headers), then #9 (loader on top of `schema`), #10 (`internal/acp` wrapping coder/acp-go-sdk; `realagents` build tag), #11, #12, #13.
17 17
modified .memory/history.md +7 -0
@@ -16,3 +16,10 @@
1616 - **Tests**: `make test` — Go schema tests (4 valid + 12 invalid documents, example) and 14 shell tests; all pass, stable over 8 runs. Real-agent captures with Alice, Riker (allow/reject), Garfield (cancel, command), one agent at a time, models unloaded.
1717 - **Quality**: qlty unavailable in this sandbox → gate **not measured**. Substitutes run: gofmt, go vet (3 modules), bash -n, svelte-check (0/0), make test.
1818 - **Docs**: `docs/README.md` selector; `docs/en` and `docs/fr`: tutorial (first ACP exchange), how-to (run tests, run a test agent), reference (configuration + schema package, agents.sh), explanation (why ACP, UI stack, architecture, memory and local models).
19+
20+## 2026-10-29 — macOS test guide for milestone Initialize
21+
22+- **Goal**: a guide to test what Initialize produced when the owner is on a Mac.
23+- **Changes**: `docs/fr/how-to/tester-la-milestone-initialize-sous-macos.md`, `docs/en/how-to/test-milestone-initialize-on-macos.md`, both indexes; comment on #3. Fixed `spikes/wails-ui/README.md`: the `.app` comes from `wails3 package`, not `wails3 build`.
24+- **Tests**: guide commands cross-checked against the sandbox runs and the Wails v3 CLI (`wails3 package` exists, darwin Taskfile creates `bin/wails-ui.app`); not run on a Mac.
25+- **Docs**: how-to in EN and FR.
@@ -16,3 +16,10 @@
16 - **Tests**: `make test` — Go schema tests (4 valid + 12 invalid documents, example) and 14 shell tests; all pass, stable over 8 runs. Real-agent captures with Alice, Riker (allow/reject), Garfield (cancel, command), one agent at a time, models unloaded.16 - **Tests**: `make test` — Go schema tests (4 valid + 12 invalid documents, example) and 14 shell tests; all pass, stable over 8 runs. Real-agent captures with Alice, Riker (allow/reject), Garfield (cancel, command), one agent at a time, models unloaded.
17 - **Quality**: qlty unavailable in this sandbox → gate **not measured**. Substitutes run: gofmt, go vet (3 modules), bash -n, svelte-check (0/0), make test.17 - **Quality**: qlty unavailable in this sandbox → gate **not measured**. Substitutes run: gofmt, go vet (3 modules), bash -n, svelte-check (0/0), make test.
18 - **Docs**: `docs/README.md` selector; `docs/en` and `docs/fr`: tutorial (first ACP exchange), how-to (run tests, run a test agent), reference (configuration + schema package, agents.sh), explanation (why ACP, UI stack, architecture, memory and local models).18 - **Docs**: `docs/README.md` selector; `docs/en` and `docs/fr`: tutorial (first ACP exchange), how-to (run tests, run a test agent), reference (configuration + schema package, agents.sh), explanation (why ACP, UI stack, architecture, memory and local models).
19+
20+## 2026-10-29 — macOS test guide for milestone Initialize
21+
22+- **Goal**: a guide to test what Initialize produced when the owner is on a Mac.
23+- **Changes**: `docs/fr/how-to/tester-la-milestone-initialize-sous-macos.md`, `docs/en/how-to/test-milestone-initialize-on-macos.md`, both indexes; comment on #3. Fixed `spikes/wails-ui/README.md`: the `.app` comes from `wails3 package`, not `wails3 build`.
24+- **Tests**: guide commands cross-checked against the sandbox runs and the Wails v3 CLI (`wails3 package` exists, darwin Taskfile creates `bin/wails-ui.app`); not run on a Mac.
25+- **Docs**: how-to in EN and FR.
modified .tickets/issues/0003-spike-choisir-la-stack-wails-et-frontend.yaml +8 -1
@@ -6,7 +6,7 @@ author:
66 name: k33g
77 email: ph.charriere@gmail.com
88 createdAt: 2026-10-29T07:20:01.000Z
9-updatedAt: 2026-10-29T08:51:00.000Z
9+updatedAt: 2026-10-29T09:05:00.000Z
1010 labels:
1111 - "kind::spike"
1212 - "area::ui"
@@ -134,3 +134,10 @@ comments:
134134 - Prototype compilé et lancé sous Linux (GTK4/WebKitGTK 6, Xvfb) : layout, streaming à 50 et 500 chunks/s (rendu une fois par frame), coloration pendant le streaming, HTML injecté non exécuté, vrai shell dans le terminal. Captures : `docs/spikes/ui/`.
135135
136136 **Reste ouvert** : la sandbox n'a pas de SDK macOS. Le prototype doit être lancé sur le Mac (`cd spikes/wails-ui && wails3 dev`) — tâche ajoutée ci-dessous. L'issue reste ouverte jusque-là.
137+ - id: 2
138+ author:
139+ name: k33g
140+ email: ph.charriere@gmail.com
141+ createdAt: 2026-10-29T09:05:00.000Z
142+ body: |
143+ Guide pas à pas pour la vérification sur Mac : [docs/fr/how-to/tester-la-milestone-initialize-sous-macos.md](docs/fr/how-to/tester-la-milestone-initialize-sous-macos.md) (EN : [docs/en/how-to/test-milestone-initialize-on-macos.md](docs/en/how-to/test-milestone-initialize-on-macos.md)). Les parties 4 et 5 couvrent cette issue ; elles expliquent aussi comment la fermer, ainsi que la milestone Initialize.
@@ -6,7 +6,7 @@ author:
6 name: k33g6 name: k33g
7 email: ph.charriere@gmail.com7 email: ph.charriere@gmail.com
8 createdAt: 2026-10-29T07:20:01.000Z8 createdAt: 2026-10-29T07:20:01.000Z
9-updatedAt: 2026-10-29T08:51:00.000Z9+updatedAt: 2026-10-29T09:05:00.000Z
10 labels:10 labels:
11 - "kind::spike"11 - "kind::spike"
12 - "area::ui"12 - "area::ui"
@@ -134,3 +134,10 @@ comments:
134 - Prototype compilé et lancé sous Linux (GTK4/WebKitGTK 6, Xvfb) : layout, streaming à 50 et 500 chunks/s (rendu une fois par frame), coloration pendant le streaming, HTML injecté non exécuté, vrai shell dans le terminal. Captures : `docs/spikes/ui/`.134 - Prototype compilé et lancé sous Linux (GTK4/WebKitGTK 6, Xvfb) : layout, streaming à 50 et 500 chunks/s (rendu une fois par frame), coloration pendant le streaming, HTML injecté non exécuté, vrai shell dans le terminal. Captures : `docs/spikes/ui/`.
135 135
136 **Reste ouvert** : la sandbox n'a pas de SDK macOS. Le prototype doit être lancé sur le Mac (`cd spikes/wails-ui && wails3 dev`) — tâche ajoutée ci-dessous. L'issue reste ouverte jusque-là.136 **Reste ouvert** : la sandbox n'a pas de SDK macOS. Le prototype doit être lancé sur le Mac (`cd spikes/wails-ui && wails3 dev`) — tâche ajoutée ci-dessous. L'issue reste ouverte jusque-là.
137+ - id: 2
138+ author:
139+ name: k33g
140+ email: ph.charriere@gmail.com
141+ createdAt: 2026-10-29T09:05:00.000Z
142+ body: |
143+ Guide pas à pas pour la vérification sur Mac : [docs/fr/how-to/tester-la-milestone-initialize-sous-macos.md](docs/fr/how-to/tester-la-milestone-initialize-sous-macos.md) (EN : [docs/en/how-to/test-milestone-initialize-on-macos.md](docs/en/how-to/test-milestone-initialize-on-macos.md)). Les parties 4 et 5 couvrent cette issue ; elles expliquent aussi comment la fermer, ainsi que la milestone Initialize.
modified docs/en/README.md +1 -1
@@ -7,7 +7,7 @@ This documentation follows [Diátaxis](https://diataxis.fr): pick the section th
77 | You want to… | Section | Pages |
88 | --- | --- | --- |
99 | **learn** by doing | Tutorials | [Your first ACP exchange with a test agent](tutorials/first-acp-exchange.md) |
10-| **do** a specific task | How-to guides | [Run the tests](how-to/run-the-tests.md) · [Run a test agent](how-to/run-a-test-agent.md) |
10+| **do** a specific task | How-to guides | [Run the tests](how-to/run-the-tests.md) · [Run a test agent](how-to/run-a-test-agent.md) · [Test milestone Initialize on macOS](how-to/test-milestone-initialize-on-macos.md) |
1111 | **look up** an exact detail | Reference | [The configuration file](reference/configuration.md) · [scripts/agents.sh](reference/agents-script.md) |
1212 | **understand** why | Explanation | [Why ACP](explanation/why-acp.md) · [The interface stack](explanation/ui-stack.md) · [Architecture](explanation/architecture.md) · [Memory and local models](explanation/memory-and-local-models.md) |
1313
@@ -7,7 +7,7 @@ This documentation follows [Diátaxis](https://diataxis.fr): pick the section th
7 | You want to… | Section | Pages |7 | You want to… | Section | Pages |
8 | --- | --- | --- |8 | --- | --- | --- |
9 | **learn** by doing | Tutorials | [Your first ACP exchange with a test agent](tutorials/first-acp-exchange.md) |9 | **learn** by doing | Tutorials | [Your first ACP exchange with a test agent](tutorials/first-acp-exchange.md) |
10-| **do** a specific task | How-to guides | [Run the tests](how-to/run-the-tests.md) · [Run a test agent](how-to/run-a-test-agent.md) |10+| **do** a specific task | How-to guides | [Run the tests](how-to/run-the-tests.md) · [Run a test agent](how-to/run-a-test-agent.md) · [Test milestone Initialize on macOS](how-to/test-milestone-initialize-on-macos.md) |
11 | **look up** an exact detail | Reference | [The configuration file](reference/configuration.md) · [scripts/agents.sh](reference/agents-script.md) |11 | **look up** an exact detail | Reference | [The configuration file](reference/configuration.md) · [scripts/agents.sh](reference/agents-script.md) |
12 | **understand** why | Explanation | [Why ACP](explanation/why-acp.md) · [The interface stack](explanation/ui-stack.md) · [Architecture](explanation/architecture.md) · [Memory and local models](explanation/memory-and-local-models.md) |12 | **understand** why | Explanation | [Why ACP](explanation/why-acp.md) · [The interface stack](explanation/ui-stack.md) · [Architecture](explanation/architecture.md) · [Memory and local models](explanation/memory-and-local-models.md) |
13 13
added docs/en/how-to/test-milestone-initialize-on-macos.md +201 -0
new file mode 100644
@@ -0,0 +1,201 @@
1+# How to test milestone Initialize on macOS
2+
3+This guide checks on a Mac (Apple Silicon) everything milestone Initialize produced: the automated tests, the test-agent tooling, the ACP exchange with the real agents, the interface prototype and the wireframes. It assumes you are at ease in a terminal and that the repository is cloned, on branch `feature/initialize`. Allow 30 to 45 minutes, model downloads included.
4+
5+Each part ends with checkboxes; part 5 is the only one still open in the tickets (issue #3).
6+
7+## 0. Prepare the machine
8+
9+Install what is missing (check first with `go version`, `node --version`, `jq --version`):
10+
11+```bash
12+xcode-select --install # Xcode command line tools (compiler, codesign)
13+brew install go node jq # Go ≥ 1.26, Node ≥ 20
14+go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0
15+wails3 doctor # must end without errors
16+```
17+
18+If `wails3` is not found, add `$(go env GOPATH)/bin` to your `PATH`.
19+
20+Install `mm` v1.0.3 (the `mm-1.0.3-darwin-arm64` asset of the [release](https://rickub.com/bots-garden/mini-me/releases/v1.0.3)):
21+
22+```bash
23+cd ~/Downloads
24+shasum -a 256 mm-1.0.3-darwin-arm64
25+# expected: 601351f273ec35d8a3b98c44d805771777457c878336357bbaa38c84e58d5726
26+chmod +x mm-1.0.3-darwin-arm64
27+xattr -d com.apple.quarantine mm-1.0.3-darwin-arm64 # otherwise Gatekeeper blocks it
28+sudo mv mm-1.0.3-darwin-arm64 /usr/local/bin/mm
29+mm -version # v1.0.3
30+```
31+
32+Start llmman and pull the test agents' models:
33+
34+```bash
35+llmman pull hf.co/unsloth/gemma-4-E2B-it-GGUF:Q4_K_M # Alice
36+llmman pull hf.co/unsloth/Qwen3.5-2B-GGUF:Q4_K_M # Bob and Riker
37+llmman pull hf.co/unsloth/gemma-4-E4B-it-GGUF:Q4_K_M # Garfield
38+curl -s http://127.0.0.1:17434/api/ps # {"models":[]}: llmman answers, nothing loaded
39+```
40+
41+Open **Activity Monitor**, **Memory** tab, and keep an eye on "Memory Pressure" throughout the guide.
42+
43+## 1. The automated tests
44+
45+At the root of the repository:
46+
47+```bash
48+make test
49+```
50+
51+Expected: an `ok … sidekicks/schema` line, then `14 passed, 0 failed`. These tests use no agent, no model and no network.
52+
53+- [ ] `make test` passes on macOS.
54+
55+## 2. The test-agent tooling (#7)
56+
57+**The two-agents limit.** Open three terminal tabs at the root of the repository:
58+
59+```bash
60+# tab 1
61+scripts/agents.sh run alice
62+# tab 2
63+scripts/agents.sh run bob
64+# tab 3
65+scripts/agents.sh run riker
66+```
67+
68+Tabs 1 and 2 wait (the agent expects JSON-RPC on stdin; this is normal). Tab 3 must answer at once:
69+
70+```text
71+agents.sh: 2 agent(s) already running, the limit is 2:
72+ alice.<pid>
73+ bob.<pid>
74+```
75+
76+In tab 3, type `scripts/agents.sh ps`: Alice and Bob are listed. Stop Alice and Bob with Ctrl+C in their tabs, then run `scripts/agents.sh ps` again: both lists are empty.
77+
78+**Unloading.** These agents received no message, so no model was loaded: `ps` shows no model and `run` printed `not loaded: …`. This is expected — the script never loads a model in order to unload it.
79+
80+- [ ] The third agent is refused.
81+- [ ] After Ctrl+C, `ps` lists no agent.
82+
83+## 3. Talk ACP with the real agents (#2)
84+
85+Run the commands of this part from `spikes/acp-trace`:
86+
87+```bash
88+cd spikes/acp-trace
89+```
90+
91+**Alice — conversation and Markdown**:
92+
93+```bash
94+go run . -agent alice -out /tmp/alice.jsonl \
95+ -prompt "Bonjour, qui es-tu ? Réponds en une phrase." \
96+ -prompt "Écris un bloc de code Go qui affiche hello."
97+```
98+
99+Expected: `== protocol version: 1`, `[commands] 3 available`, two answers, `== stop reason: end_turn` twice, then `unloaded: hf.co/unsloth/gemma-4-E2B-it-GGUF:Q4_K_M`.
100+
101+**Riker — tools, permission granted**:
102+
103+```bash
104+go run . -agent riker -permission allow -out /tmp/riker-allow.jsonl \
105+ -prompt "Utilise l'outil bash pour exécuter la commande ls dans le dossier courant, puis dis-moi combien d'entrées il y a."
106+```
107+
108+Expected: a line `== permission requested for "call_1", options: [allow_once allow] [allow_always allow_always] [reject_once reject] [reject_always never]`, then the output of `ls` (`agent.yaml`) and an answer such as "Il y a 1 entrée" — the wording varies, the model chooses its words.
109+
110+**Riker — permission refused** (takes 1 to 3 minutes):
111+
112+```bash
113+go run . -agent riker -permission reject -out /tmp/riker-reject.jsonl \
114+ -prompt "Utilise l'outil write_file pour créer le fichier notes.txt contenant le mot hello."
115+```
116+
117+Expected: Riker retries in a loop, then `exceeded maximum tool call iterations (40)` and `exit status 1`. This is the behaviour observed in the sandbox and documented in ADR 0001, not a problem with this guide. Check that no file was created: `ls ../../agents/riker` shows only `agent.yaml`.
118+
119+**Garfield — a skill through a slash command**:
120+
121+```bash
122+go run . -agent garfield -out /tmp/garfield.jsonl -prompt "/idioms Il pleut des cordes."
123+```
124+
125+Expected: `[commands] 7 available`, a line `[tool read] read_skill: idioms`, then a translation such as "It's raining cats and dogs.".
126+
127+**Garfield — cancellation**:
128+
129+```bash
130+go run . -agent garfield -cancel-after 4s -out /tmp/garfield-cancel.jsonl \
131+ -prompt "Traduis en anglais, en trois paragraphes détaillés : Sidekicks est une application de bureau pour converser avec des agents d'IA."
132+```
133+
134+Expected: `== sending session/cancel` then `== stop reason: cancelled`.
135+
136+After each command, `../../scripts/agents.sh ps` must list no agent and no model.
137+
138+- [ ] Alice answers, with a Go code block.
139+- [ ] Riker asks for permission; granted, it runs `ls`; refused, it loops then stops with an error without creating a file.
140+- [ ] `/idioms` runs Garfield's skill.
141+- [ ] Cancellation gives `stop reason: cancelled`.
142+- [ ] No model stays loaded at the end; memory pressure stayed green.
143+
144+## 4. The interface prototype, in development mode (#3)
145+
146+```bash
147+cd ../wails-ui
148+cd frontend && npm install && cd ..
149+wails3 dev
150+```
151+
152+The first run compiles Go and the frontend (one to two minutes). A "Sidekicks — UI spike" window opens. Check:
153+
154+1. **Panels**: drag both vertical separators and the horizontal one. Quit (⌘Q), run `wails3 dev` again: the layout is restored.
155+2. **Streaming**: click **Simuler (50 chunks/s)**. The answer appears progressively, the Go block is coloured **while** it is written, the table is rendered, and the quote shows `<img src=x onerror="alert(1)">` as text (no alert). The counter shows about `219 chunks · 4500 ms`.
156+3. **Throughput**: click **Simuler (500 chunks/s)**. The interface stays fluid; the counter shows under one second.
157+4. **Terminal**: click in the black panel, type `ls`, then `top`; enlarge the bottom panel while `top` runs: the display follows. Leave `top` with `q`.
158+5. **YAML editor**: the right panel colours the YAML; typing works.
159+6. **Theme**: System Settings → Appearance → switch Light / Dark: the conversation, the code and the dock follow (the YAML editor keeps the theme it started with — a known limit of the prototype).
160+7. **macOS window**: the title bar is integrated (red/orange/green buttons over the application's background).
161+
162+- [ ] Points 1 to 7 are as described.
163+
164+## 5. The prototype packaged as an application (#3)
165+
166+```bash
167+wails3 package
168+open bin/wails-ui.app
169+```
170+
171+`wails3 package` produces `bin/wails-ui.app`, signed ad hoc. Quickly repeat points 2 and 4 of the previous part in the application opened from the Finder.
172+
173+- [ ] `bin/wails-ui.app` opens and works as in development mode.
174+
175+If both parts are as described, ADR 0002 is confirmed: close the last task of issue #3 ("Lancer le prototype sur macOS"), set the issue to `closed`, then set milestone **Initialize** to `closed` in `.tickets/milestones.yaml`. Otherwise, describe what differs in a comment on issue #3 (a screenshot helps).
176+
177+## 6. The wireframes (#6)
178+
179+Open `docs/design/wireframes.drawio` with the VS Code **Draw.io Integration** extension (recommended by the repository) or on [app.diagrams.net](https://app.diagrams.net). Its six pages are the six screens; the PNG files of the same folder are their rendering.
180+
181+The acceptance criterion of issue #6 to validate: the path "I create a channel, invite Alice, ask her a question" reads from screen to screen (screens 6, 1, 3 and 2).
182+
183+- [ ] The file opens with its 6 pages.
184+- [ ] The path is understandable; otherwise, comment on issue #6.
185+
186+## Troubleshooting
187+
188+| Symptom | Likely cause | Fix |
189+| --- | --- | --- |
190+| `"mm" cannot be opened` | Gatekeeper quarantine | `xattr -d com.apple.quarantine /usr/local/bin/mm` |
191+| `agents.sh: llmman does not answer…` | llmman stopped or on another port | start llmman, or `export LLMMAN_URL=http://127.0.0.1:<port>` |
192+| `agents.sh: could not lock …` | an `agents.sh` was killed abruptly | `rm -rf .run/agents/.lock` |
193+| `wails3: command not found` | `GOPATH/bin` not on `PATH` | `export PATH="$(go env GOPATH)/bin:$PATH"` |
194+| `wails3 dev` waits 60 s then fails | npm dependencies missing | `cd frontend && npm install` |
195+| Memory pressure turns red | a model stayed loaded | `scripts/agents.sh unload --all` |
196+
197+## See also
198+
199+- [How to run a test agent](run-a-test-agent.md) · [How to run the tests](run-the-tests.md)
200+- [Reference: scripts/agents.sh](../reference/agents-script.md)
201+- Why these choices: [Why ACP](../explanation/why-acp.md) · [The interface stack](../explanation/ui-stack.md)
new file mode 100644
@@ -0,0 +1,201 @@
1+# How to test milestone Initialize on macOS
2+
3+This guide checks on a Mac (Apple Silicon) everything milestone Initialize produced: the automated tests, the test-agent tooling, the ACP exchange with the real agents, the interface prototype and the wireframes. It assumes you are at ease in a terminal and that the repository is cloned, on branch `feature/initialize`. Allow 30 to 45 minutes, model downloads included.
4+
5+Each part ends with checkboxes; part 5 is the only one still open in the tickets (issue #3).
6+
7+## 0. Prepare the machine
8+
9+Install what is missing (check first with `go version`, `node --version`, `jq --version`):
10+
11+```bash
12+xcode-select --install # Xcode command line tools (compiler, codesign)
13+brew install go node jq # Go ≥ 1.26, Node ≥ 20
14+go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0
15+wails3 doctor # must end without errors
16+```
17+
18+If `wails3` is not found, add `$(go env GOPATH)/bin` to your `PATH`.
19+
20+Install `mm` v1.0.3 (the `mm-1.0.3-darwin-arm64` asset of the [release](https://rickub.com/bots-garden/mini-me/releases/v1.0.3)):
21+
22+```bash
23+cd ~/Downloads
24+shasum -a 256 mm-1.0.3-darwin-arm64
25+# expected: 601351f273ec35d8a3b98c44d805771777457c878336357bbaa38c84e58d5726
26+chmod +x mm-1.0.3-darwin-arm64
27+xattr -d com.apple.quarantine mm-1.0.3-darwin-arm64 # otherwise Gatekeeper blocks it
28+sudo mv mm-1.0.3-darwin-arm64 /usr/local/bin/mm
29+mm -version # v1.0.3
30+```
31+
32+Start llmman and pull the test agents' models:
33+
34+```bash
35+llmman pull hf.co/unsloth/gemma-4-E2B-it-GGUF:Q4_K_M # Alice
36+llmman pull hf.co/unsloth/Qwen3.5-2B-GGUF:Q4_K_M # Bob and Riker
37+llmman pull hf.co/unsloth/gemma-4-E4B-it-GGUF:Q4_K_M # Garfield
38+curl -s http://127.0.0.1:17434/api/ps # {"models":[]}: llmman answers, nothing loaded
39+```
40+
41+Open **Activity Monitor**, **Memory** tab, and keep an eye on "Memory Pressure" throughout the guide.
42+
43+## 1. The automated tests
44+
45+At the root of the repository:
46+
47+```bash
48+make test
49+```
50+
51+Expected: an `ok … sidekicks/schema` line, then `14 passed, 0 failed`. These tests use no agent, no model and no network.
52+
53+- [ ] `make test` passes on macOS.
54+
55+## 2. The test-agent tooling (#7)
56+
57+**The two-agents limit.** Open three terminal tabs at the root of the repository:
58+
59+```bash
60+# tab 1
61+scripts/agents.sh run alice
62+# tab 2
63+scripts/agents.sh run bob
64+# tab 3
65+scripts/agents.sh run riker
66+```
67+
68+Tabs 1 and 2 wait (the agent expects JSON-RPC on stdin; this is normal). Tab 3 must answer at once:
69+
70+```text
71+agents.sh: 2 agent(s) already running, the limit is 2:
72+ alice.<pid>
73+ bob.<pid>
74+```
75+
76+In tab 3, type `scripts/agents.sh ps`: Alice and Bob are listed. Stop Alice and Bob with Ctrl+C in their tabs, then run `scripts/agents.sh ps` again: both lists are empty.
77+
78+**Unloading.** These agents received no message, so no model was loaded: `ps` shows no model and `run` printed `not loaded: …`. This is expected — the script never loads a model in order to unload it.
79+
80+- [ ] The third agent is refused.
81+- [ ] After Ctrl+C, `ps` lists no agent.
82+
83+## 3. Talk ACP with the real agents (#2)
84+
85+Run the commands of this part from `spikes/acp-trace`:
86+
87+```bash
88+cd spikes/acp-trace
89+```
90+
91+**Alice — conversation and Markdown**:
92+
93+```bash
94+go run . -agent alice -out /tmp/alice.jsonl \
95+ -prompt "Bonjour, qui es-tu ? Réponds en une phrase." \
96+ -prompt "Écris un bloc de code Go qui affiche hello."
97+```
98+
99+Expected: `== protocol version: 1`, `[commands] 3 available`, two answers, `== stop reason: end_turn` twice, then `unloaded: hf.co/unsloth/gemma-4-E2B-it-GGUF:Q4_K_M`.
100+
101+**Riker — tools, permission granted**:
102+
103+```bash
104+go run . -agent riker -permission allow -out /tmp/riker-allow.jsonl \
105+ -prompt "Utilise l'outil bash pour exécuter la commande ls dans le dossier courant, puis dis-moi combien d'entrées il y a."
106+```
107+
108+Expected: a line `== permission requested for "call_1", options: [allow_once allow] [allow_always allow_always] [reject_once reject] [reject_always never]`, then the output of `ls` (`agent.yaml`) and an answer such as "Il y a 1 entrée" — the wording varies, the model chooses its words.
109+
110+**Riker — permission refused** (takes 1 to 3 minutes):
111+
112+```bash
113+go run . -agent riker -permission reject -out /tmp/riker-reject.jsonl \
114+ -prompt "Utilise l'outil write_file pour créer le fichier notes.txt contenant le mot hello."
115+```
116+
117+Expected: Riker retries in a loop, then `exceeded maximum tool call iterations (40)` and `exit status 1`. This is the behaviour observed in the sandbox and documented in ADR 0001, not a problem with this guide. Check that no file was created: `ls ../../agents/riker` shows only `agent.yaml`.
118+
119+**Garfield — a skill through a slash command**:
120+
121+```bash
122+go run . -agent garfield -out /tmp/garfield.jsonl -prompt "/idioms Il pleut des cordes."
123+```
124+
125+Expected: `[commands] 7 available`, a line `[tool read] read_skill: idioms`, then a translation such as "It's raining cats and dogs.".
126+
127+**Garfield — cancellation**:
128+
129+```bash
130+go run . -agent garfield -cancel-after 4s -out /tmp/garfield-cancel.jsonl \
131+ -prompt "Traduis en anglais, en trois paragraphes détaillés : Sidekicks est une application de bureau pour converser avec des agents d'IA."
132+```
133+
134+Expected: `== sending session/cancel` then `== stop reason: cancelled`.
135+
136+After each command, `../../scripts/agents.sh ps` must list no agent and no model.
137+
138+- [ ] Alice answers, with a Go code block.
139+- [ ] Riker asks for permission; granted, it runs `ls`; refused, it loops then stops with an error without creating a file.
140+- [ ] `/idioms` runs Garfield's skill.
141+- [ ] Cancellation gives `stop reason: cancelled`.
142+- [ ] No model stays loaded at the end; memory pressure stayed green.
143+
144+## 4. The interface prototype, in development mode (#3)
145+
146+```bash
147+cd ../wails-ui
148+cd frontend && npm install && cd ..
149+wails3 dev
150+```
151+
152+The first run compiles Go and the frontend (one to two minutes). A "Sidekicks — UI spike" window opens. Check:
153+
154+1. **Panels**: drag both vertical separators and the horizontal one. Quit (⌘Q), run `wails3 dev` again: the layout is restored.
155+2. **Streaming**: click **Simuler (50 chunks/s)**. The answer appears progressively, the Go block is coloured **while** it is written, the table is rendered, and the quote shows `<img src=x onerror="alert(1)">` as text (no alert). The counter shows about `219 chunks · 4500 ms`.
156+3. **Throughput**: click **Simuler (500 chunks/s)**. The interface stays fluid; the counter shows under one second.
157+4. **Terminal**: click in the black panel, type `ls`, then `top`; enlarge the bottom panel while `top` runs: the display follows. Leave `top` with `q`.
158+5. **YAML editor**: the right panel colours the YAML; typing works.
159+6. **Theme**: System Settings → Appearance → switch Light / Dark: the conversation, the code and the dock follow (the YAML editor keeps the theme it started with — a known limit of the prototype).
160+7. **macOS window**: the title bar is integrated (red/orange/green buttons over the application's background).
161+
162+- [ ] Points 1 to 7 are as described.
163+
164+## 5. The prototype packaged as an application (#3)
165+
166+```bash
167+wails3 package
168+open bin/wails-ui.app
169+```
170+
171+`wails3 package` produces `bin/wails-ui.app`, signed ad hoc. Quickly repeat points 2 and 4 of the previous part in the application opened from the Finder.
172+
173+- [ ] `bin/wails-ui.app` opens and works as in development mode.
174+
175+If both parts are as described, ADR 0002 is confirmed: close the last task of issue #3 ("Lancer le prototype sur macOS"), set the issue to `closed`, then set milestone **Initialize** to `closed` in `.tickets/milestones.yaml`. Otherwise, describe what differs in a comment on issue #3 (a screenshot helps).
176+
177+## 6. The wireframes (#6)
178+
179+Open `docs/design/wireframes.drawio` with the VS Code **Draw.io Integration** extension (recommended by the repository) or on [app.diagrams.net](https://app.diagrams.net). Its six pages are the six screens; the PNG files of the same folder are their rendering.
180+
181+The acceptance criterion of issue #6 to validate: the path "I create a channel, invite Alice, ask her a question" reads from screen to screen (screens 6, 1, 3 and 2).
182+
183+- [ ] The file opens with its 6 pages.
184+- [ ] The path is understandable; otherwise, comment on issue #6.
185+
186+## Troubleshooting
187+
188+| Symptom | Likely cause | Fix |
189+| --- | --- | --- |
190+| `"mm" cannot be opened` | Gatekeeper quarantine | `xattr -d com.apple.quarantine /usr/local/bin/mm` |
191+| `agents.sh: llmman does not answer…` | llmman stopped or on another port | start llmman, or `export LLMMAN_URL=http://127.0.0.1:<port>` |
192+| `agents.sh: could not lock …` | an `agents.sh` was killed abruptly | `rm -rf .run/agents/.lock` |
193+| `wails3: command not found` | `GOPATH/bin` not on `PATH` | `export PATH="$(go env GOPATH)/bin:$PATH"` |
194+| `wails3 dev` waits 60 s then fails | npm dependencies missing | `cd frontend && npm install` |
195+| Memory pressure turns red | a model stayed loaded | `scripts/agents.sh unload --all` |
196+
197+## See also
198+
199+- [How to run a test agent](run-a-test-agent.md) · [How to run the tests](run-the-tests.md)
200+- [Reference: scripts/agents.sh](../reference/agents-script.md)
201+- Why these choices: [Why ACP](../explanation/why-acp.md) · [The interface stack](../explanation/ui-stack.md)
modified docs/fr/README.md +1 -1
@@ -7,7 +7,7 @@ Cette documentation suit la méthode [Diátaxis](https://diataxis.fr) : choisiss
77 | Vous voulez… | Section | Pages |
88 | --- | --- | --- |
99 | **apprendre** en pratiquant | Tutoriels | [Votre premier échange ACP avec un agent de test](tutorials/premier-echange-acp.md) |
10-| **réaliser** une tâche précise | Guides pratiques | [Lancer les tests](how-to/lancer-les-tests.md) · [Lancer un agent de test](how-to/lancer-un-agent-de-test.md) |
10+| **réaliser** une tâche précise | Guides pratiques | [Lancer les tests](how-to/lancer-les-tests.md) · [Lancer un agent de test](how-to/lancer-un-agent-de-test.md) · [Tester la milestone Initialize sous macOS](how-to/tester-la-milestone-initialize-sous-macos.md) |
1111 | **consulter** un détail exact | Référence | [Le fichier de configuration](reference/configuration.md) · [scripts/agents.sh](reference/script-agents.md) |
1212 | **comprendre** le pourquoi | Explications | [Pourquoi ACP](explanation/pourquoi-acp.md) · [La stack de l'interface](explanation/stack-interface.md) · [Architecture](explanation/architecture.md) · [Mémoire et modèles locaux](explanation/memoire-et-modeles-locaux.md) |
1313
@@ -7,7 +7,7 @@ Cette documentation suit la méthode [Diátaxis](https://diataxis.fr) : choisiss
7 | Vous voulez… | Section | Pages |7 | Vous voulez… | Section | Pages |
8 | --- | --- | --- |8 | --- | --- | --- |
9 | **apprendre** en pratiquant | Tutoriels | [Votre premier échange ACP avec un agent de test](tutorials/premier-echange-acp.md) |9 | **apprendre** en pratiquant | Tutoriels | [Votre premier échange ACP avec un agent de test](tutorials/premier-echange-acp.md) |
10-| **réaliser** une tâche précise | Guides pratiques | [Lancer les tests](how-to/lancer-les-tests.md) · [Lancer un agent de test](how-to/lancer-un-agent-de-test.md) |10+| **réaliser** une tâche précise | Guides pratiques | [Lancer les tests](how-to/lancer-les-tests.md) · [Lancer un agent de test](how-to/lancer-un-agent-de-test.md) · [Tester la milestone Initialize sous macOS](how-to/tester-la-milestone-initialize-sous-macos.md) |
11 | **consulter** un détail exact | Référence | [Le fichier de configuration](reference/configuration.md) · [scripts/agents.sh](reference/script-agents.md) |11 | **consulter** un détail exact | Référence | [Le fichier de configuration](reference/configuration.md) · [scripts/agents.sh](reference/script-agents.md) |
12 | **comprendre** le pourquoi | Explications | [Pourquoi ACP](explanation/pourquoi-acp.md) · [La stack de l'interface](explanation/stack-interface.md) · [Architecture](explanation/architecture.md) · [Mémoire et modèles locaux](explanation/memoire-et-modeles-locaux.md) |12 | **comprendre** le pourquoi | Explications | [Pourquoi ACP](explanation/pourquoi-acp.md) · [La stack de l'interface](explanation/stack-interface.md) · [Architecture](explanation/architecture.md) · [Mémoire et modèles locaux](explanation/memoire-et-modeles-locaux.md) |
13 13
added docs/fr/how-to/tester-la-milestone-initialize-sous-macos.md +201 -0
new file mode 100644
@@ -0,0 +1,201 @@
1+# Comment tester la milestone Initialize sous macOS
2+
3+Ce guide permet de vérifier sur un Mac (Apple Silicon) tout ce que la milestone Initialize a produit : les tests automatiques, l'outillage des agents de test, le dialogue ACP avec les vrais agents, le prototype d'interface et les maquettes. Il suppose que vous savez utiliser un terminal et que le dépôt est cloné, sur la branche `feature/initialize`. Comptez 30 à 45 minutes, téléchargements de modèles compris.
4+
5+Chaque partie se termine par une case à cocher ; la partie 5 est la seule qui reste ouverte dans les tickets (issue #3).
6+
7+## 0. Préparer la machine
8+
9+Installez les outils manquants (vérifiez d'abord avec `go version`, `node --version`, `jq --version`) :
10+
11+```bash
12+xcode-select --install # outils en ligne de commande Xcode (compilateur, codesign)
13+brew install go node jq # Go ≥ 1.26, Node ≥ 20
14+go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0
15+wails3 doctor # doit finir sans erreur
16+```
17+
18+Si `wails3` est introuvable, ajoutez `$(go env GOPATH)/bin` à votre `PATH`.
19+
20+Installez `mm` v1.0.3 (binaire `mm-1.0.3-darwin-arm64` de la [release](https://rickub.com/bots-garden/mini-me/releases/v1.0.3)) :
21+
22+```bash
23+cd ~/Downloads
24+shasum -a 256 mm-1.0.3-darwin-arm64
25+# attendu : 601351f273ec35d8a3b98c44d805771777457c878336357bbaa38c84e58d5726
26+chmod +x mm-1.0.3-darwin-arm64
27+xattr -d com.apple.quarantine mm-1.0.3-darwin-arm64 # sinon Gatekeeper bloque le binaire
28+sudo mv mm-1.0.3-darwin-arm64 /usr/local/bin/mm
29+mm -version # v1.0.3
30+```
31+
32+Lancez llmman et téléchargez les modèles des agents de test :
33+
34+```bash
35+llmman pull hf.co/unsloth/gemma-4-E2B-it-GGUF:Q4_K_M # Alice
36+llmman pull hf.co/unsloth/Qwen3.5-2B-GGUF:Q4_K_M # Bob et Riker
37+llmman pull hf.co/unsloth/gemma-4-E4B-it-GGUF:Q4_K_M # Garfield
38+curl -s http://127.0.0.1:17434/api/ps # {"models":[]} : llmman répond, rien n'est chargé
39+```
40+
41+Ouvrez le **Moniteur d'activité**, onglet **Mémoire** : gardez un œil sur la « pression mémoire » pendant tout le guide.
42+
43+## 1. Les tests automatiques
44+
45+À la racine du dépôt :
46+
47+```bash
48+make test
49+```
50+
51+Attendu : une ligne `ok … sidekicks/schema` puis `14 passed, 0 failed`. Ces tests n'utilisent ni agent, ni modèle, ni réseau.
52+
53+- [ ] `make test` passe sous macOS.
54+
55+## 2. L'outillage des agents (#7)
56+
57+**La limite de deux agents.** Ouvrez trois onglets de terminal à la racine du dépôt :
58+
59+```bash
60+# onglet 1
61+scripts/agents.sh run alice
62+# onglet 2
63+scripts/agents.sh run bob
64+# onglet 3
65+scripts/agents.sh run riker
66+```
67+
68+Les onglets 1 et 2 restent en attente (l'agent attend du JSON-RPC sur stdin, c'est normal). L'onglet 3 doit répondre aussitôt :
69+
70+```text
71+agents.sh: 2 agent(s) already running, the limit is 2:
72+ alice.<pid>
73+ bob.<pid>
74+```
75+
76+Dans l'onglet 3, tapez `scripts/agents.sh ps` : Alice et Bob sont listés. Arrêtez Alice et Bob avec Ctrl+C dans leurs onglets, puis relancez `scripts/agents.sh ps` : les deux listes sont vides.
77+
78+**Le déchargement.** Ces agents n'ayant reçu aucun message, aucun modèle n'a été chargé : `ps` n'affiche aucun modèle et la sortie de `run` disait `not loaded: …`. C'est le comportement attendu — le script ne charge jamais un modèle pour le décharger.
79+
80+- [ ] Le 3ᵉ agent est refusé.
81+- [ ] Après Ctrl+C, `ps` ne liste plus aucun agent.
82+
83+## 3. Dialoguer en ACP avec les vrais agents (#2)
84+
85+Les commandes de cette partie se lancent depuis `spikes/acp-trace` :
86+
87+```bash
88+cd spikes/acp-trace
89+```
90+
91+**Alice — conversation et Markdown** :
92+
93+```bash
94+go run . -agent alice -out /tmp/alice.jsonl \
95+ -prompt "Bonjour, qui es-tu ? Réponds en une phrase." \
96+ -prompt "Écris un bloc de code Go qui affiche hello."
97+```
98+
99+Attendu : `== protocol version: 1`, `[commands] 3 available`, deux réponses, deux fois `== stop reason: end_turn`, puis `unloaded: hf.co/unsloth/gemma-4-E2B-it-GGUF:Q4_K_M`.
100+
101+**Riker — outils et permission acceptée** :
102+
103+```bash
104+go run . -agent riker -permission allow -out /tmp/riker-allow.jsonl \
105+ -prompt "Utilise l'outil bash pour exécuter la commande ls dans le dossier courant, puis dis-moi combien d'entrées il y a."
106+```
107+
108+Attendu : une ligne `== permission requested for "call_1", options: [allow_once allow] [allow_always allow_always] [reject_once reject] [reject_always never]`, puis la sortie de `ls` (`agent.yaml`) et une réponse du type « Il y a 1 entrée » — la formulation varie, c'est le modèle qui choisit ses mots.
109+
110+**Riker — permission refusée** (dure 1 à 3 minutes) :
111+
112+```bash
113+go run . -agent riker -permission reject -out /tmp/riker-reject.jsonl \
114+ -prompt "Utilise l'outil write_file pour créer le fichier notes.txt contenant le mot hello."
115+```
116+
117+Attendu : Riker réessaie en boucle, puis `exceeded maximum tool call iterations (40)` et `exit status 1`. C'est le comportement observé dans la sandbox et documenté dans l'ADR 0001 ; ce n'est pas un bug du guide. Vérifiez qu'aucun fichier n'a été créé : `ls ../../agents/riker` n'affiche que `agent.yaml`.
118+
119+**Garfield — skill via une commande slash** :
120+
121+```bash
122+go run . -agent garfield -out /tmp/garfield.jsonl -prompt "/idioms Il pleut des cordes."
123+```
124+
125+Attendu : `[commands] 7 available`, une ligne `[tool read] read_skill: idioms`, puis une traduction du type « It's raining cats and dogs. ».
126+
127+**Garfield — annulation** :
128+
129+```bash
130+go run . -agent garfield -cancel-after 4s -out /tmp/garfield-cancel.jsonl \
131+ -prompt "Traduis en anglais, en trois paragraphes détaillés : Sidekicks est une application de bureau pour converser avec des agents d'IA."
132+```
133+
134+Attendu : `== sending session/cancel` puis `== stop reason: cancelled`.
135+
136+Après chaque commande, `../../scripts/agents.sh ps` ne doit lister ni agent ni modèle.
137+
138+- [ ] Alice répond, avec un bloc de code Go.
139+- [ ] Riker demande la permission ; accepté il exécute `ls`, refusé il boucle puis s'arrête en erreur sans créer de fichier.
140+- [ ] `/idioms` lance le skill de Garfield.
141+- [ ] L'annulation donne `stop reason: cancelled`.
142+- [ ] Aucun modèle ne reste chargé à la fin ; la pression mémoire est restée verte.
143+
144+## 4. Le prototype d'interface, en développement (#3)
145+
146+```bash
147+cd ../wails-ui
148+cd frontend && npm install && cd ..
149+wails3 dev
150+```
151+
152+Le premier lancement compile le Go et le frontend (une à deux minutes). Une fenêtre « Sidekicks — UI spike » s'ouvre. Vérifiez :
153+
154+1. **Panels** : glissez les deux séparateurs verticaux et le séparateur horizontal. Quittez (⌘Q), relancez `wails3 dev` : la disposition est restaurée.
155+2. **Streaming** : cliquez sur **Simuler (50 chunks/s)**. La réponse s'affiche au fil de l'eau, le bloc Go est coloré **pendant** l'écriture, le tableau est rendu, la citation affiche `<img src=x onerror="alert(1)">` comme du texte (aucune alerte). Le compteur affiche environ `219 chunks · 4500 ms`.
156+3. **Débit** : cliquez sur **Simuler (500 chunks/s)**. L'interface reste fluide ; le compteur affiche moins d'une seconde.
157+4. **Terminal** : cliquez dans le panel noir, tapez `ls`, puis `top` ; agrandissez le panel du bas pendant que `top` tourne : l'affichage suit. Quittez `top` avec `q`.
158+5. **Éditeur YAML** : le panel de droite colore le YAML ; tapez du texte, l'édition fonctionne.
159+6. **Thème** : Réglages Système → Apparence → basculez Clair / Sombre : la conversation, le code et le dock suivent (l'éditeur YAML garde le thème du lancement — limite connue du prototype).
160+7. **Fenêtre macOS** : la barre de titre est intégrée (boutons rouge/orange/vert sur le fond de l'application).
161+
162+- [ ] Les points 1 à 7 sont conformes.
163+
164+## 5. Le prototype empaqueté en application (#3)
165+
166+```bash
167+wails3 package
168+open bin/wails-ui.app
169+```
170+
171+`wails3 package` produit `bin/wails-ui.app`, signé ad hoc. Refaites rapidement les points 2 et 4 de la partie précédente dans l'application ouverte depuis le Finder.
172+
173+- [ ] `bin/wails-ui.app` s'ouvre et fonctionne comme en développement.
174+
175+Si ces deux parties sont conformes, l'ADR 0002 est confirmé : fermez la dernière tâche de l'issue #3 (« Lancer le prototype sur macOS »), passez l'issue à `closed`, puis la milestone **Initialize** à `closed` dans `.tickets/milestones.yaml`. Sinon, notez dans un commentaire de l'issue #3 ce qui diffère (capture d'écran bienvenue).
176+
177+## 6. Les maquettes (#6)
178+
179+Ouvrez `docs/design/wireframes.drawio` avec l'extension VS Code **Draw.io Integration** (recommandée par le dépôt) ou sur [app.diagrams.net](https://app.diagrams.net). Les six pages correspondent aux six écrans ; les PNG du même dossier en sont le rendu.
180+
181+Critère d'acceptation de l'issue #6 à valider : le parcours « je crée un channel, j'invite Alice, je lui pose une question » se lit d'écran en écran (écrans 6, 1, 3 et 2).
182+
183+- [ ] Le fichier s'ouvre avec ses 6 pages.
184+- [ ] Le parcours est compréhensible ; sinon, commentez l'issue #6.
185+
186+## En cas de problème
187+
188+| Symptôme | Cause probable | Remède |
189+| --- | --- | --- |
190+| `"mm" ne peut pas être ouvert` | quarantaine Gatekeeper | `xattr -d com.apple.quarantine /usr/local/bin/mm` |
191+| `agents.sh: llmman does not answer…` | llmman arrêté ou sur un autre port | lancez llmman, ou `export LLMMAN_URL=http://127.0.0.1:<port>` |
192+| `agents.sh: could not lock …` | un `agents.sh` tué brutalement | `rm -rf .run/agents/.lock` |
193+| `wails3: command not found` | `GOPATH/bin` absent du `PATH` | `export PATH="$(go env GOPATH)/bin:$PATH"` |
194+| `wails3 dev` attend 60 s puis échoue | dépendances npm absentes | `cd frontend && npm install` |
195+| La pression mémoire passe au rouge | un modèle est resté chargé | `scripts/agents.sh unload --all` |
196+
197+## Voir aussi
198+
199+- [Comment lancer un agent de test](lancer-un-agent-de-test.md) · [Comment lancer les tests](lancer-les-tests.md)
200+- [Référence : scripts/agents.sh](../reference/script-agents.md)
201+- Pourquoi ces choix : [Pourquoi ACP](../explanation/pourquoi-acp.md) · [La stack de l'interface](../explanation/stack-interface.md)
new file mode 100644
@@ -0,0 +1,201 @@
1+# Comment tester la milestone Initialize sous macOS
2+
3+Ce guide permet de vérifier sur un Mac (Apple Silicon) tout ce que la milestone Initialize a produit : les tests automatiques, l'outillage des agents de test, le dialogue ACP avec les vrais agents, le prototype d'interface et les maquettes. Il suppose que vous savez utiliser un terminal et que le dépôt est cloné, sur la branche `feature/initialize`. Comptez 30 à 45 minutes, téléchargements de modèles compris.
4+
5+Chaque partie se termine par une case à cocher ; la partie 5 est la seule qui reste ouverte dans les tickets (issue #3).
6+
7+## 0. Préparer la machine
8+
9+Installez les outils manquants (vérifiez d'abord avec `go version`, `node --version`, `jq --version`) :
10+
11+```bash
12+xcode-select --install # outils en ligne de commande Xcode (compilateur, codesign)
13+brew install go node jq # Go ≥ 1.26, Node ≥ 20
14+go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0
15+wails3 doctor # doit finir sans erreur
16+```
17+
18+Si `wails3` est introuvable, ajoutez `$(go env GOPATH)/bin` à votre `PATH`.
19+
20+Installez `mm` v1.0.3 (binaire `mm-1.0.3-darwin-arm64` de la [release](https://rickub.com/bots-garden/mini-me/releases/v1.0.3)) :
21+
22+```bash
23+cd ~/Downloads
24+shasum -a 256 mm-1.0.3-darwin-arm64
25+# attendu : 601351f273ec35d8a3b98c44d805771777457c878336357bbaa38c84e58d5726
26+chmod +x mm-1.0.3-darwin-arm64
27+xattr -d com.apple.quarantine mm-1.0.3-darwin-arm64 # sinon Gatekeeper bloque le binaire
28+sudo mv mm-1.0.3-darwin-arm64 /usr/local/bin/mm
29+mm -version # v1.0.3
30+```
31+
32+Lancez llmman et téléchargez les modèles des agents de test :
33+
34+```bash
35+llmman pull hf.co/unsloth/gemma-4-E2B-it-GGUF:Q4_K_M # Alice
36+llmman pull hf.co/unsloth/Qwen3.5-2B-GGUF:Q4_K_M # Bob et Riker
37+llmman pull hf.co/unsloth/gemma-4-E4B-it-GGUF:Q4_K_M # Garfield
38+curl -s http://127.0.0.1:17434/api/ps # {"models":[]} : llmman répond, rien n'est chargé
39+```
40+
41+Ouvrez le **Moniteur d'activité**, onglet **Mémoire** : gardez un œil sur la « pression mémoire » pendant tout le guide.
42+
43+## 1. Les tests automatiques
44+
45+À la racine du dépôt :
46+
47+```bash
48+make test
49+```
50+
51+Attendu : une ligne `ok … sidekicks/schema` puis `14 passed, 0 failed`. Ces tests n'utilisent ni agent, ni modèle, ni réseau.
52+
53+- [ ] `make test` passe sous macOS.
54+
55+## 2. L'outillage des agents (#7)
56+
57+**La limite de deux agents.** Ouvrez trois onglets de terminal à la racine du dépôt :
58+
59+```bash
60+# onglet 1
61+scripts/agents.sh run alice
62+# onglet 2
63+scripts/agents.sh run bob
64+# onglet 3
65+scripts/agents.sh run riker
66+```
67+
68+Les onglets 1 et 2 restent en attente (l'agent attend du JSON-RPC sur stdin, c'est normal). L'onglet 3 doit répondre aussitôt :
69+
70+```text
71+agents.sh: 2 agent(s) already running, the limit is 2:
72+ alice.<pid>
73+ bob.<pid>
74+```
75+
76+Dans l'onglet 3, tapez `scripts/agents.sh ps` : Alice et Bob sont listés. Arrêtez Alice et Bob avec Ctrl+C dans leurs onglets, puis relancez `scripts/agents.sh ps` : les deux listes sont vides.
77+
78+**Le déchargement.** Ces agents n'ayant reçu aucun message, aucun modèle n'a été chargé : `ps` n'affiche aucun modèle et la sortie de `run` disait `not loaded: …`. C'est le comportement attendu — le script ne charge jamais un modèle pour le décharger.
79+
80+- [ ] Le 3ᵉ agent est refusé.
81+- [ ] Après Ctrl+C, `ps` ne liste plus aucun agent.
82+
83+## 3. Dialoguer en ACP avec les vrais agents (#2)
84+
85+Les commandes de cette partie se lancent depuis `spikes/acp-trace` :
86+
87+```bash
88+cd spikes/acp-trace
89+```
90+
91+**Alice — conversation et Markdown** :
92+
93+```bash
94+go run . -agent alice -out /tmp/alice.jsonl \
95+ -prompt "Bonjour, qui es-tu ? Réponds en une phrase." \
96+ -prompt "Écris un bloc de code Go qui affiche hello."
97+```
98+
99+Attendu : `== protocol version: 1`, `[commands] 3 available`, deux réponses, deux fois `== stop reason: end_turn`, puis `unloaded: hf.co/unsloth/gemma-4-E2B-it-GGUF:Q4_K_M`.
100+
101+**Riker — outils et permission acceptée** :
102+
103+```bash
104+go run . -agent riker -permission allow -out /tmp/riker-allow.jsonl \
105+ -prompt "Utilise l'outil bash pour exécuter la commande ls dans le dossier courant, puis dis-moi combien d'entrées il y a."
106+```
107+
108+Attendu : une ligne `== permission requested for "call_1", options: [allow_once allow] [allow_always allow_always] [reject_once reject] [reject_always never]`, puis la sortie de `ls` (`agent.yaml`) et une réponse du type « Il y a 1 entrée » — la formulation varie, c'est le modèle qui choisit ses mots.
109+
110+**Riker — permission refusée** (dure 1 à 3 minutes) :
111+
112+```bash
113+go run . -agent riker -permission reject -out /tmp/riker-reject.jsonl \
114+ -prompt "Utilise l'outil write_file pour créer le fichier notes.txt contenant le mot hello."
115+```
116+
117+Attendu : Riker réessaie en boucle, puis `exceeded maximum tool call iterations (40)` et `exit status 1`. C'est le comportement observé dans la sandbox et documenté dans l'ADR 0001 ; ce n'est pas un bug du guide. Vérifiez qu'aucun fichier n'a été créé : `ls ../../agents/riker` n'affiche que `agent.yaml`.
118+
119+**Garfield — skill via une commande slash** :
120+
121+```bash
122+go run . -agent garfield -out /tmp/garfield.jsonl -prompt "/idioms Il pleut des cordes."
123+```
124+
125+Attendu : `[commands] 7 available`, une ligne `[tool read] read_skill: idioms`, puis une traduction du type « It's raining cats and dogs. ».
126+
127+**Garfield — annulation** :
128+
129+```bash
130+go run . -agent garfield -cancel-after 4s -out /tmp/garfield-cancel.jsonl \
131+ -prompt "Traduis en anglais, en trois paragraphes détaillés : Sidekicks est une application de bureau pour converser avec des agents d'IA."
132+```
133+
134+Attendu : `== sending session/cancel` puis `== stop reason: cancelled`.
135+
136+Après chaque commande, `../../scripts/agents.sh ps` ne doit lister ni agent ni modèle.
137+
138+- [ ] Alice répond, avec un bloc de code Go.
139+- [ ] Riker demande la permission ; accepté il exécute `ls`, refusé il boucle puis s'arrête en erreur sans créer de fichier.
140+- [ ] `/idioms` lance le skill de Garfield.
141+- [ ] L'annulation donne `stop reason: cancelled`.
142+- [ ] Aucun modèle ne reste chargé à la fin ; la pression mémoire est restée verte.
143+
144+## 4. Le prototype d'interface, en développement (#3)
145+
146+```bash
147+cd ../wails-ui
148+cd frontend && npm install && cd ..
149+wails3 dev
150+```
151+
152+Le premier lancement compile le Go et le frontend (une à deux minutes). Une fenêtre « Sidekicks — UI spike » s'ouvre. Vérifiez :
153+
154+1. **Panels** : glissez les deux séparateurs verticaux et le séparateur horizontal. Quittez (⌘Q), relancez `wails3 dev` : la disposition est restaurée.
155+2. **Streaming** : cliquez sur **Simuler (50 chunks/s)**. La réponse s'affiche au fil de l'eau, le bloc Go est coloré **pendant** l'écriture, le tableau est rendu, la citation affiche `<img src=x onerror="alert(1)">` comme du texte (aucune alerte). Le compteur affiche environ `219 chunks · 4500 ms`.
156+3. **Débit** : cliquez sur **Simuler (500 chunks/s)**. L'interface reste fluide ; le compteur affiche moins d'une seconde.
157+4. **Terminal** : cliquez dans le panel noir, tapez `ls`, puis `top` ; agrandissez le panel du bas pendant que `top` tourne : l'affichage suit. Quittez `top` avec `q`.
158+5. **Éditeur YAML** : le panel de droite colore le YAML ; tapez du texte, l'édition fonctionne.
159+6. **Thème** : Réglages Système → Apparence → basculez Clair / Sombre : la conversation, le code et le dock suivent (l'éditeur YAML garde le thème du lancement — limite connue du prototype).
160+7. **Fenêtre macOS** : la barre de titre est intégrée (boutons rouge/orange/vert sur le fond de l'application).
161+
162+- [ ] Les points 1 à 7 sont conformes.
163+
164+## 5. Le prototype empaqueté en application (#3)
165+
166+```bash
167+wails3 package
168+open bin/wails-ui.app
169+```
170+
171+`wails3 package` produit `bin/wails-ui.app`, signé ad hoc. Refaites rapidement les points 2 et 4 de la partie précédente dans l'application ouverte depuis le Finder.
172+
173+- [ ] `bin/wails-ui.app` s'ouvre et fonctionne comme en développement.
174+
175+Si ces deux parties sont conformes, l'ADR 0002 est confirmé : fermez la dernière tâche de l'issue #3 (« Lancer le prototype sur macOS »), passez l'issue à `closed`, puis la milestone **Initialize** à `closed` dans `.tickets/milestones.yaml`. Sinon, notez dans un commentaire de l'issue #3 ce qui diffère (capture d'écran bienvenue).
176+
177+## 6. Les maquettes (#6)
178+
179+Ouvrez `docs/design/wireframes.drawio` avec l'extension VS Code **Draw.io Integration** (recommandée par le dépôt) ou sur [app.diagrams.net](https://app.diagrams.net). Les six pages correspondent aux six écrans ; les PNG du même dossier en sont le rendu.
180+
181+Critère d'acceptation de l'issue #6 à valider : le parcours « je crée un channel, j'invite Alice, je lui pose une question » se lit d'écran en écran (écrans 6, 1, 3 et 2).
182+
183+- [ ] Le fichier s'ouvre avec ses 6 pages.
184+- [ ] Le parcours est compréhensible ; sinon, commentez l'issue #6.
185+
186+## En cas de problème
187+
188+| Symptôme | Cause probable | Remède |
189+| --- | --- | --- |
190+| `"mm" ne peut pas être ouvert` | quarantaine Gatekeeper | `xattr -d com.apple.quarantine /usr/local/bin/mm` |
191+| `agents.sh: llmman does not answer…` | llmman arrêté ou sur un autre port | lancez llmman, ou `export LLMMAN_URL=http://127.0.0.1:<port>` |
192+| `agents.sh: could not lock …` | un `agents.sh` tué brutalement | `rm -rf .run/agents/.lock` |
193+| `wails3: command not found` | `GOPATH/bin` absent du `PATH` | `export PATH="$(go env GOPATH)/bin:$PATH"` |
194+| `wails3 dev` attend 60 s puis échoue | dépendances npm absentes | `cd frontend && npm install` |
195+| La pression mémoire passe au rouge | un modèle est resté chargé | `scripts/agents.sh unload --all` |
196+
197+## Voir aussi
198+
199+- [Comment lancer un agent de test](lancer-un-agent-de-test.md) · [Comment lancer les tests](lancer-les-tests.md)
200+- [Référence : scripts/agents.sh](../reference/script-agents.md)
201+- Pourquoi ces choix : [Pourquoi ACP](../explanation/pourquoi-acp.md) · [La stack de l'interface](../explanation/stack-interface.md)
modified spikes/wails-ui/README.md +2 -2
@@ -19,7 +19,7 @@ Then:
1919 cd spikes/wails-ui
2020 wails3 dev # hot reload
2121 # or
22-wails3 build && open bin/wails-ui.app
22+wails3 package && open bin/wails-ui.app # build + .app bundle
2323 ```
2424
2525 ## What to check
@@ -31,4 +31,4 @@ wails3 build && open bin/wails-ui.app
3131
3232 ## Where it was verified
3333
34-Built and run on Linux arm64 (Ubuntu 26.04, GTK4 + WebKitGTK 6.0, Xvfb) inside the development sandbox on 2026-10-29: layout, streaming at 50 and 500 chunks/s, Shiki colouring, sanitisation and the PTY terminal work. **It has not been run on macOS yet**: that check is for the project owner.
34+Built and run on Linux arm64 (Ubuntu 26.04, GTK4 + WebKitGTK 6.0, Xvfb) inside the development sandbox on 2026-10-29: layout, streaming at 50 and 500 chunks/s, Shiki colouring, sanitisation and the PTY terminal work. **It has not been run on macOS yet**: that check is for the project owner, following [How to test milestone Initialize on macOS](../../docs/en/how-to/test-milestone-initialize-on-macos.md).
@@ -19,7 +19,7 @@ Then:
19 cd spikes/wails-ui19 cd spikes/wails-ui
20 wails3 dev # hot reload20 wails3 dev # hot reload
21 # or21 # or
22-wails3 build && open bin/wails-ui.app22+wails3 package && open bin/wails-ui.app # build + .app bundle
23 ```23 ```
24 24
25 ## What to check25 ## What to check
@@ -31,4 +31,4 @@ wails3 build && open bin/wails-ui.app
31 31
32 ## Where it was verified32 ## Where it was verified
33 33
34-Built and run on Linux arm64 (Ubuntu 26.04, GTK4 + WebKitGTK 6.0, Xvfb) inside the development sandbox on 2026-10-29: layout, streaming at 50 and 500 chunks/s, Shiki colouring, sanitisation and the PTY terminal work. **It has not been run on macOS yet**: that check is for the project owner.34+Built and run on Linux arm64 (Ubuntu 26.04, GTK4 + WebKitGTK 6.0, Xvfb) inside the development sandbox on 2026-10-29: layout, streaming at 50 and 500 chunks/s, Shiki colouring, sanitisation and the PTY terminal work. **It has not been run on macOS yet**: that check is for the project owner, following [How to test milestone Initialize on macOS](../../docs/en/how-to/test-milestone-initialize-on-macos.md).