[groupsky]

Refs #159

Say who gets what: the agent asks, a person approves on the phone, the value goes only into the environment of one command, and nodkey never puts it into the agent's chat. The limit is next to that claim: the agent writes the command, so a bad command can print or send the value.

Progress

• AGENTS.md and .claude/agents/security-reviewer.md describe nodkey as: access after approval, nodkey never shows the secret to the agent
• DESIGN.md L5–9 and goal 1 (L34) reworded; SECURITY.md scope line too
• README opening: the secret goes to the command, not to the agent, with the limit next to it
• README: generated "who sees the secret" picture near the top
• README warning, "How it works", phone message (verified vs claimed), "Try it" and the GH_TOKEN line say who sees what
• Technical limits stay honest (API secret in the command's environment on the agent machine; SSH keys never leave the broker)
• Review and security review (two rounds; all findings fixed)
• Green CI

Choices

• The picture is a Schemdraw flow chart (docs/diagrams/src/who-sees-the-secret.py), rendered to SVG and PNG with the workspace's draw tool. The README links the SVG. Schemdraw was the lean choice: one short Python file, no new tool in this repo, and no build step in CI.
• The issue body said "the agent never sees the secret"; the later comment by groupsky corrected this to "nodkey never puts it there", with the limit next to it. The text follows the comment.
• The security review found a second limit: the command runs as the agent's user, so a bad agent can read the value from /proc/PID/environ while the command runs. README, DESIGN.md, AGENTS.md and the reviewer brief now say this next to the claim, and THREAT-MODEL.md section 5 item 1 no longer says root is needed for it.
• The picture keeps the arrow label "output only", as the issue asks: it means nodkey sends the agent the output, not the value. The limits are in the text right above the picture.