Skip to content

Handbook + workshop layout/spec (grounded in tool-use survey)

Purpose

Concrete layout and tooling spec for the two surfaces decided in idea-arash-20260507-221835-382557.md:

  • Handbook + blog — projio/docs/handbook/ and projio/docs/blog/ (this repo, mkdocs-material, evergreen).
  • Workshop — /storage2/arash/teaching/agentic-workshop/2026-09/ (new workspace, Quarto, time-boxed; iterations as sibling dirs).

Every chapter and exercise below cites a real artifact from the tool-use survey (result-arash-20260508-tool-use-survey.md) — no hypothetical material. Where the survey flagged an honest gap, the chapter or session inherits that gap rather than papering over it.

A. Two-workspace contract

Aspect Handbook (projio/docs/handbook/) Workshop (teaching/agentic-workshop/2026-09/)
Repo projio new dataset teaching/agentic-workshop/
Builder mkdocs-material (existing) Quarto project (multi-output)
Lifecycle evergreen one iteration per directory (2026-09/, 2027-XX/, …)
Cross-link direction handbook chapters link out to projio source paths only workshop materials link into handbook chapters; never duplicate prose
Original-only content concepts, evergreen narrative, primitive references datasets, exercise scaffolds, rubrics, post-mortems, rosters

Rule: if a paragraph is true in 18 months, it belongs in the handbook. If it is tied to the September 2026 cohort or room, it belongs in the workshop dir.

B. Handbook layout

projio/docs/
├── handbook/
│   ├── index.md                      # landing + 1-paragraph "what & why"
│   ├── 00-frame/
│   │   ├── why-interactivity.md      # the 7-paradigm taxonomy translated to research workflow
│   │   ├── workflow-as-object.md     # the "research workflow has no interactive layer" gap argument
│   │   └── single-author-fragility.md # honest motivation per Quantomatic note
│   ├── 10-foundations/
│   │   ├── bids-in-practice.md       # study layouts; raw/ + derivatives/<flow>/
│   │   ├── datalad-subdatasets.md    # code/lib/ + derivatives/ as siblings
│   │   └── snakemake-with-bids.md    # snakebids vs pipeio.adapters.bids.BidsPaths
│   ├── 20-projio/
│   │   ├── repo-as-knowledge.md      # search-before-creation workflow
│   │   ├── codio-and-indexio.md      # external knowledge layer; mirror + index pattern
│   │   ├── notio-as-log.md           # docs/log/ structure; agent-activity trail
│   │   ├── biblio.md                 # srcbib → merged → compiled pipeline
│   │   └── figio.md                  # FigureSpec — and honest "mostly aspirational" note
│   ├── 30-pipelines/
│   │   ├── flows-and-mods.md         # ontology recap
│   │   ├── config-driven-pipelines.md # the lfp_extrema registry-extension pattern
│   │   ├── small-operators.md        # cogpy primitive-catalog composition
│   │   ├── manifests-as-contracts.md # cross-flow manifest.yml + BidsPaths
│   │   ├── notebooks-and-promotion.md # explore/demo split + nb_promote → mod
│   │   └── from-paper-to-pipeline.md # gecog factor_analysis (Garcia-Cortadella 2024)
│   ├── 40-agentic/
│   │   ├── working-with-the-agent.md # the gecog mlclassifier iteration arc as case study
│   │   ├── mcp-and-permissions.md    # .claude/settings.json + .mcp.json patterns
│   │   ├── skills.md                 # SKILL.md format + when to write one
│   │   └── safety-and-cost.md        # routing, model selection, dispatch patterns
│   ├── 50-orchestration/
│   │   ├── worklog-overview.md       # registry, captures, queue, goals (NB: keep lab/public docs free of personal-hub framing)
│   │   ├── goals-and-critical-path.md
│   │   └── cross-project-dispatch.md
│   ├── 60-publication/
│   │   ├── deliverables-dir.md       # docs/deliverables/ as publication surface
│   │   ├── reports-with-quarto.md    # link to existing how-to/build-a-report
│   │   ├── presentations.md          # present_* tools
│   │   └── manuscripts.md            # explicit "mature spec, not yet exercised"
│   └── 99-honest-gaps.md             # consolidates the 8 gaps from survey §"Honest gaps"
└── blog/
    ├── index.md                      # reverse-chronological post list
    └── posts/                        # YYYY/MM-slug.md (Simon-Willison-style cadence)

Navigation: patch mkdocs.yml with a top-level Handbook and Blog section. The existing tutorials/, how-to/, explanation/, reference/ trees stay as Diátaxis surfaces and are linked from handbook chapters where appropriate (e.g. 60-publication/reports-with-quarto.md → existing how-to/build-a-report.md). Do not migrate them into handbook/.

