build: align fresh-clone setup with the canonical verification gate

[WalksWithASwagger]

Summary

Make the documented runtime, fresh-clone setup, portal startup, and deterministic local verification contract match CI and the locked dependency graph.

Context

• Roadmap phase: Phase 1 - polish and stability
• Operational gate: pipeline: make agent-ready intake atomic and idempotent #338 must fix the ready-intake race observed on this issue before a maintainer re-arms it.
• Relevant files: package.json, .github/workflows/ci.yml, README.md, CONTRIBUTING.md, docs/FRONTEND.md, docs/FOLDER-LAYOUT.md, lib/server.py
• Current behavior: docs omit frontend installation, declare Node 20.17 although locked Vite needs 20.19, omit the portal output-directory prerequisite, and call npm run verify a full closeout gate even though it skips several deterministic CI checks.
• Desired behavior: one reproducible setup and one truthful deterministic verification command work from a fresh checkout.

Implementation Notes

• Use Node 20.19+ as the whole-checkout minimum while preserving npm 10+ compatibility unless evidence requires a stricter npm version.
• Document both root and frontend npm ci steps and Python virtualenv installation.
• Make npm run verify cover deterministic non-network CI gates, or introduce one clearly named canonical equivalent and stop calling the narrower command complete.
• Keep dependency audits documented as networked CI/release gates if they do not belong in the deterministic local command.
• Do not make portal startup install dependencies implicitly.

Acceptance Criteria

• Runtime requirements agree across package.json, README, contributing docs, and the frontend lockfile.
• Fresh-clone setup installs root, frontend, runtime Python, and development Python dependencies.
• Portal docs state that an output directory must exist or provide an existing --output-dir.
• One root command runs all deterministic lint, test, frontend, E2E, docs, public-boundary, smoke, package, and doctor gates expected before handoff.
• CI invokes or is demonstrably aligned with that canonical deterministic command.
• Documentation no longer claims broader coverage than scripts provide.

Tests/Evals

• Add or update script-level tests only where command composition needs protection.
• Do not invoke providers or require real credentials.

Verification

• npm run verify
• npm run docs:check
• npm run pack:check
• npm run doctor
• Compare the canonical command with .github/workflows/ci.yml step by step.

Agent Instructions

• Use branch codex/issue-<this-issue>-setup-verify-contract.
• Do not re-add agent:ready until pipeline: make agent-ready intake atomic and idempotent #338 is merged and a maintainer clears the false escalation.
• Keep this to setup, scripts, and documentation; no application refactors.
• Use lockfile evidence for runtime minimums.
• Preserve the agent environment rules in AGENTS.md.

Human Checkpoints

• Stop if the change would require selecting a new package manager or Python environment manager.

Out of Scope

• Updating application dependencies.
• Adding a Python lockfile.
• Publishing or deploying.
• Bundling the frontend into the npm package.

Linear

Not applicable. Rafiki delivery is GitHub-only; do not create or update a Linear issue.

[github-actions]

Agentic dev loop started on branch codex/issue-321-build-align-fresh-clone-setup-with-the-canonical with provider noop.

[github-actions]

Agentic dev loop finished without opening a PR. Status: no-pr. Provider: noop.

[github-actions]

Agentic issue quality gate failed: Stop labels present: in-progress