web: lead getting started with the GitHub installer

Use the reviewed direct-install recommendation in shared EN/ZH content, keep npm and Cargo as alternatives, and distinguish local builds from published releases. Soft-wrap command text so narrow guide columns preserve the full installer command.

Validation: 46 website test files and 386 tests passed, 0 failed; 23 docs topics and facts checks passed; lint 0 errors, 2 existing image warnings; Next 16.3.3 webpack production build passed. Regression: prior npm-first content 1 failed/10 skipped, restored content 1 passed/10 skipped. EN/ZH 390px and desktop CUA checks preserve command text with zero command overflow. Dual-agent critique and polish, detector 0 findings. Hosted CI, deployment and real installation remain unproven.
(cherry picked from commit 6bcbe61e3afb47ffec9e491d6170273038fa34ed)

.impeccable/critique/2026-09-05T00-42-39Z__web-components-getting-started-steps-tsx.md

@@ -0,0 +1,67 @@
+---
+target: Website install step
+total_score: 21
+max_score: 28
+na_heuristics: 1,3,9
+p0_count: 0
+p1_count: 0
+target_identity: "file:/Volumes/VIXinSSD/CW/worktrees/cw-site-github-install-guide-20260904/web/components/getting-started-steps.tsx"
+target_fingerprint: "sha256:f5180f0101eebebe501c90cb467dccca62da8c3ae726a8f1ca59bc2ab5cbe50f"
+target_path: /Volumes/VIXinSSD/CW/worktrees/cw-site-github-install-guide-20260904/web/components/getting-started-steps.tsx
+timestamp: 2026-09-05T00-42-39Z
+slug: web-components-getting-started-steps-tsx
+closed: true
+---
+Method: dual-agent (A: /root/critique_design · B: /root/critique_detector)
+
+# Website install step — independent Assessment A
+
+Scope: only the changed install step in `web/lib/content/getting-started.ts`, rendered by `web/components/getting-started-steps.tsx`. Read the workspace, repository, and `web/AGENTS.md` guidance. No context script, detector, installation, or external request was run. No detector findings were seen. No source files were edited.
+
+## Verdict
+
+The copy achieves the intended hierarchy: published GitHub release on macOS/Linux first; `codewhale update` for later releases; npm/Cargo available through the full guide; local development builds explicitly separate. English and Chinese convey the same four facts. No critical copy defect found. This is a successful narrow correction, not an assessment of the complete guide or website.
+
+The wording is concrete and restrained. It belongs to a technical product and does not need a broader visual redesign. The shared content source preserves consistency between its consumers and avoids a page-specific localization fork.
+
+## Actual observations
+
+- Opened the built `/en/docs/guide` and `/zh/docs/guide` in a fresh native CUA Chrome Guest tab. Both displayed the changed paragraph, installer command, `codewhale doctor`, and descriptive localized Full install guide link.
+- The complete installer command is present in the accessibility text in both locales.
+- In the inspected desktop layout, the new long command extends beyond the narrow first-column code box and requires horizontal scrolling. The visible first line stops partway through the URL; the full release-installer destination and pipe are not visible together. This is contained code-block overflow, not established page-level overflow or lost text.
+- Source inspection confirms `<pre><code>` semantics, `overflow-x: auto` and `white-space: pre`. The renderer offers no copy control. Full keyboard scrolling, text selection, screen-reader announcements, and contrast were not tested.
+- Local installer source selects GitHub release assets and handles Darwin/Linux; local docs show this same installer and the later updater. These are source receipts, not proof of current public downloads or successful installation.
+
+## Priority issue
+
+**P2 — The longer primary install command is awkward to inspect and copy at the rendered desktop width.** The new default command makes the existing horizontal-scroll presentation more consequential: a first-time reader cannot see the complete command in one glance. Make a narrowly scoped improvement for this install command: permit soft wrapping without changing its text, or reuse an existing accessible copy control. If keeping horizontal scrolling, verify keyboard reachability and full-command selection. Do not expand this into a redesign of the four-step grid or the untouched steps.
+
+No P0/P1 issue found within this copy slice. The release/update/alternative/local-build wording needs no additional prerequisite text or warning banner.
+
+## Applicable heuristic scores
+
+| Heuristic | Score | Scope-specific basis |
+|---|---:|---|
+| System status | n/a | Static instruction; no installation was performed. |
+| Match to real world | 4 | Clear platform, release provenance, later-update instruction. |
+| User control/freedom | n/a | No stateful operation in this slice. |
+| Consistency | 4 | Shared EN/ZH content, matching local installer/docs. |
+| Error prevention | 3 | Published release and local development build are distinguished. |
+| Recognition over recall | 2 | Complete command requires horizontal inspection. |
+| Flexibility/efficiency | 2 | Long command has no direct copy action; keyboard scrolling unverified. |
+| Aesthetic/minimalism | 3 | Short, focused paragraph; one primary route with alternatives deferred. |
+| Error recovery | n/a | Installer outcome/recovery is outside the reviewed copy. |
+| Help/documentation | 3 | Clear localized link to deeper installation guidance. |
+| **Total** | **21/28** | **Good; narrow command usability improvement remains.** |
+
+Cognitive load is low for the changed decision: one recommended installation path, one validation command, and one deeper-reading link. Alternatives are named without presenting competing command menus. The long command adds interaction effort rather than conceptual ambiguity.
+
+## Evidence limits
+
+The CUA browser provider was unavailable; native CUA Chrome supplied a fresh Guest tab. EN/ZH desktop screenshots were observed without changing viewport/window size; output image size was 768×930, exact CSS viewport unmeasured. The Guest tab was closed, then browser ownership was returned to Assessment B. No mobile inspection, homepage rendering, external GitHub/install URL validation, install/update execution, broad website audit, or test suite was performed by Assessment A. Untouched steps and full-guide content were not assessed.
+
+Questions skipped: the user already authorized implementation.
+
+## Independent responsive evidence
+
+B ran the narrow markup detector once: exit 0, zero findings. Native Chrome at 390px confirmed EN/ZH command-container overflow beyond the grid, and keyboard Tab reached the localized Full install guide link with a visible outline. Root independently measured the same intrinsic-width problem in CUA: a 343px grid allocated a 382.6px track, extending the command box beyond the viewport. This strengthens A’s scoped P2 without changing its provisional 21/28 score. No P0/P1 established. Both assessments were isolated, and A completed before B findings reached synthesis. No mutable overlay was available; native screenshots and read-only DOM geometry supplied the evidence. No installer or updater was executed.

