prove on one item then arm, and ask the API instead of searching for it

read the transcript of a real setup: 6m39s, 44 tool calls, and two things
took most of it.

forty-five seconds hunting the filesystem for what one endpoint answers.
two finds in the wrong capabilities directories, three greps through
src/servers, a Read of the tasks router itself, and then `find /` across
the whole machine — to learn which inputs a task takes, which
GET /api/tasks/<dirName> returns in one call. that one is partly mine: i
stripped the endpoint out when the template stopped naming transcription
specifics, and left "never change the platform" without its positive half.
so: ask the API, it describes itself, and never read the platform to find
out what something is.

two minutes waiting for the backlog. it armed, then slept 8, slept 20,
slept 45, opened a Monitor, scheduled a wakeup at 60s and tailed
repeatedly — all so it could say "armed" only after eight existing memos
had finished. now: run the action against ONE item to prove the pipeline,
then arm, and let the watcher take the backlog on its first pass. that is
what a watcher is for, and it scales with the work rather than with how
long the owner has had that folder.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043

src/servers/api/command-hq/directory.ts

@@ -72,6 +72,14 @@ export function credentialSection(credentialPath: string | null): string[] {
     '`POST /api/tasks/<dirName>/run` runs one and returns what it did — one reviewed definition on disk',
     'instead of a re-implementation living in a loop nobody reads.',
     '',
+    '**Ask the API what things are. Never read the platform to find out.** `GET /api/tasks/<dirName>`',
+    'returns a task in full: what it does, every input it takes, which are required. That is one call, it',
+    'is authoritative, and it stays true when the code moves.',
+    '',
+    'Searching the disk for it is the trap, and it is expensive in a way that does not look expensive:',
+    'greps through the platform source, a `find /` across the whole machine, reading a router to work out',
+    'a route that is already documented at the route itself. Minutes, for an answer one request had.',
+    '',
     'It reaches everything the platform does EXCEPT administering it — installing plugins, managing users',
     'or roles, changing server settings. That holds for features added later too: the rule is resolved per',
     'request rather than frozen into a list, so a plugin installed next year is already covered without',
@@ -341,6 +349,15 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string {
     'guess, and a wrong condition either never fires or fires constantly — either way it is found out days',
     'later.',
     '',
+    '**Prove the pipeline on ONE item, then arm. Do not process the backlog first.** Run the action against',
+    'a single existing item to see that it works end to end — that is the test, and it takes seconds. Then',
+    'arm, and let the watcher pick up everything else that is already there on its first pass.',
+    '',
+    'Waiting for a backlog before saying "armed" is the slowest possible way to start, and it scales with',
+    'how long the owner has had that folder rather than with anything you are doing. The watcher already',
+    'knows how to handle items it has not seen — that is the whole of what a watcher is — so handing it the',
+    'backlog costs nothing and hands the owner a running commander in the time one item takes.',
+    '',
     'Once the job is settled, write it into this file, replacing this section: what you watch for, what you',
     'do about it, and which numbers were guesses. The next session should read the answer, not the',
     'questions.',