docs: spec 006 interactive learning paths

docs/specs/006-learning-paths/plan.md

@@ -0,0 +1,41 @@
+# 006 — Plan
+
+## Data
+`_data/<lang>/learning-paths/<slug>.yaml`:
+```yaml
+title: Frontend development
+summary: From HTML and CSS to a component framework and testing.
+subcategory: development/frontend-development
+level: beginner
+source: ipl
+stages:
+  - title: Foundations
+    steps:
+      - title: How the web works
+        summary: Requests, responses, browsers and URLs.
+        resources: [https://developer.mozilla.org/...]
+see_also:
+  - name: Frontend Developer Roadmap (roadmap.sh)
+    url: https://roadmap.sh/frontend
+```
+
+## Generation
+`_plugins/learning_paths.rb` (a Jekyll Generator) creates one page per path and one index page per language, using
+`_layouts/learning-path.html`. It resolves each step URL to its curated entry (name, description, access); an unknown
+URL fails the build in development and test.
+
+## Interaction
+`assets/js/learning-path.js` (vanilla, no dependencies), loaded only on path pages:
+- `<details>` per step, so it works without JS;
+- checkboxes stored under `ipl:path:<lang>:<slug>`, with a progress bar that has `aria-valuenow`;
+- a polite live region that announces progress.
+
+## Authoring
+Paths are drafted by agents from IPL's own data: the subcategory's sections and its curated resources. The prompt
+forbids consulting external roadmaps. Claude reviews order, wording and resources, and native-language drafts are
+written for pt-BR.
+
+## Tests
+- `test/learning_paths_test.rb`: schema, the resource URLs exist, `source: ipl`, both languages present.
+- Build test: the pages render and the subcategory page lists its paths.
+- e2e: progress persists across reloads; axe passes.

docs/specs/006-learning-paths/spec.md

@@ -0,0 +1,39 @@
+# 006 — Interactive learning paths
+
+Status: draft · Depends on: 002 (curated resources)
+
+## Why
+Readers ask "where do I start, and what comes next?". IPL already has thousands of curated resources per topic but no
+order through them. A learning path turns a topic into ordered steps, each backed by IPL's own resources, and lets
+readers mark progress.
+
+## What
+1. **Paths as data.** One file per path: `_data/<lang>/learning-paths/<slug>.yaml` with `title`, `summary`,
+   `subcategory` (where it is listed), `level` (beginner, intermediate or advanced), `steps`, and optional `see_also`.
+2. **Steps.** Each step has a `title`, a short `summary` written for IPL, 2–5 `resources` (URLs that already exist in
+   IPL's curated data), and optional `optional: true`. Steps may group into `stages`.
+3. **Pages.** `/<lang>/learning-paths/` lists every path. `/<lang>/learning-paths/<slug>/` shows one path:
+   - stages and steps in order, expandable;
+   - the resources of each step, linking to IPL's entries;
+   - a progress checkbox per step and a progress bar, kept in the reader's browser (localStorage, no account);
+   - links to related paths and to external roadmaps listed under `see_also`.
+4. **Discoverability.** Subcategory pages show their paths above the curated resources. Search indexes path and step
+   titles.
+5. **Languages.** en-US and pt-BR, with steps written natively in each language.
+
+## Original content and credit
+Paths are authored for IPL from IPL's taxonomy and curated resources. They are not copied, translated or adapted
+from roadmap.sh or any other roadmap: that content is licensed for personal use only. External roadmaps appear only
+as links under `see_also`, credited by name.
+
+## Acceptance criteria
+- [ ] At least 12 paths per language at launch, covering the most visited development and computing subcategories.
+- [ ] Every step resource URL exists in IPL's curated data (test).
+- [ ] Without JavaScript, the path is a readable ordered list. With JavaScript, steps expand and progress persists
+      across reloads.
+- [ ] Keyboard and screen-reader accessible: checkboxes are labelled and progress is announced. axe reports no
+      serious or critical issues.
+- [ ] No content copied from external roadmaps. Each path records its authorship in `source: ipl`.
+
+## Out of scope
+Accounts, server-side progress, quizzes, certificates, graphical node maps.

docs/specs/006-learning-paths/tasks.md

@@ -0,0 +1,9 @@
+# 006 — Tasks
+
+- [ ] T1 Data schema and test (`test/learning_paths_test.rb`)
+- [ ] T2 Generator, layout and index page (en-US, pt-BR)
+- [ ] T3 Interaction script: details, progress, live region; no-JS fallback
+- [ ] T4 Subcategory pages list their paths; search indexes paths
+- [ ] T5 Author 12 paths per language from IPL data (frontend, backend, Python, JavaScript, data analysis, machine
+       learning, DevOps, cybersecurity, databases, UX, mobile, computer science), with reviews
+- [ ] T6 e2e and axe checks