docs/releases/2026-09-04-website-install-guide.md

@@ -0,0 +1,55 @@
+# Website installation guide — local receipt, 2026-09-04
+
+Branch `fix/site-github-install-guide-20260904` is based on the installer owner's
+public candidate `cdad345275809aabe38561ee2b2b17bd4a5806b8`. It preserves that
+candidate and the separately owned website redesign branch. No installer,
+release fact matrix, credentials, hosted service or release artifact was changed.
+
+The shared EN/ZH getting-started content now leads with the direct installer
+for a published GitHub release on macOS/Linux, mentions `codewhale update` for
+later updates and retains npm/Cargo as alternatives in the full guide. It
+explicitly distinguishes local development builds. The current published-release
+record remains v0.9.11; the separately installed local v0.9.12 build is not a
+publication receipt and is not substituted into public release facts.
+
+The longer command exposed an intrinsic-width defect in the existing step
+grid. Scoped `pre-wrap` and `overflow-wrap: anywhere` keep the complete command
+visible without inserting actual line breaks into it or adding another control.
+The existing content assertion now compares the first command with the canonical
+public install recommendation instead of pinning npm-first copy.
+
+## Verification
+
+- Production Next.js **16.3.3** build with webpack passed.
+- Website suite: **46 files, 386 tests passed, 0 failed**.
+- Facts check and all **23** documentation topics passed.
+- Lint: **0 errors, 2 existing image warnings** in nav/footer.
+- Regression negative control: the previous npm-first content fails the exact
+  recommendation assertion (**1 failed, 10 skipped**); restored content passes
+  (**1 passed, 10 skipped**). No installer/update command was executed.
+- Dual-agent Impeccable review: **21/28 applicable points**, no P0/P1, detector
+  **0** findings. A and B independently found the narrow command-width issue.
+  After polish, CUA measured EN/ZH at **390×844**: grid and pre both **343px**,
+  pre scroll/client widths both **341px**, right edge **359px** within the
+  **375px** content viewport (15px desktop scrollbar). Command text remained
+  exactly `curl -fsSL https://codewhale.net/install.sh | sh` followed by
+  `codewhale doctor`. All four command boxes also had equal scroll/client widths
+  at the default **1280px** desktop viewport. Localized guide links were keyboard
+  reachable with visible focus. The baseline snapshot was read and closed after
+  the built polish check; no new score or repeated detector run is claimed.
+
+Runnable preview: `http://127.0.0.1:3135/en/docs/guide` and
+`http://127.0.0.1:3135/zh/docs/guide`. Next is served from this worktree with
+`node node_modules/next/dist/bin/next start --hostname 127.0.0.1 --port 3135`
+inside `web/`. Installed dependencies were reused locally; none were downloaded.
+
+Logs: `/tmp/cwa-app-parity-20260904/site-guide-final-tests.log`,
+`site-guide-final-build.log`, `site-guide-final-lint.log`, `site-guide-facts.log`,
+`site-guide-docs.log`, `site-guide-negative-control.log`, and
+`site-guide-regression.log`. Screenshots: `screenshots/site-guide-en-390.png`,
+`site-guide-zh-390.png`, and `site-guide-final-desktop.png` under that directory.
+Temporary viewport overrides were reset; reviewers closed their own Guest tabs.
+
+This is a narrow source/copy and local browser receipt. Hosted CI, deployment,
+actual public download/update, and customer installation remain unproven. The
+complete website and unchanged guide steps were not re-audited in this slice.

