docs: 0.3.0 adoption roadmap + contributor guide

CONTRIBUTING.md

@@ -1,16 +1,46 @@
 # Contributing
 
+Pylings is actively developed and **open to contributors** — beginners welcome.
+The fastest way in is a [`good first issue`](https://github.com/abhiksark/pylings/issues?q=is%3Aopen+label%3A%22good+first+issue%22).
+
+## Where the work is
+
+- **[0.3.0 roadmap](docs/roadmap/0.3.0.md)** — the current focus (wider adoption
+  for beginners). Each roadmap issue is written to be picked up cold: it has
+  context, scope, the exact files to touch, and how to verify.
+- Browse open issues by label: [`good first issue`](https://github.com/abhiksark/pylings/issues?q=is%3Aopen+label%3A%22good+first+issue%22),
+  [`help wanted`](https://github.com/abhiksark/pylings/issues?q=is%3Aopen+label%3A%22help+wanted%22).
+
+## Claiming an issue
+
+1. Comment on the issue to claim it (e.g. "I'd like to take this"). This avoids
+   two people doing the same work.
+2. Ask any questions right on the issue — happy to clarify scope.
+3. Open a PR that references the issue (`Closes #NN`).
+
+No need to wait for a formal assignment; claiming by comment is enough.
+
 ## Development Setup
 
 ```bash
-pip install -e ".[dev]"
+git clone git@github.com:abhiksark/pylings.git
+cd pylings
+pip install -e ".[dev]"   # or: uv pip install -e ".[dev]"
 python -m pytest -q
 ```
 
+Supported Python: 3.9+.
+
 ## Curriculum Changes
 
-Update `info.toml`, `exercises/`, `checks/`, and `solutions/` together. Exercise and check paths must mirror each other, and every exercise must have a passing reference solution.
+Update `info.toml`, `exercises/`, `checks/`, and `solutions/` together. Exercise
+and check paths must mirror each other, and **every exercise must have a passing
+reference solution** (`tests/integration/test_solution_verify.py` enforces this).
 
 ## Pull Requests
 
-Use focused branches named `feature/<name>` or `fix/<name>`. Include a short description, test output, and screenshots for TUI changes.
+- Use focused branches named `feature/<name>` or `fix/<name>`.
+- Reference the issue you're closing (`Closes #NN`).
+- Include a short description, test output (`python -m pytest -q`), and
+  screenshots/GIFs for TUI changes.
+- Keep PRs scoped to one issue where possible.

Readme.md

@@ -167,6 +167,14 @@ When adding curriculum, update `exercises/`, `checks/`, and `info.toml`
 together. Keep exercise and check filenames mirrored, for example
 `exercises/lists/lists3.py` and `checks/lists/lists3.py`.
 
+## Contributing
+
+Pylings is actively developed and welcomes contributors — beginners included.
+The current focus is the [0.3.0 roadmap](docs/roadmap/0.3.0.md) (wider adoption),
+and every roadmap issue is written to be picked up cold. Start with a
+[`good first issue`](https://github.com/abhiksark/pylings/issues?q=is%3Aopen+label%3A%22good+first+issue%22),
+comment to claim it, and see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Release Flow
 
 Pylings uses Semantic Versioning:

docs/roadmap/0.3.0.md

@@ -0,0 +1,58 @@
+# Pylings 0.3.0 Roadmap — Wider Adoption
+
+**Theme:** make pylings easy to *find*, *install*, and *start* — for beginners
+learning Python. Terminal-native, focused release (no web/no-install bet this
+cycle — that's a possible 0.4.0).
+
+**North star:** real first-time users get from "discovered pylings" to "doing
+exercise 1" with as little friction as possible.
+
+Everything below is tracked under the
+[0.3.0 milestone](https://github.com/abhiksark/pylings/milestone/1). Issues are
+written to be picked up cold — each has context, scope, exact files, and how to
+verify. **Want to help? Comment to claim an issue** (see
+[CONTRIBUTING.md](../../CONTRIBUTING.md)). Many are labelled
+[`good first issue`](https://github.com/abhiksark/pylings/issues?q=is%3Aopen+label%3A%22good+first+issue%22).
+
+## ① Discovery — be found
+| Issue | What | Labels |
+|---|---|---|
+| [#5](https://github.com/abhiksark/pylings/issues/5) | Update README install & status for the live PyPI release | docs · good first issue |
+| [#6](https://github.com/abhiksark/pylings/issues/6) | Modernize & fix README badges (dynamic PyPI, Python 3.9+, CI) | docs · good first issue |
+| [#7](https://github.com/abhiksark/pylings/issues/7) | Strengthen README hero / above-the-fold "try it now" | docs · good first issue |
+| [#8](https://github.com/abhiksark/pylings/issues/8) | Submit to awesome-python | docs · good first issue · help wanted |
+| [#9](https://github.com/abhiksark/pylings/issues/9) | Submit to awesome-cli-apps / awesome-tuis | docs · good first issue · help wanted |
+| [#10](https://github.com/abhiksark/pylings/issues/10) | Add to the Rustlings third-party exercises list | docs · good first issue · help wanted |
+| [#11](https://github.com/abhiksark/pylings/issues/11) | Draft a launch announcement (Show HN / r/learnpython) | docs · help wanted |
+| [#12](https://github.com/abhiksark/pylings/issues/12) | Refresh the demo GIF for the 0.2.0 flow | docs · good first issue |
+
+## ② First-run UX — flatten the cliff
+| Issue | What | Labels |
+|---|---|---|
+| [#13](https://github.com/abhiksark/pylings/issues/13) | `pylings` with no workspace should auto-init instead of erroring | enhancement · good first issue |
+| [#14](https://github.com/abhiksark/pylings/issues/14) | Add a first-launch welcome/onboarding screen | enhancement · help wanted |
+
+## ③ Motivation & retention
+| Issue | What | Labels |
+|---|---|---|
+| [#15](https://github.com/abhiksark/pylings/issues/15) | Show overall curriculum progress in the TUI | enhancement · good first issue |
+| [#16](https://github.com/abhiksark/pylings/issues/16) | Add an all-exercises-complete celebration screen | enhancement · good first issue |
+
+## ④ Curriculum (beginner ramp)
+| Issue | What | Labels |
+|---|---|---|
+| [#17](https://github.com/abhiksark/pylings/issues/17) | Gentle-ramp the first exercises of each topic | docs · help wanted |
+
+## Out of scope for 0.3.0
+- Web / no-install (Pyodide) playground — candidate for 0.4.0.
+- Reliability/hardening work (`pylings doctor`, real file-watching) — tracked
+  separately in [#4](https://github.com/abhiksark/pylings/issues/4).
+- Full curriculum coverage-gap analysis — see the methodology spec at
+  `docs/superpowers/specs/2026-06-02-gap-audit-design.md`. Issue #17 only smooths
+  the *early ramp* of existing topics.
+
+## Definition of done for the release
+- Install paths in the README all work and point at PyPI.
+- A newcomer can run `pylings` and reach exercise 1 without reading docs.
+- Overall progress is visible; finishing the curriculum has a payoff moment.
+- pylings is listed in at least one high-traffic discovery source.

docs/superpowers/specs/2026-06-02-gap-audit-design.md

@@ -0,0 +1,148 @@
+# Pylings Gap-Audit — Design Spec
+
+- **Date:** 2026-06-02
+- **Status:** Approved for planning
+- **Scope:** Curriculum gaps + Product/feature gaps
+- **Approach:** Hybrid (C) — quantified curriculum, checklist product
+
+## Goal
+
+Build a **reusable gap-audit playbook** and **run it once** to produce a first
+gap-analysis report. The audit covers two domains:
+
+1. **Curriculum gaps** — judged against (a) *popular learning paths* (what
+   courses, bootcamps, and working Python devs actually cover) and (b)
+   *internal consistency* (per-topic counts, difficulty curve, concept
+   coverage, dead spots).
+2. **Product/feature gaps** — what a learner can't do yet, judged against
+   *Rustlings* (pylings is explicitly Rustlings-style) plus common TUI
+   learning-tool UX conventions.
+
+Explicitly **out of scope**: code-quality/test gaps and adoption/growth gaps.
+
+## Deliverables
+
+| Artifact | Purpose | Re-run cadence |
+|---|---|---|
+| `scripts/curriculum_audit.py` | Instrumentation: extracts the coverage/difficulty matrix and computes curriculum gaps. Stdlib-only, no new dependencies. | Every release |
+| `docs/refs/expected-concepts.toml` | Versioned external baseline: per-topic expected concepts with detection hints. | Edited as the baseline evolves |
+| `docs/gap-audit-playbook.md` | The reusable methodology: how to run the script, update the baseline, the internal-consistency rules, the product checklist template, and the scoring rubric. | Read each audit |
+| `docs/gap-analysis-2026-06.md` | The first run's findings. | One per audit, dated |
+
+## Part 1 — Curriculum (quantified, re-runnable)
+
+### 1a. Extraction (`scripts/curriculum_audit.py`)
+
+Walks `exercises/`, `checks/`, `solutions/_answers.py`, and `info.toml`.
+Per exercise it captures:
+
+- **Identity:** topic, exercise name, order index (from `info.toml`).
+- **Goal text:** the leading `# ...` header comment block.
+- **Difficulty signals:** exercise LOC (excluding comments), `???`-blank count,
+  check LOC, reference-answer LOC.
+
+Emits a **coverage matrix** in two formats:
+- `docs/refs/coverage-matrix.json` (machine-readable, for diffing across runs)
+- A markdown table embedded in the report.
+
+### 1b. Expected-concepts reference (`docs/refs/expected-concepts.toml`)
+
+Hand-built, versioned, per-topic list of concepts a popular-learning-path
+curriculum would cover. Each concept carries **detection hints** (keywords / API
+names / operators). Example:
+
+```toml
+[strings]
+f_string_format = { hints = [":>", ":.2f", "!r"] }
+walrus          = { hints = [":="] }
+
+[functions]
+keyword_only_args = { hints = ["*,"] }
+```
+
+Sourced from common courses/bootcamps (e.g. RealPython-style tracks) and
+job-relevance, not from exhaustive language coverage.
+
+### 1c. Gap computation (in-script)
+
+- **Coverage gaps:** for each expected concept, scan the combined
+  exercise + reference-answer text of that topic for any detection hint. No hint
+  found → `MISSING` gap. (Concept detection method: **keyword/API scan**, see
+  "Concept detection" below.)
+- **Internal-consistency flags** (no external baseline needed):
+  - *Count variance:* topics whose exercise count deviates sharply from the
+    median (flag low and high outliers).
+  - *Difficulty-curve anomalies:* within a topic, exercises ordered such that a
+    high-difficulty-signal exercise appears early, or the curve is flat, or
+    there's a large jump between adjacent exercises.
+  - *Ordering smells:* concepts whose detection hint first appears in a later
+    topic than where it's conceptually prerequisite (best-effort heuristic).
+
+### Concept detection method (decided)
+
+**Keyword/API scan now; explicit tags deferred.** v1 uses the detection hints in
+`expected-concepts.toml` to scan exercise+answer text — zero curriculum changes,
+fully automated, accepted as slightly fuzzy. The playbook documents that if
+false positives/negatives prove material, explicit `# concepts: a, b` lines can
+be added per topic incrementally later. The 292-file tagging cost is **not** paid
+in this audit.
+
+## Part 2 — Product/feature (structured checklist)
+
+A capability checklist organized by area:
+
+- Onboarding / install
+- Navigation (move between exercises/topics, jump, search)
+- Feedback loop (watch mode, verify, re-run on save)
+- Hints (presence, escalation levels)
+- Progress / state (resume, completion %, streak)
+- Help / docs (in-app docs, keybinding help)
+- Accessibility (color, screen-reader, no-color/CI mode)
+- Configurability (paths, theme, editor integration)
+
+Each item is scored **present / partial / missing**, with the baseline
+reference (Rustlings has it, or a UX convention) and a note. First run: read
+`pylings/cli.py`, `pylings/app.py`, `pylings/screens/`, `pylings/widgets/`,
+compare to Rustlings' feature set, and fill the checklist.
+
+## Part 3 — Report format (`docs/gap-analysis-2026-06.md`)
+
+1. **Summary** — headline counts and the top findings.
+2. **Curriculum gaps** — missing-concept table (topic × concept × severity ×
+   effort) followed by internal-consistency findings.
+3. **Product gaps** — the filled checklist, then prioritized findings.
+4. **Ranked candidate shortlist for v0.3** — top findings across both domains,
+   ranked. This is a *candidate* list to inform a roadmap, **not** a commitment.
+
+**Scoring rubric (applied to every finding):**
+- **Severity:** High (core skill / common learner blocker) · Medium · Low
+  (nice-to-have / rare).
+- **Effort:** S (≤1 day / few exercises) · M · L (multi-day / new subsystem).
+
+## Playbook contents (`docs/gap-audit-playbook.md`)
+
+- How to run `scripts/curriculum_audit.py` and read its output.
+- How to update `expected-concepts.toml` as the baseline evolves.
+- The internal-consistency rules and their thresholds.
+- The blank product capability checklist (copy per audit).
+- The severity/effort rubric and how to write the dated report.
+- Cadence: run each release; diff `coverage-matrix.json` against the prior run
+  to catch regressions.
+
+## Components and boundaries
+
+- `curriculum_audit.py` is a self-contained CLI: input = repo curriculum dirs +
+  `expected-concepts.toml`; output = `coverage-matrix.json` + a printed markdown
+  report fragment. It performs **no** writes to curriculum files. Testable in
+  isolation against `tests/fixtures/` curricula.
+- The reference (`expected-concepts.toml`) and the report are **data/docs**, not
+  code — they change without touching the script.
+- The product checklist is a human process documented in the playbook; it has no
+  code dependency on the script.
+
+## Non-goals
+
+- No changes to curriculum exercise files in this audit (tagging deferred).
+- No new runtime dependencies; script is stdlib-only.
+- No automated product-gap scoring (kept qualitative on purpose).
+- The report ranks candidates; it does not decide or implement the v0.3 roadmap.