Blog co-residence: same mkdocs-material site; one Observable-style interactive essay per quarter is the bar (per idea note). Blog posts that mature into chapters get linked from index.md, not moved.

C. Workshop layout

Confirms the sketch in the idea note with one addition (scaffolds/ for participant template repos).

teaching/agentic-workshop/
├── README.md                       # iteration scheme + how to fork next year
├── shared/                         # cross-iteration assets
│   ├── datasets/                   # symlinks to teaching-safe sample data
│   ├── slide-templates/            # revealjs theme matching handbook
│   ├── scaffolds/                  # template participant repo (`projio init` output, pre-baked)
│   └── manim/                      # one opening animation, source + render
└── 2026-09/
    ├── _quarto.yml                 # multi-output: website + book + revealjs
    ├── announcement.md             # move from idea-note conversation log
    ├── syllabus.qmd                # learning outcomes, schedule, prereqs
    ├── pre-workshop-setup.qmd      # checklist participants run before day 1
    ├── day-1-foundations/
    │   ├── lecture.qmd             # → revealjs (morning, BIDS+DataLad+Snakemake concepts)
    │   ├── handout.qmd             # → website + book chapter (cross-links to handbook 10-foundations)
    │   └── exercises/              # marimo notebooks; afternoon hands-on
    │       ├── 01-bidsify.py
    │       ├── 02-datalad-create.py
    │       └── 03-snakemake-rule-chain.py
    ├── day-2-agentic/
    │   ├── lecture.qmd
    │   ├── handout.qmd             # links handbook 40-agentic/*
    │   └── exercises/
    │       ├── 01-claude-code-tour.py
    │       ├── 02-mcp-permissions.py
    │       └── 03-iteration-loop.py    # mirrors gecog mlclassifier arc, abridged
    ├── day-3-orchestration/
    │   ├── lecture.qmd
    │   ├── handout.qmd
    │   └── exercises/
    │       ├── 01-projio-init.py
    │       ├── 02-pipeio-flow-new.py
    │       ├── 03-cross-flow-manifest.py
    │       └── 04-worklog-dispatch.py
    ├── day-4-presentations/
    │   ├── rubric.qmd              # day-4 assessment
    │   └── participant-template.qmd
    ├── participants/
    │   ├── roster.yml              # gitignored or kept private branch
    │   └── submissions/
    └── post-mortem.qmd             # written week of, before content fades

Quarto config rationale: one project, three output formats. *.qmd files declare their output via front-matter format:. lecture.qmd → revealjs; handout.qmd → html (website chapter) + pdf (book chapter, via book profile). Marimo exercises stay as .py and are embedded into handouts via Quarto {{< embed >}} shortcodes pointing at exported HTML or marimo export html-wasm artifacts.

D. Survey artifacts → chapters & sessions

This is the load-bearing table. Every entry references a real artifact in the survey; the workshop session number maps to §C above.

# Artifact (project) Handbook chapter Workshop session
1 code/pipelines/lfp_extrema/Snakefile (pixecog) 30-pipelines/config-driven-pipelines.md day-1 PM ex 03 (Snakemake) + day-3 AM lecture
2 brainstate.mlclassifier mod + Apr 29–May 6 result/task arc (gecog) 40-agentic/working-with-the-agent.md day-2 PM ex 03 (iteration loop)
3 factor_analysis flow (gecog) 30-pipelines/from-paper-to-pipeline.md day-3 AM lecture (cross-session aggregation)
4 manifest_assemble + BidsPaths (pixecog) 30-pipelines/manifests-as-contracts.md day-3 AM ex 03
5 cogpy primitive catalog + subtract_template 30-pipelines/small-operators.md day-1 PM intro; day-3 AM mention
6 exploration_analysis flow (msol) 30-pipelines/flows-and-mods.md "this generalizes" sidebar day-3 AM diversity slide
7 docs/log/ notio layout + agent-activity.md (pixecog/gecog) 20-projio/notio-as-log.md day-2 AM intro
8 .projio/codio/mirrors/ + indexio catalog (projio itself) 20-projio/codio-and-indexio.md day-3 AM lecture sidebar
9 TTL-cleaning ieeg → re-BIDS (pixecog lfp_extrema/config.yml bids_dir_ieeg switch) 10-foundations/bids-in-practice.md "when one root isn't enough" day-1 AM advanced sidebar
10 2026-05-02-mlclassifier-cohort.md + figio spec (gecog) 60-publication/deliverables-dir.md + 20-projio/figio.md day-4 rubric anchor + participant template

E. Tooling spec

