feat: improve Learning Console readability

[GwriPennar]

Summary

• surfaces the real-data exact, simulation and hardware results before technical modelling detail;
• improves the GitHub README landing language and explains ordering agreement in plain language;
• opens with why folk tunes provide a useful small, understandable test case;
• tells the learner exactly what to do before revealing the synthetic answer;
• makes the transition from the teaching fixture to public folk-tune data explicit;
• replaces internal experiment-code headings with human research questions while retaining governed IDs as secondary provenance;
• explains R, rho, PUBs and shots before presenting their metrics;
• removes route/version metadata and duplicated lesson framing from Foundations;
• preserves the existing navigation, Glossary data and button-gated Qiskit path.

Read-only review findings

The merged PR #41 baseline was functional and scientifically careful, but still read like a project report in several places. The opening did not explain why folk music was being used; the learner was asked to predict without a concrete instruction; the real-data journey began with EXP-010A; hardware terminology arrived before its meaning; and Foundations exposed route/version metadata plus a duplicate title.

Learner-facing blocks removed or rewritten

• Rewrote the global opening question and introductory paragraph.
• Moved the exact-first/no-advantage statement into the Experiments context.
• Rewrote the Experiments, Foundations and Glossary explainers.
• Replaced Guided experiment with the prediction question Can you spot the hidden split?.
• Clarified what evidence to inspect and that the prediction is mental, not a missing form control.
• Recast post-reveal and technical headings as learner questions.
• Removed the visible EXP-010A opening and the duplicated feature-summary blocks.
• Recast the real-data sequence around discovery, choices, evidence and checking.
• Defined R before ideal and hardware metrics and explained the uniform control.
• Replaced EXP-010D and EXP-011 primary headings with plain-language replication headings; governed IDs remain as captions.
• Defined parameter landscape, rho, PUBs and shots before their results.
• Removed Foundations route/version metadata and made each lesson's relevance explicit.

Change classification

This is a copy-led readability change with small ordering/removal changes. It adds no navigation architecture, custom styling, registry, evidence layer or product feature.

The final amendment moves the choices table, input contract and five-step encoding process into a collapsed How the four-bit model works disclosure after the replicated hardware evidence. It also renames README's Four proof points section to What you can inspect and explains rho as agreement between rankings. No screenshot was added.

Scientific components deliberately frozen

• all registered numerical results and experiment artifacts;
• exact, QAOA and IBM evidence contracts;
• all hardware chart specifications and evidence loaders;
• warning classifications and limitations;
• EXP-005A, EXP-010A, EXP-010C, EXP-010D and EXP-011 governed evidence;
• dependencies, glossary data and Foundation lesson content;
• optional Qiskit execution remains explicitly button-gated.

Validation

• focused Streamlit and hardware presentation tests: 14 passed;
• full pytest: 252 passed;
• Ruff lint: passed;
• Ruff format: passed (151 files checked);
• Build Week release verification: passed;
• public-safety scan: passed;
• experiment, fixture, result and dependency diff: empty;
• git diff --check: passed.

Visual review

• 1280×720: the human question, reason for using folk tunes, synthetic-to-real transition and Reveal action form one clear opening screen;
• 1440×900: Foundations and Glossary remain readable without documentation-like route/version framing;
• 700×900: no horizontal overflow (scrollWidth == clientWidth == 700);
• the real-data journey introduces each evidence layer and technical measure before displaying its metrics;
• warnings remain visible after the associated result and do not obscure the human question.

No IBM service was contacted, no credential was accessed, PR #23 was untouched, and the primary checkout's .gitignore and .claude/ state was preserved.

Review focus

• Does the opening now make the learner's task and the reason for using folk tunes immediately clear?
• Does the synthetic teaching experiment lead naturally into real-data and hardware evidence?
• Are R, rho, PUBs and shots understandable before the metrics appear?
• Do Foundations and Glossary now feel connected to the experiments without becoming a redesign?

Novice README and reproducibility amendment

Head commit: e975c8a932bc9aaa7762b47c20c9103464ff5267

Summary

• rewrites the GitHub landing page from a novice product explanation through launch, data, evidence, Codex/GPT-5.6 boundaries, reproduction, limits and repository map before the retained research archive;
• surfaces First: what is the exact answer? in the real-data journey and presents EXP-010A · compact real-data formulation as secondary provenance;
• fixes release freshness comparison to ignore only software_provenance.python on non-mutating copies;
• allows the standard OPENAI_API_KEY variable name with a placeholder while retaining detection of key-like secret values;
• corrects public-app IBM wording and uses the submission tagline consistently;
• adds no screenshot because both authentic 1440×900 capture attempts timed out in the browser capture layer; no image was fabricated.

Exact amendment files

• README.md
• apps/learning_console/README.md
• apps/learning_console/renderers/compact_experiment.py
• docs/build-week/DEMO-SCRIPT.md
• docs/build-week/JUDGING-GUIDE.md
• docs/build-week/KNOWN-LIMITATIONS.md
• docs/build-week/SUBMISSION-CHECKLIST.md
• scripts/check_public_safety.py
• scripts/verify_build_week_release.py
• tests/build_week/test_release_verification.py
• tests/learning/test_build_week_console.py
• tests/test_no_secrets.py

Diagnosis and fix

The old verifier compared the committed example and runtime-generated envelope directly, making the interpreter version itself a stale-export failure. The new helper deep-copies both payloads and removes only software_provenance.python before comparison. Regression tests prove 3.13.5 versus 3.12.13 passes and a changed scientific result still fails. On locally available Python 3.11.9, two validation tolerances also changed near 10^-15; the verifier correctly continued to fail rather than ignore those scientific fields.

Validation

• focused release, safety, README, Streamlit and hardware tests: 21 passed;
• credential-free non-quantum suite: 238 passed;
• full optional-quantum suite on Python 3.13.5: 257 passed;
• Ruff lint and formatting: passed;
• release verification on Python 3.13.5: passed;
• public-safety scan: passed;
• clean Python 3.11.9 .[learning] install and credential-free Streamlit launch: HTTP 200;
• 700×900 responsive check: no horizontal overflow;
• frozen experiment, result, fixture, example and dependency diff: empty.

Python 3.12 was not installed on this machine, and the request to add a persistent interpreter was denied. The exact 3.12.13 version-only case is covered by regression; an independent clean 3.12 execution remains a review follow-up if required.

All registered evidence and scientific values remain unchanged. No IBM or OpenAI service was contacted, no credential was accessed, PR #23 was untouched, and PR #42 remains draft.