wip

Author: GeigerJ2

docs/source/_static/aiida-custom.css

@@ -227,3 +227,10 @@ div.highlight-console div.highlight {
 .bd-sidebar-primary {
     overflow-y: hidden;
 }
+
+/* Tutorial module header badges (reading time + difficulty): a bit larger than
+   the default sphinx-design badge so they read at a glance under the title. */
+.sd-badge {
+    font-size: 0.9rem;
+    padding: 0.4em 0.7em;
+}

docs/source/tutorials/_notes/2026-06-02-gm-feedback-plan.md

@@ -198,8 +198,9 @@ Cross-references the issue IDs above. `X*` = the whole cross-cutting checklist.
 - Shorter extras access: `node.base.extras.all.items()` to something like `node.extras.items()` (A2).
 - Unified run/submit for WorkGraph: `engine.run(wg)` / `engine.submit(wg)` instead of instance methods (api-discrepancies item 1; PR open).
 - `verdi process dump` support for WorkGraph ([#7196](https://github.com/aiidateam/aiida-core/pull/7196)).
-- Public accessor for gathered `Map` outputs instead of the private `._value` unwrap (M3:490 note).
+- Public accessor for gathered `Map`/dynamic-namespace outputs instead of the private `._value` unwrap. Verified: public `.value` raises `AttributeError` on a namespace socket (`TaskSocketNamespace.__getattr__` treats `.value` as a sub-socket lookup), so `._value` is genuinely the only current way. Not tracked as its own upstream issue. Adjacent: node-graph [#155](https://github.com/scinode/node-graph/issues/155) (dynamic-namespace output can't be iterated in a graph body), [#156](https://github.com/scinode/node-graph/issues/156); aiida-workgraph [#786](https://github.com/aiidateam/aiida-workgraph/issues/786) (`.value` inconsistency), [#779](https://github.com/aiidateam/aiida-workgraph/issues/779) (None entries dropped). Worth a focused issue on node-graph.
 - Confirm aiida-shell accepts plain relative path strings, so tutorials can drop `Path(...).resolve()` (U1).
+- (aiida-workgraph, not aiida-core) Fold `shelljob()` into `task()` dispatch, e.g. `task(ShellJob, outputs=[...])`; only ShellJob's dynamic output namespace (`spec.outputs.dynamic=True`) needs manual naming, everything else comes from `from_aiida_process`. Also resolves the `shelljob`/`ShellJob` case-only name clash. Draft issue: `_notes/aiida-workgraph-shelljob-task-issue.md`.
 - New QueryBuilder filter syntax is already shipped (A1), so it is an adopt-now item, not a wishlist item.
 
 ---

docs/source/tutorials/_notes/HANDOFF.md

@@ -7,6 +7,54 @@ orphan: true
 Resume point after context compaction.
 Full decision log + JG/CC threads live in `2026-06-02-gm-feedback-plan.md`; this is the tight "where we are, what's next" summary.
 
+---
+
+## LATEST ROUND: module3a deep content pass (resume here, next = module3b)
+
+We did a full line-by-line content/wording pass on **module3a** with JG, driven by `_notes/reword-module3a.md` (items 1-9 + a "mental model" block, **all resolved**, CC notes in the doc). Plus many live ad-hoc edits. **module3a is content-complete pending a real build-verify.**
+
+### Durable conventions established this round (APPLY THESE TO 3b AND BEYOND)
+
+- **No "handle" wording.** Calling a task returns its **output sockets** (a `TaskSocketNamespace`), not a "handle". Say "output sockets" / "the task's outputs".
+- **Avoid private (`._foo`) and dunder (`type(x).__name__`) in *shown* code**, where a clean public/domain accessor exists:
+  - process-node type → `node.process_label` (e.g. `WorkGraph<gray_scott_pipeline>`), NOT `type(x).__name__`.
+  - socket-name listing → `wg.get_input_names()` / `wg.get_output_names()`, NOT `._get_keys()`.
+  - prefer readable names + list slices over `next(gen)` (`[child for child in ... ][0]`, not `next(c for c in ...)`).
+  - **Exceptions that MUST stay (no public alternative, verified):** (1) gathered `Map`/dynamic-namespace outputs are read via private `._value` (public `.value` raises `AttributeError`, node-graph bug, issue drafted) — module3b:243,356 and module6b:258,259,272 keep `._value` with their explanatory comments; (2) module1:211 uses `type(output_node).__name__` for a *data* node's class (data nodes have no `process_label`; kept, it's standard introspection).
+- **`orm.Dict` inputs kept explicit** in build calls (we verified plain dict auto-converts, but chose to keep `orm.Dict(...)` — do NOT switch to plain dicts). `parameters=orm.Dict(BASE_PARAMS)` in 3b's build calls stays.
+  - (module3a specifically ended up passing `parameters=BASE_PARAMS` plain in its two `.build()` calls + a bullet teaching auto-conversion; that was a module3a-local choice. For 3b keep whatever is already there unless JG says otherwise.)
+- **blueprint → build → run framing:** the `@task.graph` function (`gray_scott_pipeline`) is the *blueprint*; `.build(...)` makes it *concrete* (a runnable `WorkGraph`); `.run()`/`.submit()` executes. Don't call the built graph the "blueprint".
+- **Don't name AiiDA link types** (`CALL_CALC`, `RETURN`, `INPUT_WORK`) in prose, they were never taught; say it plainly ("linked to each child it called and back to the outputs it returned"). module1:164's forward-promise of those names was removed.
+- **Reading-time + difficulty badges** are on every module H1: `{bdg-secondary}⏱️ ~N min read` `{bdg-<color>}<Tier>` (Beginner=success/green, Intermediate=primary/blue, Advanced=warning/amber). `.sd-badge` is bumped in `_static/aiida-custom.css`. JG will tune numbers.
+- **`shelljob()`**: describe as "a convenience that handles the actual `ShellJob` setup for you behind the scenes and adds it to the active graph" — a light parenthetical, NOT a big note.
+- General wording aesthetic JG applied relentlessly: cut repetition (don't restate the same idea twice), plain English over jargon, no forward-refs to things introduced later, split overlong bullets, one point per sentence.
+
+### `include/` state (done earlier this session)
+
+`tasks.py` split into: `tasks.py` (core: `prepare_input`, `parse_output`, `ParseOutputs`) + `tasks_module_3b.py` (`make_transition_plot`) + `tasks_module_6.py` (`fft_peak_wavelength`, `bump_n_steps`, `identify_transition_region`). All `.md` imports / `{literalinclude}` / `{download}` repointed. `workflows.py`'s `gray_scott_pipeline` docstring trimmed to one line.
+
+### Cross-cutting propagations DONE across all modules
+
+- All install notes use `uv pip install ...` (not `pip install`).
+- Setup comment collapsed to `# Set up the tutorial's isolated sandbox profile (see Module 1 for details).` in M2/M3a/M3b/M4/M5/M6a/M6b/M7 (M1 keeps the full explanation, it's where setup is taught).
+- `conf.py` `nb_execution_mode` was toggled to `'off'` during the prose sweep and **REVERTED** — execution is back ON (default `auto`). Rebuilds re-run notebooks.
+
+### New draft issues written this round (in `_notes/`, as JG, ready to post; NOT posted)
+
+- `aiida-workgraph-shelljob-task-issue.md` — fold `shelljob()` into `task(ShellJob, outputs=...)`; only ShellJob's dynamic-output namespace isn't auto-discoverable.
+- `node-graph-namespace-value-issue.md` — public accessor for namespace socket `value` (currently only private `._value`; pure-node-graph MWE verified). The wishlist in the plan doc has the `._value` finding + adjacent upstream refs (node-graph #155/#156, aiida-workgraph #786/#779).
+
+### NEXT: module3b
+
+Same treatment as 3a. 3b covers `Map` (turning the Module-2 `for`-loop into a parallel workflow) + `make_transition_plot` reduction. Things to watch:
+- Apply all conventions above (esp. no "handle", plain link-type language, blueprint framing, private/dunder rules).
+- 3b's `._value` reads (lines ~243, ~356) STAY (documented exception).
+- 3b already has uv + one-line setup + badge (`~70 min` Intermediate).
+- Work from any GM-feedback items still open for 3b (check the plan doc's per-module worklist).
+- module3a is NOT yet build-verified after this round's edits — a real build of M1→M2→M3a (chained data) should be run at some point to confirm cells execute.
+
+---
+
 ## Where we are
 
 Reworking the new AiiDA tutorials (`docs/source/tutorials/module*.md`) against group-meeting feedback (source: `review/2026-06-02-msd-gm-tutorial.md`).