commit 6d4bc872c15370ae5073cc12e85f7d1f904f2128
parent 3150fc9589a5e98b66fb836b6a2e5e95e93eb532
Author: I Mean I'm Just Saying <imeanimjustsaying@kiwifarms.st>
Date: Mon, 28 Sep 2026 13:11:34 -0400
docs: every `archilyzer mcp` example runs `pnpm --silent` (W2 review S1)
`pnpm archilyzer` is a `pnpm run`, and pnpm 9 and 10 print their script
banner to stdout, the JSON-RPC channel, before the server starts; only pnpm
11 prints it to stderr. `pnpm --silent -C … archilyzer mcp` (spelled out,
since `claude mcp add` has its own -s) gives one stdout line, the
initialize answer, on 9.15.4, 10.18.0 and 11.26.0. AGENTS.md, README.md,
mcp/README.md (Run it, Add to Claude Code, mcp.json) and PUBLISH.md, and
the claims that stdout is clean now say why. FACTS amended.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Diffstat:
5 files changed, 44 insertions(+), 18 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
@@ -54,14 +54,18 @@ claude mcp add archilyzer \
--env TRANSCRIPT_SITE_URL=https://jeralyzer.pages.dev \
--env ARCHILYZER_EDITOR_URL=http://localhost:3001 \
--env WORKER_TOKEN=… \
- -- pnpm -C "$PWD" archilyzer mcp
+ -- pnpm --silent -C "$PWD" archilyzer mcp
```
The two editor lines are optional: they let `fetch_clip` ask a local editor for clip
media (`WORKER_TOKEN` is the editor's own, from `editor/.env`). `archilyzer mcp`
(`common/bin/mcp.ts`) is `pnpm --filter yt-dlp-transcript-mcp exec tsx src/index.ts`
behind the repo's CLI: the environment and any `--local`/`--remote`/`--hub` pass
-through, and stdout carries nothing but the protocol (pnpm's `$ …` line goes to stderr).
+through. **Keep `--silent`** (the long spelling — `claude mcp add` has its own `-s`):
+`pnpm archilyzer` is a `pnpm run`, and pnpm 9 and 10 print its `> …` banner to STDOUT,
+the JSON-RPC channel, before the server starts (pnpm 11 prints `$ …` to stderr). With
+it, stdout carries nothing but the protocol on 9, 10 and 11 — on an installed checkout:
+pnpm 11 may install first after a pull, and that output goes to stdout either way.
`TRANSCRIPT_HUB_URL` federates several sites; `TRANSCRIPT_LOCAL_DIR` reads a local
build off disk. The server never writes to an archive — `fetch_clip` asks the editor,
diff --git a/PUBLISH.md b/PUBLISH.md
@@ -439,9 +439,11 @@ the MCP server reads it over HTTP. Register it against your public URL — as
```sh
claude mcp add archilyzer \
--env TRANSCRIPT_SITE_URL=https://<your-site>.pages.dev \
- -- pnpm -C "$PWD" archilyzer mcp
+ -- pnpm --silent -C "$PWD" archilyzer mcp
```
`archilyzer mcp` starts the same server as `pnpm --filter yt-dlp-transcript-mcp exec
-tsx src/index.ts`, with the environment passed through and nothing on stdout but the
-protocol; [mcp/README.md](mcp/README.md) has the other ways to run and register it.
+tsx src/index.ts`, with the environment passed through. `--silent` is what keeps stdout
+the protocol's alone: without it pnpm 9 and 10 print their `> …` script banner there
+first (pnpm 11 prints `$ …` to stderr). [mcp/README.md](mcp/README.md) has the other
+ways to run and register it.
diff --git a/README.md b/README.md
@@ -58,19 +58,20 @@ never modifies the archive:
```bash
# point it at a published instance over HTTP (from the repo root)
-TRANSCRIPT_SITE_URL=https://jeralyzer.pages.dev pnpm archilyzer mcp
+TRANSCRIPT_SITE_URL=https://jeralyzer.pages.dev pnpm --silent archilyzer mcp
```
There is nothing to compile — it runs from source through `tsx`. `archilyzer mcp` is
-the repo's CLI starting `mcp/`'s server; stdout carries only the MCP protocol. To
-register it with Claude Code:
+the repo's CLI starting `mcp/`'s server. Keep `--silent`: stdout is the MCP protocol's
+channel, and without it pnpm 9 and 10 print their `> …` script banner there first
+(pnpm 11 prints its `$ …` to stderr). To register it with Claude Code:
```bash
claude mcp add archilyzer \
--env TRANSCRIPT_SITE_URL=https://jeralyzer.pages.dev \
--env ARCHILYZER_EDITOR_URL=http://localhost:3001 \
--env WORKER_TOKEN=… \
- -- pnpm -C /ABS/PATH/TO/this/repo archilyzer mcp
+ -- pnpm --silent -C /ABS/PATH/TO/this/repo archilyzer mcp
```
The two editor lines are optional: they let `fetch_clip` ask a local editor for clip
@@ -323,14 +324,16 @@ claude mcp add archilyzer \
--env TRANSCRIPT_SITE_URL=https://jeralyzer.pages.dev \
--env ARCHILYZER_EDITOR_URL=http://localhost:3001 \
--env WORKER_TOKEN=… \
- -- pnpm -C "$PWD" archilyzer mcp
+ -- pnpm --silent -C "$PWD" archilyzer mcp
claude # then try: /ask what has he said about magic tournaments?
```
The two editor lines are optional: they let `fetch_clip` ask a local editor for clip
media (`WORKER_TOKEN` is the editor's own). Leave them out for research alone.
`archilyzer mcp` is `pnpm --filter yt-dlp-transcript-mcp exec tsx src/index.ts`
-through the repo's CLI; either form registers the same server.
+through the repo's CLI. `--silent` (spelled out: `claude mcp add` has its own `-s`)
+keeps pnpm's script banner off stdout, which is the protocol's channel — pnpm 9 and 10
+print it there without it.
> **Register the server as `archilyzer`.** The shipped commands call
> `mcp__archilyzer__ask_plan` / `mcp__archilyzer__sweep_plan`, and that tool name
diff --git a/mcp/README.md b/mcp/README.md
@@ -509,17 +509,22 @@ argument after `mcp` passed through:
```sh
# a deployed site
-pnpm archilyzer mcp --remote https://rekietalyzer.pages.dev
+pnpm --silent archilyzer mcp --remote https://rekietalyzer.pages.dev
# a hub, federating every member site
-pnpm archilyzer mcp --hub https://archilyzer-hub.pages.dev
+pnpm --silent archilyzer mcp --hub https://archilyzer-hub.pages.dev
# local shards on disk (a relative path resolves from mcp/, so give an absolute one)
-pnpm archilyzer mcp --local "$PWD/export/public"
+pnpm --silent archilyzer mcp --local "$PWD/export/public"
```
-Logs go to stderr; stdout is the MCP JSON-RPC channel. pnpm's own `$ …` line goes
-to stderr too, so nothing precedes the protocol.
+Logs go to stderr; stdout is the MCP JSON-RPC channel. **Keep `--silent`** (spelled
+out — `claude mcp add` has its own `-s`): `pnpm archilyzer` is a `pnpm run`, and
+without it pnpm 9 and 10 print their `> …` script banner to stdout before the server
+starts, which a client reads as broken protocol (pnpm 11 prints `$ …` to stderr).
+With it, nothing precedes the protocol on 9, 10 or 11 — on an installed checkout:
+after a pull that changed the lockfile, pnpm 11 may install first and print that to
+stdout whatever the flags, so run `pnpm install` first.
## Add to Claude Code
@@ -528,7 +533,7 @@ claude mcp add archilyzer \
--env TRANSCRIPT_SITE_URL=https://rekietalyzer.pages.dev \
--env ARCHILYZER_EDITOR_URL=http://localhost:3001 \
--env WORKER_TOKEN=… \
- -- pnpm -C /ABS/PATH/TO/yt-dlp-transcript-browser archilyzer mcp
+ -- pnpm --silent -C /ABS/PATH/TO/yt-dlp-transcript-browser archilyzer mcp
```
The two editor lines are optional: they let `fetch_clip` ask a local editor for
@@ -551,7 +556,7 @@ registers it as `archilyzer` whatever archive it reads. Under another name (say
"mcpServers": {
"archilyzer": {
"command": "pnpm",
- "args": ["-C", "/ABS/PATH/TO/yt-dlp-transcript-browser", "archilyzer", "mcp"],
+ "args": ["--silent", "-C", "/ABS/PATH/TO/yt-dlp-transcript-browser", "archilyzer", "mcp"],
"env": {
"TRANSCRIPT_SITE_URL": "https://rekietalyzer.pages.dev",
"ARCHILYZER_EDITOR_URL": "http://localhost:3001",
diff --git a/plans/FACTS.md b/plans/FACTS.md
@@ -6913,6 +6913,18 @@ out. O3's facts are the section just above ("O3 — runner lows"). Anchors are a
- **`pnpm archilyzer <command>`** is a root script (`package.json`: `pnpm --filter
yt-dlp-transcript-common exec tsx bin/archilyzer.ts`). pnpm prints its `$ …` line on stderr, so
`-- pnpm -C "$PWD" archilyzer mcp` is a clean MCP registration (stdout carries only the protocol).
+ - *Amended 2026-09-28 (release 13, slice W2 fix round, W2 review S1): true on pnpm 11 only.*
+ `pnpm archilyzer` is a `pnpm run`, and **pnpm 9 and 10 print their script banner (a blank line,
+ `> yt-dlp-transcript-browser-monorepo@0.1.0 archilyzer <dir>`, `> <command>`, a blank line) to
+ STDOUT** before the server starts — ahead of the JSON-RPC answer. pnpm 11 prints `$ <command>`
+ to stderr. `pnpm exec` prints no banner on any of them. **Register it as
+ `-- pnpm --silent -C "$PWD" archilyzer mcp`** (the long spelling: `claude mcp add` has its own
+ `-s`); measured with an initialize request against an empty `--local` dir, stdout is exactly one
+ line, the answer, on 9.15.4, 10.18.0 and 11.26.0 (`--silent` also drops pnpm 11's stderr `$`
+ line; the server's own banner stays on stderr). 9.15.4 is what the Dockerfiles install, and
+ `package.json` pins no `packageManager`. Separately, pnpm 11 may install before a `run` or an
+ `exec` in a checkout whose install is missing or stale, and prints that to stdout whatever the
+ flags (both forms). Every doc example carries `--silent` since this amendment.
- **`archilyzer doctor [--json]`** (`common/bin/doctor.ts`, row `archilyzer.ts:280`) is STRICTLY
read-only: it stats the LMDB index and never opens it, never mkdirs, never writes settings, and
calls a port "in use" when a TCP connect succeeds (it never binds). The one process-state change
