docs: public alpha onboarding improvements (slice #16)

Refactor README quickstart to lead with Makefile, use multiline CLI
commands, show --html-output, and correct API entry point to wsgi.py.
Expand CONTRIBUTING with prerequisites, clone-to-proof quickstart,
formatting workflow, and where-to-start guidance for new contributors.

Add `make proof` target running all 6 gates via .venv/bin/python
without requiring uv on PATH. Add --html-output to Makefile analyze
target and CI proof workflow. Update clean target for HTML output.

Add checked-in HTML example at examples/python_org_homepage_report.html
with deterministic contract test coverage. Link all three output formats
in README examples section.

138 total tests passing across all 6 proof gates.

Made-with: Cursor

Author: buildrr89

.github/workflows/proof.yml

@@ -59,7 +59,8 @@ jobs:
             --input examples/sample_ios_output.json \
             --app-id com.example.legacyapp \
             --json-output output/modernization_report.json \
-            --md-output output/modernization_report.md | tee proof-output.txt
+            --md-output output/modernization_report.md \
+            --html-output output/modernization_report.html | tee proof-output.txt
 
       - name: Publish proof summary
         run: |

CONTRIBUTING.md

@@ -1,19 +1,38 @@
 # Contributing
 
+## Prerequisites
+
+- [uv](https://docs.astral.sh/uv/) (Python package manager)
+- Python 3.14.3 (pinned in `.python-version`)
+- Node 20.19.5 (pinned in `.node-version`)
+- [pnpm](https://pnpm.io/)
+
+## Quickstart
+
+```bash
+git clone https://github.com/buildrr89/rade-engine.git
+cd rade-engine
+make bootstrap
+make proof
+```
+
+If all 6 gates pass, you are ready to contribute.
+
 ## Scope rule
 
-Contributions must follow the canonical read order and scope controls in [AGENTS.md](AGENTS.md) and [docs/TRUTH_HIERARCHY.md](docs/TRUTH_HIERARCHY.md).
+Contributions must follow the canonical read order and scope controls in [AGENTS.md](AGENTS.md) and [docs/TRUTH_HIERARCHY.md](docs/TRUTH_HIERARCHY.md). Read [docs/APP_SCOPE.md](docs/APP_SCOPE.md) before proposing new features.
 
 ## Workflow
 
-1. Create a branch from `main`.
+1. Create a branch from `main` (`feat/`, `fix/`, or `docs/` prefix).
 2. Keep changes small, testable, and reversible.
-3. Update canonical docs in the same PR when behavior or contracts change.
-4. Open a PR using `.github/pull_request_template.md`.
+3. Update canonical docs and tests in the same PR when behavior or contracts change.
+4. Run `make proof` and include exact outputs.
+5. Open a PR using the [PR template](.github/pull_request_template.md).
 
 ## Proof required before review
 
-Run and include exact outputs for:
+Run all gates with `make proof`, or individually:
 
 ```bash
 .venv/bin/python -m pytest -q
@@ -26,6 +45,20 @@ pnpm --dir web test
 
 If a proof command was not run, mark the result as unverified.
 
+## Formatting
+
+Auto-fix formatting before committing:
+
+```bash
+make format
+```
+
+## Where to start
+
+- Look at [docs/NEXT_EXECUTION_BACKLOG.md](docs/NEXT_EXECUTION_BACKLOG.md) for the current backlog.
+- Issues labeled `good first issue` are scoped for new contributors.
+- If you are unsure whether a change is in scope, open an issue first.
+
 ## Security
 
 Do not report vulnerabilities in public issues. Use the process in [SECURITY.md](SECURITY.md).

Makefile

@@ -8,7 +8,7 @@ export UV_CACHE_DIR ?= .uv-cache
 export UV_OFFLINE ?= 0
 PY_SOURCES ?= src tests agent
 
-.PHONY: bootstrap test lint format analyze api worker agent-scan web-install web-dev web-test clean
+.PHONY: bootstrap test proof lint format analyze api worker agent-scan web-install web-dev web-test clean
 
 bootstrap:
 	$(UV) sync --dev
@@ -17,9 +17,19 @@ bootstrap:
 test:
 	./rade-proof
 
+proof:
+	.venv/bin/python -m pytest -q
+	.venv/bin/python -m tests.runner
+	.venv/bin/ruff check $(PY_SOURCES)
+	.venv/bin/python -m black --check $(PY_SOURCES)
+	pnpm --dir $(WEB_DIR) lint
+	pnpm --dir $(WEB_DIR) test
+	@echo "All proof gates passed."
+
 lint:
 	$(UV) run ruff check $(PY_SOURCES)
 	$(UV) run black --check $(PY_SOURCES)
+	pnpm --dir $(WEB_DIR) lint
 
 format:
 	$(UV) run ruff check --fix $(PY_SOURCES)
@@ -30,7 +40,8 @@ analyze:
 		--input examples/sample_ios_output.json \
 		--app-id com.example.legacyapp \
 		--json-output $(OUTPUT_DIR)/modernization_report.json \
-		--md-output $(OUTPUT_DIR)/modernization_report.md
+		--md-output $(OUTPUT_DIR)/modernization_report.md \
+		--html-output $(OUTPUT_DIR)/modernization_report.html
 
 api:
 	./rade-devserver src.api.wsgi:application --host 127.0.0.1 --port 8000
@@ -51,4 +62,4 @@ web-test:
 	pnpm --dir $(WEB_DIR) test
 
 clean:
-	rm -rf $(OUTPUT_DIR)/*.json $(OUTPUT_DIR)/*.md .uv-cache .ruff_cache
+	rm -rf $(OUTPUT_DIR)/*.json $(OUTPUT_DIR)/*.md $(OUTPUT_DIR)/*.html .uv-cache .ruff_cache

README.md

@@ -17,22 +17,44 @@ RADE accepts a structured JSON payload or a public URL, runs deterministic struc
 
 ## Try It
 
-Prerequisites: `uv`, Python `3.14.3`, Node `20.19.5`, and `pnpm`.
+Prerequisites: [uv](https://docs.astral.sh/uv/), Python 3.14.3, Node 20.19.5, and [pnpm](https://pnpm.io/).
 
 ```bash
-# Install
+# Install all dependencies
+make bootstrap
+# or manually:
 uv sync --dev
 .venv/bin/python -m playwright install chromium
 pnpm --dir web install
+```
 
-# Analyze a public URL
-uv run python -m src.core.cli analyze   --url https://example.com   --json-output output/example_report.json   --md-output output/example_report.md
+Run the sample analysis:
 
-# Or analyze a local JSON fixture
-uv run python -m src.core.cli analyze   --input examples/sample_ios_output.json   --app-id com.example.legacyapp   --json-output output/modernization_report.json   --md-output output/modernization_report.md
+```bash
+make analyze
+# produces output/modernization_report.{json,md,html}
 ```
 
-See [examples/python_org_homepage_report.md](examples/python_org_homepage_report.md) for a checked-in report example.
+Or use the CLI directly:
+
+```bash
+# Analyze a public URL
+uv run python -m src.core.cli analyze \
+  --url https://example.com \
+  --json-output output/example_report.json \
+  --md-output output/example_report.md \
+  --html-output output/example_report.html
+
+# Analyze a local JSON fixture
+uv run python -m src.core.cli analyze \
+  --input examples/sample_ios_output.json \
+  --app-id com.example.legacyapp \
+  --json-output output/modernization_report.json \
+  --md-output output/modernization_report.md \
+  --html-output output/modernization_report.html
+```
+
+See [examples/](examples/) for checked-in report examples (JSON, Markdown, and HTML).
 
 ## How It Works
 
@@ -44,7 +66,7 @@ Input (JSON or URL)
   -> Deduplication into ordered clusters
   -> Scoring (complexity, reusability, accessibility risk, migration risk)
   -> Standards-backed recommendations and roadmap
-  -> Scrubbed JSON + Markdown report output
+  -> Scrubbed JSON + Markdown + interactive HTML report output
 ```
 
 The analysis pipeline is fully deterministic: no LLM inference, no non-deterministic scoring, and no network calls during analysis itself.
@@ -76,12 +98,16 @@ See [docs/APP_SCOPE.md](docs/APP_SCOPE.md) for the current implementation bounda
 ## Development Setup
 
 ```bash
-# Python + web dependencies
-uv sync --dev
-.venv/bin/python -m playwright install chromium
-pnpm --dir web install
+make bootstrap          # install Python + web dependencies
+make proof              # run all 6 proof gates
+make analyze            # run sample analysis to output/
+make lint               # ruff + black check
+make format             # auto-fix formatting
+```
 
-# Proof gates
+The individual proof gates (also run by `make proof` and CI):
+
+```bash
 .venv/bin/python -m pytest -q
 .venv/bin/python -m tests.runner
 .venv/bin/ruff check src tests agent
@@ -90,15 +116,6 @@ pnpm --dir web lint
 pnpm --dir web test
 ```
 
-Or use the Makefile:
-
-```bash
-make bootstrap
-make test
-make lint
-make analyze
-```
-
 ## Architecture
 
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full architecture document.
@@ -108,7 +125,7 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full architecture docum
 | CLI | `src/core/cli.py` | Primary analysis command |
 | Web collector | `src/collectors/web_dom_adapter.py` | Playwright ARIA snapshot collection |
 | Report engine | `src/core/report_generator.py` | Validation, scoring, recommendations, output |
-| API | `src/api/app.py` | `POST /analyze` with API key auth |
+| API | `src/api/wsgi.py` | `POST /analyze` with API key auth |
 | Scrubber | `src/scrubber/pii_scrubber.py` | PII removal preserving stable identifiers |
 | Blueprint (exploratory) | `src/demo/run_raid_visualizer.py` | SVG blueprint from accessibility trees |
 
@@ -127,9 +144,9 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full architecture docum
 
 Real-world analysis outputs from public websites:
 
-- [python.org homepage report](examples/python_org_homepage_report.md)
-- [MDN homepage report](examples/mdn_homepage_report.md)
-- [web.dev homepage report](examples/web_dev_homepage_report.md)
+- python.org: [Markdown](examples/python_org_homepage_report.md) · [JSON](examples/python_org_homepage_report.json) · [HTML](examples/python_org_homepage_report.html)
+- MDN: [Markdown](examples/mdn_homepage_report.md) · [JSON](examples/mdn_homepage_report.json)
+- web.dev: [Markdown](examples/web_dev_homepage_report.md) · [JSON](examples/web_dev_homepage_report.json)
 
 ## Legal
 

docs/BUILD_SHEET.md

@@ -32,12 +32,14 @@ Accessibility-like tree -> construction graph -> deterministic SVG blueprint ->
 - Date: 2026-03-27
 - Status: Passed
 - Evidence:
-  - `.venv/bin/python -m pytest -q` -> `137 passed in 0.41s`
-  - `.venv/bin/python -m tests.runner` -> `137 passed, 0 failed`
+  - `.venv/bin/python -m pytest -q` -> `138 passed in 0.41s`
+  - `.venv/bin/python -m tests.runner` -> `138 passed, 0 failed`
   - `.venv/bin/ruff check src tests agent` -> `All checks passed!`
   - `.venv/bin/python -m black --check src tests agent` -> `84 files would be left unchanged.`
   - `pnpm --dir web lint` -> `RADE web shell lint passed`
-  - `pnpm --dir web test` -> `RADE web shell smoke test passed against http://127.0.0.1:56187`
+  - `pnpm --dir web test` -> `RADE web shell smoke test passed against http://127.0.0.1:56432`
+  - `make proof` -> `All proof gates passed.`
+  - `make analyze` -> produces `output/modernization_report.{json,md,html}`
 
 ### Milestone: Three real-world fixture pack
 
@@ -97,10 +99,11 @@ The ignored `rade-repo/` subtree remains outside canonical repo truth and should
 - 2026-03-22 - Implement Playwright-backed `--url` collection with ARIA snapshot parsing, semantic DOM fallback, agent-shell forwarding, and real CLI proof against `https://example.com`. Full gates pass with 122 pytest cases and 122 custom-runner cases.
 - 2026-03-26 - public repo alignment: created `buildrr89/rade-engine`, switched repository posture to AGPL-3.0, updated public metadata/output wording, and re-generated checked-in proof artifacts to match the new public alpha story.
 - 2026-03-27 - interactive HTML report: `render_html_report()` produces self-contained HTML with score bars, expandable findings/recommendations, category filters, and priority badges. `--html-output` on CLI and agent CLI. Golden fixture and 15 new tests. 137 total tests passing.
+- 2026-03-27 - public alpha onboarding: improved README quickstart (Makefile-first, multiline commands, HTML output), expanded CONTRIBUTING with prerequisites/quickstart/formatting/where-to-start, added `make proof` target running all 6 gates via `.venv/bin/python`, added `--html-output` to Makefile analyze and CI workflow, added checked-in HTML example for python.org, fixed README API entry point to wsgi.py. 138 total tests passing.
 
 ## Next immediate action
 
-Build slice #16: public alpha onboarding (tighten contributor experience).
+Build slice #17: GitHub Action for CI/CD integration.
 
 ## Stop conditions
 

docs/NEXT_EXECUTION_BACKLOG.md

@@ -84,14 +84,12 @@
 - Status: implemented 2026-03-27
 - Result: `render_html_report()` in `src/core/report_generator.py` produces a self-contained HTML report with score-bar visualizations, expandable finding and recommendation cards, category filter buttons, priority badges, and responsive layout. `--html-output` flag added to CLI (`src/core/cli.py`) and agent CLI (`agent/cli.py`). `write_report()` and `analyze_file()` accept `html_output`. Golden fixture at `tests/golden/sample_modernization_report.html`. 14 new tests in `tests/test_html_report.py` plus 1 golden contract test in `tests/test_report_generator.py`. 137 total tests passing.
 
-## Backlog
-
 ### 16. Public alpha onboarding
 
-- Risk reduced: repository approachability (proof exists, but public readers still need a cleaner starting path)
-- Scope: tighten contributor onboarding, sample commands, checked-in examples, and repo-facing docs so a new reviewer can understand the proof slice quickly
-- Acceptance: a first-time reader can bootstrap the repo, run the proof commands, and understand what is implemented vs deferred without outside context
-- Does NOT include: hosted signup flows or billing
+- Status: implemented 2026-03-27
+- Result: README refactored with Makefile-first quickstart, multiline CLI commands, HTML output coverage, and corrected API entry point (`wsgi.py`). CONTRIBUTING expanded with prerequisites, clone-to-proof quickstart, formatting instructions, and where-to-start guidance. Makefile gains `make proof` target (all 6 gates via `.venv/bin/python`), `--html-output` in `make analyze`, and `*.html` in `make clean`. CI workflow updated to produce HTML output. Checked-in HTML example at `examples/python_org_homepage_report.html` with contract test. Examples section in README now links all three output formats. 138 total tests passing.
+
+## Backlog
 
 ### 17. GitHub Action