Environment facts: ids, archived sandbox, Go missing, and the exact heartbeat test

Measured: six Pi agents and their ids, the user key rule, blocker endpoint, sandbox
archived (DELETE returned 500), scratch repo removed, Go not installed, repo has no
remote. The wake step is named as unproven with the endpoint that should trigger it.

AGENTS.md

@@ -61,14 +61,17 @@ this per task. `docs/PAPERCLIP-API-NOTES.md` has the measured response.
 
 Only the first item of `CHECKLIST.md`. One task, really run, with no interface.
 
-1. The sandbox project `spike-2026-11-09` already has two tasks: `AUD-157` and `AUD-158`,
-   the second blocked by the first. Safe to use or delete.
-2. Assign the first task to the Pi agent and see whether a heartbeat picks it up. **This
-   is unproven.** If assignment does not wake an agent, write down exactly what happened;
-   do not build a workaround yet.
-3. Watch the status change, read the comment the agent writes, read the cost, and find the
+1. Read `docs/ENVIRONMENT-FACTS.md` first. It has the company id, the agent ids, the fact
+   that Go is not installed, and the sandbox project's state.
+2. Make a fresh sandbox project with the payload in `docs/PAPERCLIP-API-NOTES.md`, or reuse
+   the archived one. Assign one task to `Builder` (`403de1f7-…`).
+3. Trigger the wake with `POST /api/agents/{id}/heartbeat/invoke`, then read
+   `GET /api/issues/{id}/runs` and `.../activity`. **Whether a heartbeat wakes Pi is
+   unproven.** If no run starts, write down what the API said and stop; do not build a
+   workaround.
+4. Watch the status change, read the comment the agent writes, read the cost, and find the
    worktree Paperclip created.
-4. Report what you saw, with the commands and the responses.
+5. Report what you saw, with the commands and the responses.
 
 Do not start the Go program until that passes.
 

CHECKLIST.md

@@ -10,8 +10,9 @@ Tick each line. Nothing after the first unchecked line should be started early.
 
 ## Milestone 1 — one task, really run (no interface)
 
-- [ ] Read the sandbox from `docs/PAPERCLIP-API-NOTES.md`; it has two tasks, the second blocked by the first.
-- [ ] Give the first task to the Pi agent on the task (assign it) and let a heartbeat run it.
+- [ ] Read `docs/ENVIRONMENT-FACTS.md` for the company id, agent ids and toolchain facts.
+- [ ] Make a sandbox project (payload in `docs/PAPERCLIP-API-NOTES.md`) with two tasks, the second blocked by the first.
+- [ ] Assign the first task to `Builder` and force a wake with `POST /api/agents/{id}/heartbeat/invoke`. **Unproven** — if no run appears, record the response and stop.
 - [ ] Watch: the task goes `todo` → `in_progress` → `done`.
 - [ ] Confirm a comment written by Pi holds what it did.
 - [ ] Confirm the cost appears: `GET /api/issues/{id}/cost-summary`.

README.md

@@ -11,6 +11,8 @@ If you are the person: read these in order:
 2. `docs/PLAN.md` — the plan: the four screens, the milestones, what is Paperclip's job and what is ours.
 3. `docs/PAPERCLIP-API-NOTES.md` — what we measured against your running Paperclip, with the endpoint and the response.
 4. `CHECKLIST.md` — the exact steps for the next session, in order, with boxes to tick.
+5. `docs/ENVIRONMENT-FACTS.md` — the ids, the installed tools, and the one step that is
+   still unproven.
 
 ## The one-line version
 
@@ -23,7 +25,8 @@ Nothing else.
 - Paperclip server running locally on `http://127.0.0.1:3100` (it is; 685 endpoints).
 - `PAPERCLIP_BOARD_KEY` in the environment — the **user** key. The terminal program uses
   this one. An agent key cannot write outside a heartbeat run.
-- Go toolchain, for the terminal program.
+- Go toolchain — **not installed yet**; add `go` to `/etc/nixos/configuration.nix` before
+  Milestone 2. See `docs/ENVIRONMENT-FACTS.md`.
 - Pi, which is already the worker adapter on your Paperclip agent.
 
 ## Rules for this project

docs/ENVIRONMENT-FACTS.md

@@ -0,0 +1,62 @@
+# Facts about this machine, checked 2026-11-09
+
+Everything here was measured with a command. Anything not measured is marked unproven.
+
+## Paperclip
+
+- Running locally: `http://127.0.0.1:3100`. Public UI: `https://paperclip.lab.audasmedia.com.au`.
+- Company: `d4921013-e5da-4d88-8016-57d5746e2d03`
+- Agents, all running the Pi adapter (`pi_local`), all idle:
+  - `Hub` — `108c6220-c9e1-4b62-9e0a-6a763e0d28fd` (this is the identity of `PAPERCLIP_API_KEY`)
+  - `Builder` — `403de1f7-645c-4d35-bc7e-19b01d77bacc`
+  - `Chief of Staff` — `232f1f9e-bac0-4185-8a0e-eddbead33e04`
+  - `Documenter` — `706ffc88-120f-46c4-a5d9-ffa12e2ad5f0`
+  - `researcher` — `a6a2c0ee-570e-4f89-a977-83136b534a2f`
+  - `System` — `fe7a1881-1df9-481b-af74-87292fef288c`
+- Writes need the user key: `PAPERCLIP_BOARD_KEY`. The agent key `PAPERCLIP_API_KEY` is
+  refused with 403 outside a heartbeat run.
+- Blockers live at `GET /api/issues/{id}/diagnostics/blockers`, **not** on the task list.
+
+## The sandbox project
+
+- `spike-2026-11-09` is **archived**: status `cancelled`, renamed
+  `spike-2026-11-09 (deleted)`, id `9e3f61f6-cce9-49b1-8083-3130345a04a5`.
+- `DELETE /api/projects/{id}` returned 500, so it was archived instead. Its two tasks
+  (`AUD-157`, `AUD-158`) remain inside the archived project. **Deleting an archived project
+  is still untested.**
+- Its scratch repo `/tmp/pc-sandbox` was removed.
+- To make a fresh sandbox, use the payload recorded in `PAPERCLIP-API-NOTES.md`:
+  `POST /api/companies/{companyId}/projects` with `name`, `status: "backlog"` and
+  `workspace: { name, sourceType: "git_repo", cwd, isPrimary: true }`.
+
+## The unproven step: does a heartbeat wake an agent?
+
+Measured: a task can be created, given a blocker, and commented on. **Not** measured: that
+assigning a task causes Pi to wake and work.
+
+The endpoint that should start it exists:
+
+```
+POST /api/agents/{id}/heartbeat/invoke      (empty body)
+```
+
+Test in this order, and write down the response at each step:
+
+1. Assign a task: `PATCH /api/issues/{id}` with `{"assigneeAgentId":"<agent id>"}`.
+2. Either wait for a scheduled heartbeat, or force one:
+   `POST /api/agents/{agentId}/heartbeat/invoke`.
+3. Read `GET /api/issues/{id}/runs` and `GET /api/issues/{id}/activity` to see whether a
+   run started.
+4. If no run appears, the wake needs something we have not configured (a routine, a
+   schedule, or a wake trigger). Record the facts; do not build a workaround.
+
+## Toolchain
+
+- **Go is not installed on this machine.** `go version` → not found. The terminal program
+  needs it. Under Nix, add `go` to `/etc/nixos/configuration.nix` and rebuild; do not
+  install it by hand.
+
+## The new repository
+
+- Local git repo only, one commit, no remote. It is not on Gitea. Push it somewhere before
+  relying on it, or accept that only this machine has it.