create-hawk-app: make GitHub optional, verify the app actually renders

[willtoth]

Findings from a live 2h35m run of create-hawk-app that produced a working app but hit three avoidable walls. None of them were the model going off-script — the skill and the template told it to do those things.

1. GitHub was mandatory on every path

The template repository was private, so even the "never leaves this computer" path needed gh and a signed-in account. SKILL.md called it "required, not optional". That forces a GitHub account on a skill whose stated audience "has never programmed or used Git".

FRC2713/hawk-app-template is now public, so downloading it needs Git and nothing else.

• preflight.sh / .ps1 gain --github yes|no|unknown (default no) and a third report level, Worth knowing, that reports without blocking. Only Needs attention still exits 1.
• Template access is probed with an anonymous git ls-remote. If that fails but a credentialed one succeeds, the repo has gone private again and preflight says so — instead of passing on borrowed credentials and stranding the next student on a fresh machine.
• The GitHub question moves to phase 1, where it decides which tools are needed at all. gh is installed just in time, only on a yes. The this-computer-only path is a plain git clone.

Verified: with gh absent from PATH and an empty environment, preflight now exits 0 and an anonymous clone succeeds.

2. The app rendered as unstyled text and every check passed

The template shipped security.csp: true; Astro only hashes inline styles at build time, so the dev server's inline Tailwind was blocked. /health returns JSON and npm run check builds for production, so nothing noticed. Fixed in FRC2713/hawk-app-template#1.

Here, phase 7 now runs npm run check:render against the server it just started, falls back to an inline CSP probe on older apps, and asks the user to confirm what they see before anything is called working. The "never treat Playwright browsers as initial requirements" rule is scoped to preflight rather than read as a ban — not being able to see the page is what turned a one-line fault into two confident wrong diagnoses.

3. Git ambushed the user at the end

The commit offer was followed by a second unplanned prompt, because user.name/user.email were unset. The user left with "let just skip git and build the app" — and the skill had no instruction for what happens next, so it improvised straight into building an entire feature, skipping the plan-approval gate AGENTS.md requires.

Identity is now read in phase 5, folded into a single commit question, a decline is accepted once and never re-asked, and the skill states plainly that it stops at the receipt.

Also: Node installed where the agent couldn't see it

The run piped curl into bash to install nvm — the pattern SKILL.md forbids, offered by the skill itself as recommended. nvm appends to ~/.bashrc below Ubuntu's non-interactive early return, so node stayed invisible to the agent's own shell and ~25 later commands carried an absolute-path prefix.

platform-setup.md now fixes an install order, prefers symlinking into ~/.local/bin (already on PATH, no profile edit — which is exactly why the gh install caused no trouble in the same session), and requires verifying with both bash -ic and bash -c, which disagree.

Plus: version was 0.3.0 in .codex-plugin and 0.4.0 everywhere else; all now 0.5.0.

Verification

• preflight.sh exercised for: default/no-gh (exit 0), --github yes without gh (exit 1), no gh on PATH at all (exit 0), bad flag value (exit 2).
• Full new-app rehearsal: plain git clone → remove remote → npm ci → doctor → dev → check:render, all green.
• ⚠️ preflight.ps1 carries the same changes but could not be executed here — WSL interop is disabled on this machine. It needs a run on Windows before release.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KwyEjaCaTwhkRkTUMq9hep