docs(install-safety): preserve platform split in Step 3 upgrade preview

[4gjnbzb4zf-sudo]

{
"schema": "spark-compete-hotfix-v1",
"event": "spark-compete-first-event",
"submission_mode": "public_repo_pr",
"submission_target_url": "#176",
"team": {
"name": "SparkThisUp",
"members": [
"ValHallaBuilder",
"Baz707",
"DanFireDash"
],
"github_accounts": [
"4gjnbzb4zf-sudo"
],
"llm_device_holder": "ValHallaBuilder",
"device_holder_github": "4gjnbzb4zf-sudo"
},
"target_repo": {
"id": "vibeforge1111/Spark-Agent-Site",
"source": "https://github.com/vibeforge1111/Spark-Agent-Site",
"owner_surface": "agent-site"
},
"issue": {
"type": "documentation_gap",
"severity": "low",
"title": "docs install-safety Step 3 renders bash + PowerShell commands in one unlabeled block while Steps 1+2 split them by platform",
"actual_behavior": "docs/install-safety/index.html Step 3 ('Preview an upgrade') stacks the bash and PowerShell commands in a single unlabeled command-list block. Steps 1 and 2 on the same page explicitly split their commands under 'macOS, Linux, or WSL' / 'Windows' headings. Sequential readers can copy the wrong-platform line in Step 3 because the visual cue for which line applies to their OS is missing.",
"expected_behavior": "Step 3's command-list block splits the bash and PowerShell commands under the same 'macOS, Linux, or WSL' / 'Windows' headings used in Steps 1 and 2. The page's agent-readable docs/install-safety.md already preserves the split; only the rendered HTML surface regressed.",
"repro_steps": [
"gh pr checkout ",
"Open docs/install-safety/ in a browser (or rendered via the site's static-build).",
"BEFORE: Step 3 shows both commands in one unlabeled block.",
"AFTER: Step 3 mirrors Steps 1+2 -- bash under 'macOS, Linux, or WSL', PowerShell under 'Windows'."
],
"affected_workflow": "First-time readers walking the safety-preview steps top-to-bottom. The previous single-block render created a copy-the-wrong-line failure mode in Step 3 that Steps 1+2 already protect against."
},
"evidence": {
"safe_links_only": true,
"before_after_proof": "Single-file change: docs/install-safety/index.html, +4 lines. The Step 3 command-list block is split into the two heading + code-block pairs that Steps 1 and 2 already use. No script, CSS, or JS changes. Both check-docs-readiness.mjs and check-command-docs.mjs gates pass.",
"links": [
"https://github.com//pull/176"
],
"forbidden": [
"pdf",
"zip",
"exe",
"unknown downloads",
"shortened links",
"archives",
"binaries",
"tokens",
"browser cookies",
"wallet material",
"raw logs",
"raw conversations",
"raw memory",
"raw patches",
"private repo maps",
"private scoring details"
]
},
"proposed_fix": {
"approach": "Split the Step 3 command-list block in docs/install-safety/index.html into two labeled groups mirroring the structure already used in Steps 1 and 2 of the same page. The agent-readable Markdown counterpart already carries the split; this restores parity on the HTML surface.",
"files_expected": [
"docs/install-safety/index.html"
],
"tests_or_smoke": "check-docs-readiness.mjs + check-command-docs.mjs both pass (green). Visual review of rendered docs/install-safety/ confirms Step 3 mirrors Steps 1+2 split layout."
},
"pr": {
"branch": "sentinel/ux-friction/docs-install-safety-platform-split",
"title_prefix": "[spark-compete]",
"author_github": "4gjnbzb4zf-sudo",
"body_must_include": [
"packet",
"team",
"pr_author",
"repo",
"actual_behavior",
"expected_behavior",
"repro_steps",
"before_after_proof",
"tests_or_smoke",
"duplicate_notes",
"risk_notes",
"review_claim"
],
"url": "#176"
},
"review_claim": {
"impact_claim": "low",
"evidence_types": [
"redacted_terminal_excerpt"
],
"duplicate_notes": "Pre-flight check returned PR #45 on the same page (reframes the descriptive sentence above Step 3 -- different goal, different lines). This PR fixes the command-list block below; no exact-line collision.",
"risk_notes": "Local scope: docs HTML only. No script / CSS / JS / runtime code touched. Agent-readable Markdown counterpart already carries the same split, so this restores parity rather than introducing new structure.",
"review_state_requested": "pr_review"
}
}

[4gjnbzb4zf-sudo]

I was walking through /docs/install-safety/ in the browser and got tripped up at Step 3. Steps 1 and 2 each have their own card that clearly says "Preview a new install on macOS, Linux, or WSL" or "Preview a new install on Windows" with one command per platform. I knew exactly which line to copy.

Step 3 ("Preview an upgrade when Spark is already installed") puts both the bash spark-install.sh --dry-run --upgrade-existing line and the powershell -NoProfile ... line into the same <div class="command-list"> with no platform label between them. On a fresh visit you read them as a sequence to run together rather than a "pick one for your OS" choice.

The agent-readable companion at docs/install-safety.md already gets this right:

Existing install preview:
   ```bash
   bash spark-install.sh --dry-run --upgrade-existing

Windows existing install preview:

powershell -NoProfile -ExecutionPolicy Bypass -File .\spark-install.ps1 -DryRun -UpgradeExisting

So the markdown source preserves the platform split; the rendered HTML page is the surface that lost it.

The patch puts each command back under its own `<strong>macOS, Linux, or WSL</strong>` / `<strong>Windows</strong>` heading inside Step 3, matching the Step 1 / Step 2 pattern on the same page. No new strings outside the existing copy, no JS changes, no CSS changes.

Local checks before push:

- `node scripts/check-docs-readiness.mjs` -> `docs readiness ok: 12 pages, 37 internal links.`
- `node scripts/check-command-docs.mjs` -> `command docs content ok: 12 coach moments, 32 Spark CLI examples`

Diff is +4 / -0 in `docs/install-safety/index.html` only.