--- name: knock description: Manages spt access control — asking another endpoint to let you reach it, answering the knocks waiting for you, and handing out or redeeming invite codes. Use when the user says "knock", "let me reach", "approve the knock", "invite code", "who is knocking", or asks why a peer cannot message this endpoint. --- # Knock A knock asks another endpoint to let you reach it. It is a request, never a grant: answering it is what writes an access rule, and the answer belongs to the endpoint being asked. This is not the subnet skill — a subnet pairs machines; a knock grants reach between endpoints. Confirm the flags against `spt knock --help` before running anything; the surfaces and flags below are the published contract for spt-core 0.54.0 and later. ## Pick the verb - **Ask to reach someone:** `spt knock --send-only` or `spt knock --send-receive`. The bare form is `spt knock send `; it asks for the `MSG` surface by default. Add `--surfaces ` only when the user means more than messaging. - **See what is waiting for you:** `spt knock list` (add `--for ` for another endpoint on this machine). Each pending knock prints its id. - **Answer one:** `spt knock approve --approve-requested` grants exactly what was asked; `spt knock deny ` refuses it. - **Hand out an invite:** `spt knock new-code --surfaces MSG` mints a single-use code. A code is sealed to your subnets: omit `--subnet` and it seals to every subnet you belong to; name subnets to narrow who can redeem it, because a redeemer must share one of them to read the code's route at all. - **Present a code you were given:** `spt knock redeem --send-only` or `--send-receive`. Redeeming is you doing the asking, so it takes the directionality flag too. A subcommand name always wins over a bare target: an endpoint whose id is `send`, `list`, `approve`, `deny`, `new-code` or `redeem` is knocked as `spt knock send `. ## Directionality is declared by the asking side only `send` and `redeem` require exactly one of `--send-only` or `--send-receive`. There is no default: a bare invocation refuses and names both, and passing both refuses too. - `--send-only` asks to reach them and deliberately not the reverse. The decline is recorded. - `--send-receive` also pre-authorizes the reverse on your own side. Your own side writes that rule only if and when they answer; nobody writes another endpoint's rules. - `approve` and `new-code` take no directionality flag. Accepting is your own side's act. To reach someone you approved, knock back: `spt knock send --send-only`. - `--send-only` never bars replies: a message correlated to your own outbound is admitted with no rule of its own. Teach it as "they can answer what you send", never as a permanent back-channel. The old spellings `--mutual` and `--one-way` are parse errors with no aliases; use what `spt knock --help` lists. ## Impart a note about whoever you admit `--monic ""` on `approve` or `new-code` records your standing note about the peer so their messages do not arrive with the trust warning. A note you already hold wins; the output says which happened. A knocker without an endpoint id (a person at a terminal) cannot be classified — the grant still stands. ## What to expect - A knock is quiet on purpose: it lands in the target's inbox and is never pushed at its agent. Nothing you did failed. If the user expects an answer, run `spt knock list` rather than waiting to be told, and never treat silence as proof that nobody has knocked at you. - Only two things notify: an approval notifies the knocker, and a redemption notifies the code's minter. - A redeem answer is `redeemed`, `refused` (one message for every cause, on purpose), or `unconfirmed` — silence is not a refusal, the code was not spent, present it again later. - `MSG` binds a single sender. Machine-scoped surfaces admit the knocker's whole machine (`--admit-node`); approve those only when the user means to. Report the verb you ran and its printed outcome verbatim. Do not invent a grant, a notification, or an answer the command did not print.