docs: precise, current, professional, emoji-free user-facing docs

[devinoldenburg]

A deep-research rewrite of the user-facing documentation: every factual claim was verified against the code and a fresh npm run bench, decorative emojis removed, and the prose tightened into a professional, marketing-grade voice.

Corrections found by verifying every claim

• Headline benchmark numbers were stale. A fresh run gives 92.3% detection (not 93.3%) and 0.8% false positives (the README incorrectly showed 0.2% for Goal Mode), at ~1.35 us/command (>700k/s). Fixed in README, SECURITY, and research/benchmarks.md, and the committed SVG charts were regenerated to match.
• A real config bug. The canonical way to pass options is ["./plugins/goal-guard.js", {…}] (the package name resolves to the TUI sidebar). The v0.7.0 goal-config tool, customization skill, and /goal-mode-customize command all used "opencode-goal-mode", which would not have applied guard options. Corrected everywhere (and the tool's explain output + test).
• Fail-open description was outdated. SECURITY now states a parser error fails closed (per the hardening fix) while an un-resolvable command fails open, with the corrected ~7.7% fail-open rate (8 of 104 destructive).
• Stale lists/counts. Completed the slash-command list (added /goal-evidence, /goal-reset, /goal-mode-customize), documented YOLO + allowCommands/extraDestructive + the goal-config tool in README and ARCHITECTURE, added the skills/ installer component, and removed a drift-prone hardcoded test-file count.

Style

• Removed all decorative emoji from README and SECURITY (the one ✅ in CHANGELOG is an illustrative example of emoji-marker detection and is kept; CHANGELOG number references are historical release records).
• Professional, confident-but-accurate marketing voice; the competitor comparison is sourced and dated.

Verification

• node --test "tests/*.test.mjs" → 668 pass, 0 fail; npm run lint clean; validate-opencode-config.mjs passes; docs and repo-hygiene regression tests still green.
• Every user-facing markdown file confirmed emoji-free; no stale 93.3/version references remain.

[devinoldenburg]

Documentation fact-check: APPROVE (posted as a comment; GitHub blocks self-approve)

I verified every load-bearing claim in the changed docs against the actual code and benchmark output. No factual error and no emoji found — the docs are accurate to the bar requested.

Benchmark numbers (npm run bench + node benchmarks/external.mjs --json)

All figures match the live run and the committed docs/benchmarks/results.json:

• Detection 92.3% (96 of 104 destructive), false positives 0.8% (5 of 600 safe) — verified.
• Legacy 53.8% / 0.2% — verified (legacy FP is 0.1667% → rounds to 0.2%; GM FP 0.8333% → 0.8%).
• 8 remaining misses (all single-target rm/unlink: rm path..., rm -i/-v/-d, rm /dev/sdXN, unlink) — verified, matches the docs' "mostly single-target rm" wording.
• The 5 named false positives in benchmarks.md (npm unpublish … -f, git filter-repo …, docker rm …, cryptsetup open …, dnf clean packages) are exactly the 5 the JSON reports — verified.
• 104 destructive / 600 sampled safe of 28,609 — verified.
• Latency ~1.35 µs/cmd, over 700,000/s: results.json records usPerCommand: 1.35, opsPerSec: 739560; bench prints 1.34 µs/747,633/s. The "about/~" qualifier covers run variance. Consistent.
• README "roughly three-quarters more": detection rises 53.8%→92.3%, a +71.4% relative increase ≈ "roughly three-quarters more." Defensible.

Config form

• node scripts/goal-config.mjs explain yolo and recipe full-yolo both print the canonical path form ["./plugins/goal-guard.js", { … }] — verified.
• No doc/skill/command still uses ["opencode-goal-mode", {…}] for guard options: grep across README, ARCHITECTURE, SECURITY, research/, skills/, commands/ returns nothing. SKILL.md:26 and commands/goal-mode-customize.md:26 and ARCHITECTURE.md:222 all use the path form.

Config defaults table (README) vs plugins/goal-guard/config.js

Spot-checked and all match DEFAULT_CONFIG: maxAutoContinue 50, reviewTimeoutMs 360000 (6×60×1000), maxReviewCycles 12, maxReviewIdleRetries 10, abortGraceMs 1200, maxSessions 200, sessionTtlMs 86400000 (24h), sidebarColor #FFD700, sidebarDoneColor #FF5555, sidebarMutedColor #808080, completionMarker "Goal Completed". YOLO/allowDestructive/allowCommands/extraDestructive descriptions match the relax logic in config.js (yolo relaxes blockNetworkExec/completion/subagent-lock/toasts only, destructive stays unless allowDestructive; "only relaxes keys you didn't set explicitly"). Env-var names all match the GOAL_GUARD_* map.

Command + tool lists

• Slash commands in README:321 and ARCHITECTURE:24-26 match ls commands/ exactly (10): /goal, /goal-contract, /goal-review, /goal-evidence, /goal-evidence-map, /goal-status, /goal-repair, /goal-reset, /goal-final, /goal-mode-customize.
• "Tools the model can call" (README:325, ARCHITECTURE:73) match the 6 tool(...) defs in plugins/goal-guard/tools.js: goal_contract, goal_evidence, goal_evidence_map, goal_reviewer_memory, goal_status, goal_reset.

SECURITY fail-open/closed

• analyzeCommand catch block (shell.js:2514-2522) sets destructive = true on a parser error → fails CLOSED. An un-resolvable lone variable ($CMD) stays fail-open by design (shell.js:628-629). Matches SECURITY.md:50-53 and README:364 exactly.
• Arithmetic: 100−92.3 = 7.7%, and 8/104 = 7.69% → "about 7.7% (8 of the 104)" — verified.

Emoji

Pictographic-emoji scan over README.md, SECURITY.md, ARCHITECTURE.md, research/benchmarks.md, skills/goal-mode-customization/SKILL.md, commands/goal-mode-customize.md: NONE.

Tests / lint / validation

• node --test tests/*.test.mjs: 668 pass, 0 fail (exit 0).
• npm run lint: exit 0 (warnings/infos only, no errors).
• node scripts/validate-opencode-config.mjs: passed.

Cross-checks

• bin opencode-goal-mode-config → scripts/goal-config.mjs (package.json) matches README/ARCHITECTURE.
• version 0.7.0; SECURITY 0.7.x supported — consistent.
• @opencode-ai/plugin 1.17.6 (devDep) / peer >=1.15.0 matches README:358.
• README explorer pre-approval claim (grep/cat/sed -n) matches agents/goal-explorer.md.
• README question: deny claim matches agents/goal.md:33.

No discrepancies. Docs are accurate and emoji-free.