Tool Surface Use Don't
mkdocs-material handbook + blog all evergreen prose don't migrate to Quarto
Quarto (project, not book) workshop website + book + slides + executable nb in one source don't force the book metaphor
Marimo both workshop hands-on (.py, kernel = project pixi env); handbook explorables via marimo export html-wasm don't depend on a backend for handbook embeds
Manim workshop only one 3–5 min opening animation under shared/manim/ don't try to animate every concept
Observable blog only one interactive essay/quarter don't make handbook chapters require JS

Single-source patterns in the workshop project:

  • day-N-*/handout.qmd is the canonical text; both website and book pull from it.
  • day-N-*/lecture.qmd is slides only; cross-links the handout for participants who want depth.
  • Marimo exercises are referenced from the handout, not duplicated.

Cross-link protocol:

  • Workshop handouts link into handbook chapters via the published URL (https://projio.<domain>/handbook/...), not relative paths — keeps the workshop dataset detachable.
  • Handbook chapters cite source artifacts via repo-relative paths (code/pipelines/lfp_extrema/Snakefile) and mention the project name (pixecog, gecog, …) explicitly. Handbook is sole-author so personal lab context is fine; do not mention worklog as a personal hub in shipped/lab-facing handbook copy (per feedback_worklog_personal.md).

F. Conventions inherited from the survey

Default workshop conventions, picked from where the survey shows multiple choices coexist:

Decision Pick Why (from survey)
Snakemake idiom pipeio.adapters.bids.BidsPaths (used by all 4 study projects) snakebids-only is legacy in cogpy
Runner pixi (used by pixecog/gecog/msol) conda is the projio-and-cogpy outlier
Code tier code/{lib,pipelines,utils,scripts}/ universal across study projects
Notebook backend marimo for workshop exercises (live editing via nb_watch) matches marimo-pair skill; pixecog already uses it
Docs framework (study projects) MkDocs only cogpy is on Sphinx
Project skills introduce as "optional advanced", not baseline 3/5 projects have any
Figio one dissection (gecog May-02 cohort spec); rest is honest "ad-hoc still common" only first-party FigureSpec in the corpus
Manuscript subsystem mention but don't teach as mature manuscript_list returns [] everywhere

G. What gets scaffolded first (concrete next actions)

In order. None of these need user input beyond confirmation.

  1. Provision the workshop dataset: datalad create under /storage2/arash/teaching/agentic-workshop/, add the 2026-09/ directory with _quarto.yml and the day-N skeleton from §C. Move the announcement draft from the idea-note conversation into 2026-09/announcement.md and the Deep Research PDF (per idea-note TODO) into shared/reading/.
  2. Stub the handbook tree under projio/docs/handbook/ with the layout in §B — empty files with H1 titles and a "from survey: artifact X" pointer comment. Patch mkdocs.yml nav. Don't write prose yet.
  3. Wire one canonical example end-to-end before drafting any other chapter: pick artifact #1 (lfp_extrema registry-extension Snakefile) and write both the handbook chapter (30-pipelines/config-driven-pipelines.md) and the workshop session that points at it (day-1 PM ex 03 + day-3 AM lecture excerpt). This validates the cross-link protocol on a real artifact before replicating the pattern across 10 entries.
  4. Then scaffold the remaining day-skeletons and chapter stubs in parallel.

H. Open decisions deferred (explicitly not picked here)

These are workshop-iteration decisions, due before announcement (target: mid-July 2026 per idea note). Not scoped to this spec.

  • Department + room + exact dates.
  • Capacity (8–12 suggested).
  • Hardware/Claude credits policy.
  • Prereq strictness (PhD only? postdocs? PIs?).
  • Day-4 rubric concrete criteria.
  • Final public title (working: The Agentic Research Workflow).
  • Whether projio extracts to its own public repo (Rust-Book pattern) — decision affects whether the handbook ever leaves projio/docs/.

I. What this spec deliberately does not include

  • Per-chapter outlines or prose (premature; do after step G.3 validates the pattern).
  • Per-exercise marimo cell breakdowns (depends on which dataset slice ships in shared/datasets/).
  • The Manim storyboard (one focused session, separate task).
  • Workshop budget / Claude-API cost model.

Method note

  • Read the source idea (idea-arash-20260507-221835-382557.md) and result survey (result-arash-20260508-tool-use-survey.md) end-to-end.
  • Verified docs/handbook/ and docs/blog/ do not yet exist in projio (docs/ currently has Diátaxis split: tutorials/how-to/reference/ explanation/specs + log/deliverables/prompts/pipelines).
  • Verified /storage2/arash/teaching/agentic-workshop/ does not yet exist (the teaching/ parent is a datalad dataset).
  • All cited artifacts already inventoried in the survey — no fresh filesystem scans of the four study projects needed.