web/app/globals.css

@@ -2330,6 +2330,11 @@ a.body-link:hover { background-size: 100% 6px; color: var(--ink); }
   font-size: 0.75rem;
 }
 
+pre.gs-step-commands {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
 .gs-step-link {
   display: inline-block;
   margin-top: 0.9rem;

web/lib/content/getting-started.ts

@@ -34,10 +34,10 @@ export const GETTING_STARTED_STEPS: GuideStep[] = [
     id: "install",
     title: { en: "Install Codewhale", zh: "安装 Codewhale" },
     body: {
-      en: "One npm command installs the terminal runtime. Cargo, prebuilt archives, Docker, Nix, and China mirrors also work. All of them install published releases.",
-      zh: "一条 npm 命令即可安装终端运行时。Cargo、预编译包、Docker、Nix 和中国镜像也可以。它们安装的都是已发布版本。",
+      en: "Install a published GitHub release on macOS or Linux. Run codewhale update for later releases. npm and Cargo remain alternatives in the full guide. Local development builds are separate.",
+      zh: "在 macOS 或 Linux 上安装 GitHub 已发布版本。之后运行 codewhale update 获取新版本。完整指南中也提供 npm 和 Cargo 安装方式。本地开发构建与已发布版本分开。",
     },
-    commands: ["npm install -g codewhale", "codewhale doctor"],
+    commands: ["curl -fsSL https://codewhale.net/install.sh | sh", "codewhale doctor"],
     link: {
       href: "/install",
       label: { en: "Full install guide", zh: "完整安装指南" },

web/lib/content/vocabulary.test.ts

@@ -24,6 +24,7 @@ function repoText(path: string): string {
 
 const matrix = JSON.parse(repoText("docs/public-surface-facts.json")) as {
   product: { terminology: Record<string, string> };
+  install: { recommended: string };
   control: { modes: string[]; permissionPostures: string[] };
 };
 
@@ -148,7 +149,8 @@ describe("shared getting-started path", () => {
     // leading with the Fleet noun; see its naming/compatibility section.
     const fleetDoc = repoText("docs/FLEET.md");
     const install = GETTING_STARTED_STEPS.find((s) => s.id === "install")!;
-    expect(install.commands).toContain("npm install -g codewhale");
+    expect(install.commands[0]).toBe(matrix.install.recommended);
+    expect(repoText("docs/INSTALL.md")).toContain(install.commands[0]);
     expect(guide).toContain("codewhale doctor");
     const provider = GETTING_STARTED_STEPS.find((s) => s.id === "connect-provider")!;
     expect(provider.commands).toContain("codewhale auth set --provider deepseek");