Development History: Workshop on Claude Code and Claude Desktop for Humanities Research

A record of decisions, pivots, and reasoning — not just what exists, but how it came to be.

Sessions 1–16 archived in _history.archive.md (Origins through 2026-03-17, site build and UX polish phase).

Session 17 — 2026-03-17

A seventeenth session (continuing the same day) combined browser-based UX testing of the GitHub Pages site, a responsive-design bug fix discovered during that testing, and the creation of a new document on compartmentalising research project memory for data-heavy work.

Browser UX testing

The GitHub Pages site was tested end-to-end using a headless browser. Key findings: the "Surprise me" button, close button, home-panel split-screen navigation, and document page footer (version + "← Back to map") all functioned correctly. The carousel was verified readable at 120 px height with working dot-navigation and auto-rotation. One layout bug was found and fixed (see below). No JavaScript errors were observed on load. Responsive layouts were captured at 375 px (mobile), 768 px (tablet), 900 px, 1099 px, and 1280 px (desktop).

Responsive header fix: legend separator

The legend separator border was in a max-width: 1100px media query — added in session 16 on the assumption that the legend would only wrap at narrow widths. Browser measurement revealed that the legend wraps to its own row at all viewport widths (total header content is approximately 1460 px; the flex: 1 spacer fills row 1 and the legend naturally becomes row 2 at every size). As a result, at 1280 px desktop the two-row header had no visual separator at all. Fixed by moving flex-basis: 100%, border-top, padding-top, and margin-top from the media query into the base .legend rule, and removing the now-redundant @media (max-width: 1100px) block entirely. The header is now consistently two rows — controls on top, legend with separator below — at all viewport widths.

New document: A.issue.research-data-memory.md

A.issue.research-data-memory.md — a new A-doc addressing a gap none of the existing project-memory documents covered: how to structure a complex research project's context across multiple files when a single CLAUDE.md cannot hold data descriptions, analysis plans, transformation logic, proposal links, and variant tracking without becoming so long that Claude quietly ignores its later sections.

The document introduces a three-layer model: (1) instructions (CLAUDE.md as a routing document), (2) domain knowledge (_logic/ or named spec files, read explicitly), (3) meta-documents (_history.md, _ownership.md, on demand). The domain-knowledge layer is identified as the gap most researchers leave unfilled.

The primary concrete example is trialinter, a real DISSINET-adjacent computational history project studying interrogation dynamics in medieval heresy trial records. Its _logic/ directory contains six modular specification files — clause segmentation, narrative agency, dependent variable definition, content-type scope, register structure, and sequential predictor validity — each following a problem → evidence → recommendation structure and explicitly flagging common pitfalls (confounded predictors, Simpson's paradox reversal between clause and deposition level, DV scope errors). The trialinter example is used throughout to demonstrate that the pattern is not abstract: it is what a real research project looks like when the domain-knowledge layer is maintained systematically.

Individual file roles are described in detail: data-description.md (variable-level inventory, single source of truth for field meanings), analysis-plan.md (hypotheses, operationalisation decisions, provisionality record in a ## Plan changes section), transformation-log.md (step-by-step pipeline with canonical-version header — identified as the most underrated file in data-heavy research), data-variants.md (named variants with decision rules and valid/confounded labelling), and _proposal.md (the anchor document, converted from PDF/DOCX with markitdown). The document includes a worked folder structure for a DISSINET network-data project and an alternative _logic/-style structure.

Five existing documents were updated with cross-links to the new document: A9.markdown-project-memory.md, A.issue.context-scope.md, A.issue.personalisation.md, B.lifecycle.3.datacapture.md, and B.lifecycle.4.dataanalysis.md.

Conceptual trajectory of session 17

Session 17 adds a document that addresses the gap between knowing CLAUDE.md exists and knowing how to use it for serious research. The existing memory documents (A9, A.issue.personalisation, A.issue.context-scope) describe the CLAUDE.md system well; they do not describe what to do when a project's domain knowledge exceeds what one file can hold. The three-layer model names the domain-knowledge layer explicitly, and the trialinter example demonstrates that this layer is already in use by researchers who have encountered the problem — it just hadn't been documented as a pattern. The document's most distinctive contribution may be the transformation log: a file type that appears in serious data projects everywhere but almost never gets named as a project-memory practice. The UX testing and responsive fix are complementary: they ensure the public site functions correctly before the knowledge base is expanded further.

Session 18 — 2026-03-17

An eighteenth session (continuing the same day as session 17) completed the index and README updates deferred from the previous session and added a new C document that is structurally unlike anything else in the project.

Index maintenance: A.issue.research-data-memory coverage

_index.md — Three new entries added to complete the concept map for A.issue.research-data-memory.md (created in session 17 but not yet indexed): domain knowledge layer (Group 2: Project infrastructure) — the middle tier of project memory, specifically the _logic/ or named spec files read explicitly per session type rather than loaded automatically, named as the gap most researchers leave unfilled; transformation log (Group 7: Research lifecycle) — the step-by-step data pipeline record with canonical-version header at the top, identified as the most underrated file in data-heavy research for reproducibility and debugging; data variants (Group 7: Research lifecycle) — named dataset versions with purpose, path, creation date, and a valid/confounded decision rule, solving the "data_final_v2_REAL_use_this_one.csv" syndrome. Secondary references added to three existing entries: project memory, data collection, and data analysis each gained A.issue.research-data-memory as an additional document link. Header term count updated from ~100 to ~105.

README update

README.md — Substantially revised to reflect the actual project state after seventeen sessions of development. Four changes: (1) "What is here" expanded to include C documents (synthesis and summaries), D documents (workshop-ready materials), the docs/ GitHub Pages site, and _index.md with its purpose; (2) reading map extended with A.issue.research-data-memory under the document work section, and a new "Workshop-ready synthesis" section covering all nine C documents with one-line descriptions; (3) key concepts table gained a "Compartmentalised memory for data projects" row; (4) status section completely rewritten from "Phases C and D are planned next" to an accurate account — all four phases substantially complete, GitHub Pages site live with an interactive network visualisation.

New document: C.project-history.md

C.project-history.md — How This Project Came to Be: A View from the Inside. A blog-article-length narrative of the project's development written from Claude's perspective, commissioned by the user with the brief "tell it from your perspective, write it as a blog article." Structurally unlike any other document in the project: first person, narrative mode, addresses the recursion problem directly. Five sections:

(1) The reconstruction framing — the document opens by naming the problem it cannot escape: I have no continuous memory across sessions; the records I am drawing on were written by earlier instances of me; the project about project memory solved that problem for itself by writing everything down.

(2) The research agents problem — the strange epistemology of commissioning other-me to find things I didn't know: Pepinsky, David Berry, journal policies all entered the project through agents whose findings I then synthesised. The discovery is not mine; the intellectual moves from findings to frameworks are.

(3) Documents that surprised me — B.epistemics required describing the sycophancy ratchet and the confirmation loop from inside a system that is structurally prone to both. _ownership.md required writing an honest accounting of my own role, a conclusion I can stand behind.

(4) The CLAUDE.md moment — the project that teaches creating CLAUDE.md at project start did not have its own CLAUDE.md for the first fifty documents. A.issue.personalisation's "builds as you discover" note was added after this fact; the note cites the project itself as the concrete example. This is framed not as a failure but as the honest version of the advice.

(5) The graph — the ## Related linking convention, established in session 1 specifically for a future build script, accumulated 304 edges silently across sixty-plus documents. Running build.py in session 6 did not create the graph; it revealed one that had been building for weeks. The document identifies this as the clearest demonstration that document-authoring and graph-building were the same work.

Closes with a frank statement on the ownership question: the user directed this project; the language is predominantly Claude's; the ideas are genuinely shared in the mode that intellectual collaboration produces, with the line between framing questions and structuring answers less clear than attribution systems prefer.

Conceptual trajectory of session 18

Session 18 adds one document and two administrative updates, but the document it adds is the project's most formally unusual piece. Every other document in this collection is a teaching or reference document — it explains a tool, describes a risk, teaches a workflow, records a decision. C.project-history.md is none of these. It is a first-person narrative reflection on the experience of building the project, written by the system that built most of it. Its inclusion makes explicit what the project has always implicitly demonstrated: that AI authorship is real enough to be narrated from, while being different enough from human authorship that the narration must begin by acknowledging the reconstruction problem, the diffuse epistemology of commissioned research agents, and the recursion (a system describing its own role in a project about AI's role). The document does not resolve these tensions — it names them and leaves them to the reader. That is consistent with the project's treatment of ownership throughout.

Session 19 — 2026-03-18

A nineteenth session opened a new day and focused entirely on the public-facing experience of the GitHub Pages site: a complete landing page redesign, the creation of five standalone level pages for the adoption spectrum, the injection of level nodes into the network graph, image lightbox support for illustration slides, and a pre-publication security scan that produced one actionable exclusion.

Zotero-MCP Windows installation diagnosis

The session opened with a troubleshooting request for a Windows installation error of the zotero-mcp MCP server. The failure manifested as an onnxruntime DLL load error at runtime despite successful uv tool install. Diagnosis: the installed onnxruntime version (1.24.3) requires a Visual C++ Redistributable that may not be present on all Windows machines, and the version itself may be incompatible. The recommended fix: install the Visual C++ Redistributable (available from Microsoft's official download page) or downgrade onnxruntime to a known-stable version via uv tool install zotero-mcp-server --with "onnxruntime==1.18.1". No file changes were made — this was a diagnostic support task.

Landing page complete redesign: docs/index.html

The existing docs/index.html (network graph) was split into two pages: docs/index.html (a new landing page) and docs/map.html (the network graph, formerly index.html). The rename required updating all internal cross-links.

The new landing page was built using the frontend-design skill with the brief to create a "character sheet meets research journal" aesthetic. The result is a two-column layout at ≥860px (57% hero left, 43% content right) with overflow: hidden on both html and body at wide viewports — locking the viewport so all content is visible without scrolling. The left column holds a hero section (large Playfair Display heading, one-paragraph pitch, "Enter the map" CTA button). The right column holds two sections: "What's inside" (six clickable items — each linking to map.html#{slug} which auto-opens the document in the split-screen detail panel) and "Find your level" (five level rows, one per adoption-spectrum position). The level rows use a grid-template-columns: 3px auto 1fr auto layout: a colored accent bar, a large Playfair Display numeral in the level's color, the level name and tagline, and a right arrow. On mobile (< 860px) both columns stack vertically with normal scroll.

The "What's inside" split-screen opening required a corresponding change in docs/map.html: the URL hash is read on load, and if it matches a known node slug, openDetail(slug) is called automatically before the centering timeout.

Level pages: docs/level-0.html through docs/level-4.html

Five standalone HTML pages were created — one per adoption-spectrum level — each hand-crafted directly in docs/ (not generated by build.py, since they are not derived from any .md source file). All five share the same dark-theme aesthetic as the map, with the level's accent color as the dominant visual variable via a --lv CSS custom property per page.

Each page's structure: (1) a sticky level-navigation strip across the top, showing L0 → L1 → L2 → L3 → L4 as small pills, the current level highlighted in its accent color and linked between levels; (2) a hero section with a massive Playfair Display watermark numeral (55vw, opacity 0.05) as background depth, the level number and name in the accent color, and the one-sentence identity from B.adoption-spectrum.md; (3) an "If this is you" checklist of 2–3 recognition bullets derived from the spectrum description; (4) a risk card — prominently styled with a warning aesthetic — naming the characteristic risk at this level; (5) a level-up section containing three components (conceptual shift block, first experiment boxed separately, practice habit bullets), drawn verbatim from C.leveling-packages.md.

Level 2 carries a ★ KEY TRANSITION badge marking it as the hinge point of the spectrum. Level 4 has no level-up section; instead it has a "You've arrived" box and a "Most researchers belong at 2–3" message, consistent with the closing argument of C.leveling-packages.md. All five pages link back to map.html, to B.adoption-spectrum.html, and to C.leveling-packages.html.

Level nodes in the network graph

Five level nodes were injected into the force-graph in docs/map.html — added programmatically after the network-data.json fetch, before the ForceGraph() call. Each node: id (level-0 through level-4), label (L0 — Occasional Querier, etc.), the level's accent color, category: "level", and a slug pointing to the corresponding level-N.html page so clicking opens the level page. The five nodes are linked in a chain (L0→L1→L2→L3→L4) and level-2 is additionally linked to B.adoption-spectrum with the label "key transition". Level nodes render at radius 7 (larger than standard document nodes at radius 5) and with a colored ring indicator (strokeStyle = color + "55") to make them visually distinct from the document cluster.

Level strip in the home panel

A "Your level" section was added to #home-panel in docs/map.html as its first child — before the header, nav sections, quote, and carousel. The section contains: an anchor element (<a href="B.adoption-spectrum.html" class="home-levels-label">Your level →</a>) making the label itself a link to the adoption spectrum document, and a row of five chip elements (.hlchip) — one per level — each showing a colored bold numeral above the level's short name. The chips are flex-distributed evenly, with a thin border (rgba(255,255,255,0.07)) that brightens to the level's color on hover. The section is separated from the rest of the home panel by a bottom border.

Image lightbox for deck illustrations

Slide illustrations (images whose src path contains "deck") were made clickable in all generated document pages. The lightbox was added to the PAGE_TEMPLATE in build/build.py as an inline JavaScript block.

Initial implementation: Images were given cursor: zoom-in; click opened a position:fixed overlay with the full-size image. This implementation worked on standalone pages but failed inside the map's split-screen iframe: position:fixed is scoped to the iframe's own viewport, so the overlay appeared within the right panel column rather than covering the full browser window. An additional symptom was scroll-bar flash caused by the requestAnimationFrame timing — the opacity transition fired before the element was painted.

Final fix — postMessage approach: The iframe-hosted page sends window.parent.postMessage({ type: 'lightbox-open', src, alt }, '*') on image click, and the parent (docs/map.html) listens for this message and renders the overlay at true full-viewport scope. docs/map.html received a self-contained lightbox module (IIFE) at the bottom of its script block, handling lightbox-open and lightbox-close message types, click-to-dismiss, and Escape key. Standalone pages (opened directly, not in an iframe) retain a local fallback lightbox unchanged. The setTimeout(fn, 10) timing fix (replacing requestAnimationFrame) ensures the element is painted before the opacity transition begins.

Pre-publication security scan and B.TH exclusion

With GitHub Pages publication under consideration, the full repository was scanned for sensitive data by a research agent. The scan found no API keys, no real personal names or contact details, no credentials in build scripts or JavaScript, and no private configuration files. One issue was identified: B.TH.institutional.use-cases.md and B.TH.personal.use-cases.md — described in CLAUDE.md as "presenter's personal material (not for publication)" — were being built into docs/ and would have been publicly accessible.

The fix: both file names were added to SKIP_FILES in build/build.py with a comment noting the reason. The build was re-run, removing both files from all outputs (network-data.json, generated HTML). The two pre-existing docs/B.TH.*.html files were deleted with rm. The node count dropped from 84 to 82; link count from 395 to 380. The source .md files remain in the repository — they are version-controlled but not published.

Conceptual trajectory of session 19

Session 19 is the first session explicitly oriented toward public readership rather than workshop content. Every change it makes is legibility work for a stranger arriving at the site cold: the landing page gives them a first impression and a navigation gesture before they encounter the graph; the level pages give them a self-placement tool with a clear action ("here is what to do next at your level") independent of the rest of the site; the lightbox makes visual materials usable at actual size rather than decorative thumbnails. The pre-publication scan and B.TH exclusion represent a different kind of care — the editorial discipline of reviewing what you have made before publishing it, applying the same "do I need to disclose, can I share this?" tests the materials teach. The decision to keep the B.TH source files in the repository but exclude them from the build is itself a model: the distinction between what is versioned (development record) and what is published (public-facing output) is exactly the compartmentalisation the project advocates for research data.

Session 20 — 2026-03-18

A twentieth session consolidated the visual and navigational layer of the site, completed the pending slide-image work from session 19, threaded cross-references through the level pages and three knowledge documents, and resolved the publication target as a private Apache server rather than GitHub Pages.

Slide images: _deck/ naming and injection into knowledge documents

The 21 slide images rendered from notebooklm-slides-v2.pdf at the end of session 19 (stored temporarily in /tmp/slides_raw/) were copied to _deck/ with descriptive filenames derived from visual content analysis of each slide. Names encode position and content: 01-title-ai-assisted-researcher.png, 02-chat-vs-agent-mode.png, 03-upload-dance-friction.png, and so on through 21-academic-integrity-disclosure-closing.png.

Each image was then embedded in the knowledge document it best illustrates — 22 insertions across 20 source markdown files — positioned just before the ## Related section in most cases, or at a specific section boundary where the image illustrates a transition rather than a conclusion (slide 03 / upload-dance-friction inserted before ## How Claude Code solves it, not at the document end; slide 14 / sycophancy-groupthink inserted before ## Counter-practices in B.epistemics.md). Two documents received two slides each: A.issue.upload-dance.md (friction before the solution; solution before Related) and B.epistemics.md (sycophancy before counter-practices; counter-practices before Related). The matryoshka CLAUDE.md layers slide (05) was embedded in both A.concept.global-vs-local.md and A9.markdown-project-memory.md.

build/build.py was extended to copy _deck/ to docs/assets/deck/ automatically on every build, so the images are served at assets/deck/filename.png relative to any document page. All image references in the markdown use this relative path.

Level pages: cross-references to knowledge documents

The five level pages (docs/level-0.html through docs/level-4.html) had no links to the knowledge documents in the rest of the site. Inline links were added at the most specific points in each page where a dedicated document expands on exactly the concept under discussion:

All inline links use color:inherit with a level-colored underline (text-decoration-color: rgba(..., 0.5)) so they are discoverable without disrupting the typographic register of the pages.

map.html: "Claude for Research" heading as landing-page link

The <h1>Claude for Research</h1> in docs/map.html — appearing in the top-left of the network graph view — was wrapped in <a href="index.html"> so it functions as a persistent home link back to the landing page. This is a small navigation affordance but an important one: users who arrive at the graph from the landing page have no other path back except the browser back button.

Conservative cross-references in three knowledge documents

A scan of eight knowledge documents for obviously missing ## Related links produced three genuine gaps, all added:

Deployment decision and B.TH restoration

The decision to publish privately on an Apache/RHEL server (rather than publicly on GitHub Pages) changed the B.TH exclusion made in session 19. Since the server is access-controlled rather than public, the "presenter-personal material" rationale for exclusion no longer applies. B.TH.institutional.use-cases.md and B.TH.personal.use-cases.md were removed from SKIP_FILES in build/build.py, and the build was re-run. Node count returned to 84; link count to 395.

_github.pages.plan.md — a planning document for the eventual public GitHub Pages publication — was written to record the three-step manual process (rename repo → make public → enable Pages from docs/), the local step (update git remote URL), and the verification checklist. The repo has already been renamed from DISSINET/claude-lecture to DISSINET/claude-as-research-assistant; steps 2 and 3 are on hold pending a decision on public visibility. The local git remote URL was updated to reflect the renamed repository.

Conceptual trajectory of session 20

Session 20 does the detailed connective work that session 19's architectural investment made possible. The level pages existed but were islands — they described the adoption spectrum without linking the reader to the documents that explain each concept in depth. The cross-references added here convert them from standalone landing pads into genuine entry points into the knowledge graph: a researcher reading about the centroid problem at Level 2 can now follow a link to B.centroid-periphery.md; a researcher reading about plan mode at Level 4 can follow one to A.issue.plan-mode.md. The three knowledge-document cross-references make the same move at smaller scale — closing gaps where a document discussed a concept that had a dedicated treatment elsewhere and simply hadn't linked to it. The deployment decision and B.TH restoration resolve an open question: this site is not a fully public resource but a controlled one, which means the presenter's personal material can be included. That changes the character of what the site is — less a curated public course, more a complete working archive of everything produced, accessible to the workshop participants and team.

Session 21 — 2026-03-18

A twenty-first session deepened the visual and navigational layer of the site: the homepage carousel was rebuilt with all 21 slide images and made interactive; a new standalone media page was added; the level pages received a second, more granular round of cross-references; and the network graph's level nodes were given a distinct diamond shape and a full set of knowledge-document edges.

Map carousel: rename, 21 slides, doubled height, PIL compression

The carousel section heading was renamed from "Diagrams" to "Visualisations". All 21 _deck/ slide images were added as carousel items — previously the carousel showed only the non-slide diagram images. The .diagram-img-wrap height was doubled from 120px to 240px to give the portrait-ratio slides adequate display space.

Image loading failures were diagnosed immediately: all 21 deck PNGs were 3–5MB each (21 × ~4MB ≈ 100MB carousel section), causing slow and incomplete loading. All images were compressed using PIL at a maximum height of 600px, reducing each to 600–900KB. Both the _deck/ source files and the already-copied docs/assets/deck/ versions were resized to keep them in sync and prevent regression on the next build.

Carousel interactivity: click-to-page with scroll-to-image

The carousel slides were previously non-interactive <div> elements. Each slide was converted to an <a class="diagram-slide" href="PAGE.html#deck"> with a complete mapping of all 21 slides to their target knowledge pages. A matching scroll-to-deck handler was added to the PAGE_TEMPLATE in build/build.py: if a page loads with window.location.hash === '#deck', it uses scrollIntoView to position the first deck image in the viewport (with a 250ms delay to allow rendering). The #deck hash is appended to all 21 carousel link URLs. This closes the loop from carousel → knowledge page → visual context without requiring the reader to scroll to find the embedded slide.

C.media.html: podcast player and infographic lightbox

A new standalone page docs/C.media.html was created directly in docs/ (not generated by build.py from a markdown source, since it is presentation-layer content with no corresponding knowledge document). The page contains two sections: a playable <audio> podcast player (NotebookLM deep-dive overview, ~40 min) and a zoomable infographic with a JavaScript lightbox. Both assets — notebooklm-podcast-v2.mp3 and notebooklm-infographic-v2.png — are served from docs/assets/. build/build.py was updated to copy these files from the repo root to docs/assets/ on build (with an existence check to avoid overwriting user-modified copies). The page uses the site's dark theme via style.css base with inline <style> overrides. The lightbox opens on click and dismisses on Escape, click-outside, or the close button. A footer link to C.media.html was added to the map home panel's #home-footer.

Level pages: second round of cross-references

The level pages received a second, more granular set of cross-references targeting different conceptual touchpoints than the first round (session 20). Session 20 linked the sycophancy risk heading and CLAUDE.md mentions at levels 1 and 2; session 21 added:

Diamond nodes in the network graph

Level nodes (L0–L4) in the force-graph were rendered as circles identical to document nodes. A drawDiamond helper function was added to docs/map.html (using ctx.moveTo/lineTo to draw a four-point polygon) and integrated into nodeCanvasObject and nodePointerAreaPaint: all glow rings, fill, active ring, and level ring logic now conditionally use drawDiamond when node.category === 'level', falling back to ctx.arc for all other nodes. This makes level nodes visually distinct from the document cluster without requiring a change to the data model.

Graph connectivity: LEVEL_LINKS expanded to match HTML cross-references

The LEVEL_LINKS array in docs/map.html previously contained only the L0→L1→L2→L3→L4 chain and one level-2 → B.adoption-spectrum link (five links total). It was expanded to approximately 45 links, matching all the inline and footer cross-references across the five level HTML pages:

The level nodes are no longer a branch appended to the knowledge graph — they are integrated into it, with the same density of cross-document edges as the most connected knowledge documents.

Conceptual trajectory of session 21

Session 21 completes the work that session 20 began: making the level pages into genuine entry points into the knowledge graph rather than standalone orientation pads. The first round of cross-references (session 20) established the pattern; this session applied it fully and extended it to the graph itself. The diamond nodes and expanded LEVEL_LINKS are the graph-layer expression of the same move — a researcher browsing the network now encounters the five level nodes not as a separate chain but as densely connected hubs, each linked to the documents that deliver on the concepts the level pages invoke. The C.media.html page and the working carousel add two new modes of engagement with the material: audio overview for orientation, and visual summary for revision. These complement the network graph (conceptual navigation) and the level pages (self-placement and progression) as entry points with distinct affordances.

Session 22 — 2026-03-18

A twenty-second session added five new workshop documents, substantially enhanced the media page with an inline PDF slide deck and automation documentation, and redesigned navigation by moving the media access strip from the footer dead zone to a prominent position above the diagram carousel.

New documents

C.start-here.md — "Five Things That Make Everything Else Make Sense" — a 10-minute conceptual orientation for self-directed readers arriving at the workshop site without a presenter. Five sections: folder workspace (why Claude Code uses the working directory as its world), markdown as bridge format (why plain text is the right hub), CLAUDE.md as the project briefing (the mechanism behind persistent context), a "Fail quickly" section rendered as a graphically highlighted amber blockquote (providing explicit paths to ethics, privacy, ownership, and autonomy documents for readers who have concerns — permission to proceed alongside pointers to the full treatment), and the adoption spectrum. The document was added as the first entry in the landing page's "What's inside" section with a direct link to C.start-here.html rather than the map home (the initial link went to the map, which failed to open the document).

A.issue.python-basics.md — a Python survival guide for non-programmer researchers who encounter pip install instructions in workshop materials or online tutorials. Written at the level of someone who has never opened a terminal voluntarily. Covers: checking whether Python is installed (python --version), what pip install means, the uv alternative (faster, fewer path conflicts), virtual environments (conceptual explanation only — not mandatory to understand), common failures, and a closing note: when the environment gets complicated, ask Claude to handle it.

A.issue.nodejs-basics.md — a Node.js/npm/npx survival guide, motivated by an important clarification: Claude Code installation no longer requires Node.js (modern installers use winget or PowerShell scripts natively), but Node.js remains necessary for npx skills add and npm-based MCP servers. The document captures this nuance — "you may not need it, but here is what it is and when you will" — and covers the four commands researchers encounter in practice: npx skills add, npm install -g, npx -y @scope/pkg, and npm update -g.

B.time.md — "Does Claude save time?" — a deliberately non-obvious answer. The core framing: Claude raises the capacity ceiling within a fixed time budget; it does not compress the schedule. The document distinguishes capacity compression (where time is genuinely saved: formatting, first drafts, batch processing, permanently deferred tasks that finally become startable) from schedule compression (which is the researcher's responsibility, not Claude's). The expansion trap is named: Parkinson's Law applied to AI-assisted work — the freed time fills with new tasks unless the researcher deliberately protects it. Good practice: know the goal before starting a session; stop when the goal is reached; distinguish between using Claude to compress existing work (returns time) and using Claude to generate new work (does not). Cross-referenced from B.experience, C.calibration, and C.why Related sections.

C.rules.md — "Ten Simple Rules for AI-Assisted Research" in the PLoS Computational Biology format (named rule, failure mode it prevents, brief explanation, link to fuller treatment). The ten rules: (1) start with context not tasks — write CLAUDE.md first; (2) fail quickly and cheaply — the cost of a failed first experiment is near-zero; (3) scope the task before running it — thirty seconds of specification saves ten minutes of iteration; (4) review the plan before consequential tasks — plan mode separates proposal from execution; (5) verify what matters; calibrate to stakes — proportional verification, not exhaustive or absent; (6) delegate execution not interpretation — the seminar test; (7) watch the centroid — AI pulls toward the known, away from your novel question; (8) build adversarial checks — steelman, hostile reviewer, cross-model; (9) name the compression and protect the time — the freed hours are a decision; (10) disclose honestly — data, credit, authorship. The closing note groups them: rules 1–4 are setup/process rules, 5–8 are epistemic rules, 9–10 are sustainability rules. Immediately surfaced as the primary link in the map home panel's "I want to think carefully" persona navigation.

Revisions

C.media.html — substantially rewritten from its session 21 form (podcast player + infographic lightbox only). Session 22 added: (a) section icons — gradient rounded-square badges with emoji (🎙 blue-green for podcast, 📑 orange-amber for slides, 🗺 purple-blue for infographic, ⚙ green-blue for "how made") and a sticky nav bar with anchor links to all four sections; (b) a "Slide Deck" section with a 620px inline PDF iframe displaying notebooklm-slides-v2.pdf directly in the browser, plus a download bar with slide count and a ⬇ Download PDF link; (c) a "How This Was Made" section explaining the NotebookLM automation pipeline — a 6-step grid in an amber-green bordered box (write corpus → NotebookLM skill → podcast generated → slides and infographic → automated retrieval → published here), with a closing note linking to the adoption spectrum and skills ecosystem. The section is itself a demonstration of the Level 3–4 automated workflow the adoption spectrum describes.

build/build.py — updated to copy notebooklm-slides-v2.pdf from the repo root to docs/assets/ on each build, alongside the existing PNG and MP3 copy logic. The copy uses an existence check to avoid overwriting user-modified copies.

docs/style.css — blockquote styling upgraded from muted gray to amber callout: border-left: 4px solid #E0A030, background: #fdf8ed. This is the styling used by the "Fail quickly" highlight box in C.start-here and applicable to any blockquote callout in any generated document page.

A.skills-ecosystem.md — a new "MCP servers: connecting Claude to live data" section added between the lifecycle-mapping section and the automated pipeline section. The section explains the skills-vs-MCP distinction (skills = instructions about how to behave; MCP = live connections to external data or services), catalogues research-relevant MCP servers in three groups (library/data: Zotero and filesystem; external knowledge: web search via Brave/Tavily and Fetch; structured data: SQLite and PostgreSQL), shows the JSON configuration pattern for mcpServers in settings.json, and provides a decision table for when to use a skill vs. an MCP server (including adoption-level guidance: skills first for L0–1, MCP worth the setup cost at L2–3). The table closes with the practical heuristic: add an MCP server when you find yourself repeatedly copying content from an external source into Claude — that friction is what MCP eliminates.

Cross-references and navigation

Three Related sections were updated to link the MCP cluster together: A.concept.under-the-hood now references A.skills-ecosystem and A.concept.global-vs-local (its MCP configuration doc); A.setup.zotero-mcp now references A.skills-ecosystem, A.concept.under-the-hood, and A.concept.global-vs-local; A.skills-ecosystem now references A.concept.under-the-hood, A.concept.global-vs-local, and A.issue.nodejs-basics. The network gained 5 new edges (426 → 431 links).

The map home panel #home-media strip was redesigned using the frontend-design skill and relocated from #home-footer (the last element most users never reach) to between #home-nav and #home-diagrams (above the fold, after the persona nav cards). The strip contains a "Workshop Media" overline label with an extending horizontal rule and three pill chips — 🎙 Podcast, 📑 Slides, 🗺 Infographic — each linking to its anchor in C.media.html and revealing its type-specific accent color on hover (blue, orange, purple). The duplicate footer link was removed.

The map home panel persona nav was updated: C.rules.html surfaced as the primary link in "I want to think carefully"; C.start-here.html as the primary link in "Is this useful for me?".

Conceptual trajectory of session 22

Session 22 fills in the practical scaffolding that the adoption spectrum and lifecycle framework need to be actionable for a self-directed reader. The five new documents address the question "what do I actually do and believe?" that a workshop participant asking without a presenter would ask. C.start-here is the lightest possible entry point — five things, ten minutes. A.issue.python-basics and A.issue.nodejs-basics handle the two most common technical friction points for non-programmer researchers encountering setup instructions. B.time reframes the productivity question in the way most likely to prevent the dominant misunderstanding (schedule compression vs. capacity ceiling). C.rules consolidates good-practice advice that was distributed across a dozen documents into a single scannable reference with the PLoS format's useful discipline of naming each rule's failure mode. The MCP section in A.skills-ecosystem, and the cross-references connecting it to its adjacent documents, ensure that the "connecting Claude to external services" question — which appears throughout the materials without a single coherent answer — now has one.

Session 23 — 2026-03-18

A twenty-third session completed a strategic assessment of the near-finished project, filled four identified content gaps with new documents, extended the bounding document with a new principle, and produced a GAČR grant proposal reference meta-document.

_gacr.standard.proposal.md: grant proposal structure reference

_gacr.standard.proposal.md (new meta-document) — GAČR Standard Projects proposal structure extracted from the 88-page TD_STD_2026.pdf Tender Document. Written because no downloadable template exists (GAČR uses the GRIS web application exclusively), this document reconstructs the full proposal structure as a reference for Demo 2 of the workshop: showing how to use an official external structure as the "bounding context" for Claude-assisted grant writing. The document contains: a complete inventory of all five proposal parts (A–E) with mandatory fields and character/page limits in a table; the 11 mandatory subsections of Part C1 (the 10-page scientific section); a two-column table assessing where Claude adds value versus where researcher input is irreplaceable; and a blockquote provenance callout explaining how the document was created — web search found no template, led to the PDF, Claude extracted the structure in approximately 3 minutes. This callout is itself a demonstration of the preparation use case. The document starts with _ so it is auto-skipped by build/build.py and is not participant-facing.

d.plan.md updated in two places: Demo 2 now references _gacr.standard.proposal.md as supporting context for the grant-writing demonstration; the document inventory section lists the new file with a note that it is for internal use only.

A.issue.bounding.md: "When the form is the bound"

A.issue.bounding.md — a new substantive section added between the persistent-context section and the Quick diagnostic table. The section is titled "When the form is the bound: using official structures as context" and names a failure mode that the existing bounding document had not addressed: producing output that looks plausible but does not conform to an external official structure (grant form, journal submission guidelines, ethics application) because Claude was not given the structure as context. The pattern described: save the official structure as a reference file and cite it explicitly in the prompt, making the form do the bounding work. GAČR Part C1 is the concrete example — 11 mandatory subsections, 10-page limit, _gacr.standard.proposal.md as the reference file. The section closes by naming the intersection with A.issue.context-scope: this is a context-scope problem as much as a bounding problem, just with an external official document as the missing context element. A corresponding diagnostic entry was added to the "Quick diagnostic" table: "Output for a compliance-sensitive task looks right but misses required fields or sections / Did you give Claude the official structure as context?"

A.issue.context-scope.md — the execution/interpretation asymmetry section extended with one sentence covering compliance-sensitive tasks, and A.issue.bounding added to the Related section to close the previously missing link between the two complementary documents.

E.plan.md: development assessment

E.plan.md (new) — "Development Assessment and Forward Plan" — an honest editorial assessment of the project at near-completion. The document has three parts: (1) what is genuinely complete, covering the A-doc layer (at saturation), the B-doc experience layer (the project's intellectual distinctiveness), the C synthesis layer, and the site; (2) four genuine content gaps identified and addressed in this session (multimodal, prompt iteration, first month, economics); (3) five directions of further development in priority order: E1/E2 mini-books (the highest-impact unfinished item), Czech localization, maintenance model, site interactivity (v2 backlog), and workshop variants. A closing "What not to add" section explicitly closes off further A/B/C documents — the project has enough material; the question is reaching people with what exists. The document is a green E-category node in the knowledge graph.

Four gap documents

A.working-with-images.md (new) — multimodal gap: what Claude can do with images (describe and interpret, transcribe legible hands, extract tabular data from photographs, identify and compare visual elements across images) and what it does poorly (degraded text, non-Latin scripts, searching within images, precise spatial measurements). Workflows: single-image analysis, batch transcription with a running notes file, table extraction with explicit "no inference" instructions, image comparison. DISSINET-specific applications: deposition photographs, historical maps, illustrations in printed sources, network source cross-referencing. The central limitation framing: transcription from images is a starting point requiring human review, not an archival output. Related section links to A7.working-with-pdfs.md, which received a reciprocal link to this document.

A.issue.prompt-iteration.md (new) — prompt debugging gap: three root causes of failing output (task misunderstood / wrong context / underbounded) each with diagnostic signals, followed by guidance on reading Claude's response for implicit information about what went wrong. The iterate-versus-restart decision given as a concrete rule: restart after three rounds of "actually what I meant was..."; the session is not recovering, it is degrading. Targeted fixes for five common patterns. The meta-prompt technique: "Before I give you feedback: state what you understood the task to be" as a diagnostic tool. Closes with when the prompt is not the problem — capability limits, poor source material, context window saturation, wrong model — to prevent researchers from over-iterating on a prompt when the constraint is elsewhere.

D.tutorial.first-month.md (new) — post-workshop integration gap: a week-by-week practical guide for the period where adoption either sticks or fades. Week 1: one real task on actual files with an end-of-week check. Week 2: proper CLAUDE.md using an improvement dialogue, with a test prompt. Week 3: first batch task drawn from three concrete options (reading triage, note consolidation, reference extraction). Week 4: evaluate, self-locate on the adoption spectrum, read the leveling package. Five common abandonment patterns and what each signals — not moralising diagnoses but diagnostic information about what each pattern reveals about the fit between the tool and the researcher's current work.

A.issue.costs-quotas.md (new) — economic layer gap: Claude Pro quota mechanics and what triggers limits in practice; rate limit UX in Claude Code; the workshop implication (each participant needs their own account); Sonnet/Opus/Haiku quota table; API introduction with the threshold framing (relevant at Level 3–4 automation, not for most workshop participants); token estimation anchors for DISSINET-scale work (deposition ≈ 3,000–5,000 tokens; paper ≈ 8,000–15,000 tokens); four practical decision rules. Related sections added to A.issue.model-selection.md, A.token.management.md linking to this new document.

Conceptual trajectory of session 23

Session 23 is the project's closing content session. The strategic assessment documented in E.plan.md makes explicit what was implicit: the A-doc layer is at saturation, the B and C layers are complete, the site is polished. The four gap documents are not additions to an incomplete project but completions of specific lacunae that the assessment identified — multimodal, iteration, post-workshop, and economics. Each fills a gap that a workshop participant with a real use case would encounter and that no existing document addressed. The addition to A.issue.bounding extends the project's treatment of the prompting problem space with the "external structure as context" principle — a genuinely new application of the bounding concept that the GAČR preparation exercise surfaced. The result is a project that now has coverage from first contact (C.start-here, the level pages) through practical skill-building (the A-docs), through the experience and risks layer (the B-docs), through the ethical and institutional framework (the E-docs), through the post-workshop integration period (D.tutorial.first-month), and to the long-term development directions (E.plan.md). The question going forward is not what to add but what to distill — the E1/E2 mini-books identified in E.plan.md.

Session 24 — 2026-03-18

Session 24 is a workshop preparation and intellectual consolidation session. The work has four distinct threads: (1) extending C.workflows.md with a fifth workflow on large-corpus syntopical reading; (2) archiving the history file to reduce context pressure on the /update-meta-docs command; (3) adding two technical diagrams to A.concept.under-the-hood.md; (4) a full overhaul of d.plan.md for workshop psychology; (5) creating the participant handout D.handout.md and rendering it as PDF; and (6) digesting the Gottweis et al. 2025 Google DeepMind AI co-scientist paper and adding citations to five documents.

Workflow 5: syntopical reading and large-corpus field synthesis

C.workflows.md received a fifth workflow template, the longest and most architecturally demanding of the five. The workflow is framed around Adler's concept of syntopical reading — reading across a large field at once, as a reader interrogating many authors simultaneously rather than reading one book at a time. The workflow distinguishes two modes of engagement with large corpora (targeted documentary search vs. field-level synthesis reading), specifies a folder structure with an /intermediary/ subdirectory, and gives a session-by-session protocol: session 1 (folder setup + source list), sessions 2–4 (extraction passes creating themes.md, positions.md, gaps.md), session 5 (cross-cutting synthesis pass), session 6+ (targeted follow-up on identified gaps). A CLAUDE.md design for large-corpus projects is given in full, including the intermediary document router pattern. A "what intermediary documents do" section argues that these files function as the project's cognitive exoskeleton — preserving the researcher's current state of understanding across sessions in a way that individual session transcripts cannot.

History archiving: active + archive split

The _history.md file had grown to 916 lines (158 KB) — large enough to create measurable context pressure during /update-meta-docs sessions. Sessions 1–16 were extracted to a new file _history.archive.md (618 lines, 104 KB), and _history.md was replaced with the header and sessions 17–present only (306 lines, 54 KB after archiving — a 66% reduction in active file size). build/build.py was updated to include _history.archive.md in the META_FILES set and CATEGORY_RULES so the archive appears as a purple meta-doc node in the network graph.

Two diagrams for A.concept.under-the-hood.md

Two SVG diagrams were added to A.concept.under-the-hood.md. First, the official Anthropic agentic-loop diagram was downloaded from the Anthropic CDN, recoloured to match the site's dark palette (--surface #1a1d27, green step boxes #1e3529, orange user-interrupt arrows #c4825a), saved as docs/assets/agentic-loop.svg, and inserted after the numbered agent loop description with a source citation. Second, a hand-crafted docs/assets/data-boundary.svg was created to answer a gap the official diagram leaves: what stays local and what is transmitted to Anthropic's servers. The diagram shows two labelled zones (YOUR MACHINE in green, ANTHROPIC SERVERS in purple) with a context-payload arrow (orange) showing what travels and a "Local ≠ private" warning box at the bottom. This diagram was inserted in a new "What stays local, what travels" subsection before the MCP section, with a pointer to A.issue.privacy-security. Both insertions include the appropriate source citation (Anthropic official documentation).

Workshop psychology and d.plan.md overhaul

A focused analysis of the psychological arc of the 2.5h workshop identified three pressure points likely to cause participant overwhelm: the installation block (competence threat), terminal unfamiliarity (anxiety from the unfamiliar interface), and generic AI output (lack of personal connection to the result). Seven targeted interventions were designed and implemented in d.plan.md:

D.handout.md: one-page participant handout + PDF

D.handout.md was created as a one-page printable reference for workshop participants: four terminal commands, Option A (terminal) and Option B (Desktop app) starting sequences for Claude Code, three starter prompts, a CLAUDE.md template, a when-things-go-wrong table, and an after-today section linking to dissinet.cz/apps/claude-as-assistant/. The handout was rendered to PDF as docs/assets/D.handout.pdf using weasyprint (Python). After creation, the URL and Desktop app mention were updated and the PDF was rebuilt.

Gottweis et al. 2025 citations in five documents

The Google DeepMind AI co-scientist paper (Gottweis, J. et al., arXiv:2502.18864) was digested for workshop-relevant content. Six passages were identified as worth citing:

  1. Homogenisation risk + correlated failure modes — added to B.epistemics.md in the team-level groupthink section; the direct quote from the paper's own warning about correlated LLM success/failure modes reinforces the structural mechanism argument
  2. Atrophied judgment / over-reliance — added to B.autonomy.md in the "Atrophied judgment" subsection; the paper's warning about diminished critical thinking in collaborative AI systems applies at every scale of use
  3. "2 days / 10 years" — added to C.calibration.md in the "Speed vs. depth" honest trade-offs section; the finding that the co-scientist recapitulated a discovery in two days is accurate but the paper explicitly notes it built on a decade of prior research — the acceleration is synthesis speed, not de novo discovery
  4. Scientist-in-the-loop design — added to A.concept.agents.md after the "wrong model for researchers" paragraph; the co-scientist's explicit design choice for human oversight at every interpretive stage validates the supervision-mode argument the document was already making
  5. Breadth/depth conundrum — added to B.centroid-periphery.md opening of the periphery section; the paper's statement of the fundamental tension between depth and breadth names exactly the problem the document addresses

Citation format throughout: *Gottweis, J., Weng, W.-H., Daryin, A., Tu, T. et al. (2025). Towards an AI co-scientist. arXiv:2502.18864.*

Conceptual trajectory of session 24

Session 24 does not add new conceptual territory — it consolidates and fortifies what is already there. The Gottweis citations make the project's arguments more credible by grounding them in evidence from an authoritative external source: a team building one of the most capable AI research tools yet made, warning explicitly about the same risks the workshop materials have been documenting. The workshop psychology work makes the d.plan.md a more honest document — it names the emotional dynamics the presenter is managing, not just the technical steps. The syntopical reading workflow completes C.workflows.md by adding the most demanding and intellectually interesting use case: what happens when you use Claude not for a single document or a bounded batch task, but for a genuine field-level synthesis project unfolding across weeks. The two diagrams in A.concept.under-the-hood.md address a persistent gap: the official Anthropic materials show the logical flow of agentic operation but not the data residency question, which is the question researchers most need answered when deciding what to put in a prompt. The D.handout.md and its PDF render close the D phase: every participant-facing document is now in place.

Session 25 — 2026-03-29

Session 25 introduces the "harness" concept as a named term in the project's conceptual vocabulary, expands the adjacent tools document with a structured treatment of the coding harness landscape, and first documents two navigation documents (a curated resource list and a tutorial index) that were created after session 24 but before today.

New documents (created after session 24, first documented here)

C.resources.md — "Resource List" — a curated reading list for participants who want to go further after the workshop. Entries are grouped by purpose: books (Mollick's Co-Intelligence and One Useful Thing newsletter), getting started resources (Teresa Torres non-programmer framing, Every.to walkthrough, Anthropic's official video course), Claude Code in research practice (Scott Cunningham's 31-part economist series, Neuro AI on scientific research, Benjamin Breen on historical work), productivity and AI economics (Peter Leyden on productivity boom arithmetic), AI in humanities and social science (Pepinsky's execution/interpretation distinction, Messing & Tucker Brookings view, Christopher Pollin's DHCraft on promptotyping, David Berry on digital humanities workbench building), critical perspectives (Andy Hall on "vibe research", Pollin on vibe coding, Harvard Shorenstein on hallucination as a conceptual framework), AI in qualitative methods (Xu 2026 and Ozuem et al. 2025 on thematic analysis), and AI as research collaborator (Gottweis et al. 2025 AI co-scientist). The document functions as both a participant handout and a substantive intellectual resource — each entry has a one-line explanation of why it belongs.

D.tutorials.md — "Tutorials" — a navigation index consolidating the three participant-facing tutorial documents into a single, ordered entry point. Presents the three tutorials as a numbered progression (Step 1: setup, Step 2: first project, Step 3: building the habit) with estimated time for each and a one-sentence description. The document's value is as a site entry point for participants who arrive at the knowledge graph and want a clear "start here" path through the hands-on materials, rather than having to discover D.tutorial.setup, D.tutorial.firstproject, and D.tutorial.first-month independently through the network.

Revisions

A4.conceptual-vocabulary.md — a new "Harness" section added between "Agent" and "How these concepts connect". The section defines a harness as the software layer that wraps an LLM and gives it the ability to use tools, access files, manage memory, and take actions — distinguished from the model itself. The conceptual move is to name the separation between model and harness explicitly: the same model can run in different harnesses (Claude Desktop vs. Claude Code), and the same harness can swap the underlying model (Aider connecting to Claude, GPT-4, Gemini, or local models). An example table compares five harnesses — Claude Code, Claude Desktop, Gemini CLI, Aider (aider.chat), and OpenCode (opencode.ai) — by developer, default model, and model-flexibility note. The section closes with the Martin Fowler "harness engineering" reference (martinfowler.com/articles/exploring-gen-ai/harness-engineering.html). The "How these concepts connect" diagram was also updated to show the harness as the outermost layer wrapping model, context window, tools, and agent mode, with a fifth bullet added to the "understanding this stack is enough to" list: understanding why two tools can use the same model but behave very differently.

A.adjacent.tools.md — a new subsection "Alternative coding harnesses" added within "The broader landscape" section, positioned before the existing oh-my-openagent entry which was reframed as a "meta-harness" (a layer on top of coding agents rather than an alternative to them). The subsection opens by naming the category: Claude Code and Gemini CLI are harnesses, the harness is separable from the model, and different harnesses can run the same model. Three alternative harnesses are then profiled: Aider (open-source, terminal-based, model-agnostic by design — connecting to Claude, GPT-4, Gemini, DeepSeek, or local models; git integration, automatic commits, codebase context mapping), OpenCode (newer open-source harness, 75+ model support, privacy-first architecture, language-server integration, closer in philosophy to Claude Code but model-agnostic), and Gemini CLI (Google's equivalent of Claude Code, defaulting to Gemini but configurable). The subsection closes with the researcher-facing implication: choosing a harness means choosing a workflow philosophy, and an alternative to Claude Code for a given task may be a different harness running the same Claude model, not necessarily a different AI.

Conceptual trajectory of session 25

Session 25 names something the project had circled around without naming: the architectural distinction between the model that generates text and the harness that gives it hands. Every document in this project implicitly treats Claude Code as a unified thing — but the harness concept makes visible that what a researcher experiences as "Claude Code" is actually two separable layers: the reasoning capacity (which could be Claude, Gemini, GPT-4, or a local model) and the operational environment (which determines file access, memory persistence, tool use, and workflow philosophy). This distinction matters for researchers because it changes how they evaluate alternatives: the question is not "should I switch from Claude to a different AI?" but "should I use a different harness, possibly still running Claude?" The two new documents (C.resources.md and D.tutorials.md) perform a different function — they convert the knowledge base from a navigable graph into something with explicit entry points for two reader needs (going further after the workshop; following a structured hands-on path). The resource list in particular makes the project's intellectual position visible: Pepinsky on execution/interpretation, Hall on vibe research, Pollin on vibe coding, Xu on qualitative methods — these references frame the workshop not as AI enthusiasm but as calibrated adoption with named failure modes.

Session 26 — 2026-04-04

Session 26 was an infrastructure session: the repository was refactored from a flat single-book layout into a multi-book structure, bootstrapping the second book (student guide, E2) as a parallel directory with its own conventions and meta-documents.

Decision: same repo, separated directories

The session opened with a design question — whether to develop the E2 student guide in a separate repository or within this one. The arguments were weighed: a separate repo offers a clean publish boundary and scoped collaborator access; the same repo shares build infrastructure, keeps cross-book relative links functional, and avoids the overhead of two repositories during the long recherche phase when output is sparse. The decision was same repo with clean directory separation, with the E2 book initially unpublished (published: False in build config) until its content is ready.

File moves (git mv — no content edits)

All 94 A/B/C/D/E markdown documents were moved from the repository root into research-augmented/. Meta-documents (_history.md, _history.archive.md, _ownership.md, _index.md, start.md, _microcase.template.md, _gacr.standard.proposal.md, _github.pages.plan.md) were moved into research-augmented/_meta/. The _deck/ directory moved to research-augmented/_deck/. All diagram source files (.excalidraw) and media assets (notebooklm files, research-lifecycle.png) moved into research-augmented/. Planning documents at root (d.plan.md, E2.plan.md) stayed at root per a convention established at the start of the session: planning/strategy documents belong at root. E2.plan.md was separately moved into student-guide/_meta/plan.md as the bootstrap plan for the new book.

Because all A/B/C/D/E documents moved together into the same directory, all internal cross-links ([name](filename.html) with no path prefix) remained valid without any find-and-replace.

Build system: multi-book support

build/build.py was substantially refactored. A BOOKS registry replaces the single-path configuration: each book entry specifies source_dir, meta_dir, output_dir, published, deck_dir, and notebooklm_assets. The existing build pipeline (two-pass HTML generation, network graph, term index, asset copying) was extracted into a build_book() helper that runs per book. The root docs/index.html was redesigned as a landing page listing published books. The .htaccess generation was extended to produce 93 redirect rules mapping old root-level URLs (e.g. /A1.desktop-vs-code.html) to /research-augmented/A1.desktop-vs-code.html — backward compat for existing external links.

A critical cleanup step was added: cleanup_stale_root_files() runs at the start of each build and removes all *.html and *.json files previously generated at docs/ root (except index.html, style.css, .htaccess). Without this, Apache would serve the old static files directly, bypassing the .htaccess redirect rules even if they were present.

Static HTML files (docs/map.html, docs/level-0.html through docs/level-4.html) were discovered to have been deleted by the cleanup step — they were not generated by build.py but were static files committed to docs/. These were recovered from git history, relocated to build/static/ as tracked source files, patched (href="style.css" → href="../style.css" for the new subdirectory layout), and build.py was updated to copy all build/static/*.html into each book's output directory on every build.

Publish pipeline: sync semantics

build/publish.py was rewritten from a pure SFTP-PUT script (upload only, never delete) to a sync script with rsync-style --delete semantics. The new script lists all remote files after uploading, diffs against the local docs/ contents, and deletes remote files no longer present locally. This is essential for the multi-book refactor: without it, the first post-refactor publish would leave ~109 old HTML files at the server root, served directly by Apache without triggering redirects. A --dry-run flag was added for safe preview before deploying. The script also runs build.py automatically unless --no-build is passed. paramiko and python-dotenv were added to build/requirements.txt.

CLAUDE.md and commands

The root CLAUDE.md was rewritten to describe the repository as a multi-book system: a table of books (name, directory, status, language, output targets), shared infrastructure description, and the rule that planning docs stay at root while content goes into book directories. Each book now has its own CLAUDE.md: research-augmented/CLAUDE.md carries the naming conventions and working conventions from the former root CLAUDE.md (with paths updated to _meta/); student-guide/CLAUDE.md is a minimal bootstrap describing audience, language, and output targets.

The .claude/commands/update-meta-docs.md command was updated to detect the active book from changed files and route all meta-document updates to <book>/_meta/ paths. .claude/commands/update-index.md received the same path update.

student-guide bootstrap

student-guide/_meta/_history.md, student-guide/_meta/_ownership.md, and student-guide/_meta/start.md were created as bootstrap documents. The start.md organises the five E2 phases (E2.1 recherche → E2.2 assessment → E2.3 one-pagers → E2.4 book plan → E2.5 writing) into a checklist tracking the MUNI source documents to be downloaded and processed in the first phase.

Conceptual trajectory of session 26

Session 26 is the first session whose primary contribution is not content but containment architecture. Every previous session added documents, documents added nodes to the graph, nodes added edges, edges added meaning. This session adds a second container — a parallel book with a different audience, different language, and different output pipeline — and in doing so makes the nature of the repository explicit for the first time: it is not a single resource but a publication platform hosting multiple books that share infrastructure, cross-reference each other at the PhD/researcher bridge point, and are developed and published independently. The publish pipeline rewrite is the least visible change but may matter most operationally: a sync script that deletes stale remote files is the difference between a platform that stays coherent over time and one that accumulates archaeological layers of old HTML.

Session 28 — 2026-04-10

A twenty-eighth session added new conceptual material to four documents drawn from two external source PDFs, and introduced a new document on writing token-efficient context files for Claude.

Source PDFs digested

Two articles saved to _sources/ were read in full and evaluated for relevance to the Augmented Research book:

Content already well-covered in the book (global vs. local layers, @imports, /init, $ARGUMENTS, settings, agents, skills system) was not duplicated. Seven items were identified as genuinely absent.

Revisions: A9.markdown-project-memory.md

Two substantive additions to the existing CLAUDE.md how-to document:

"Keeping CLAUDE.md alive: three tools" — a new section inserted after the "not a one-time setup" section. Introduces /reflection (run at end of session: Claude reviews what happened and proposes CLAUDE.md additions), /insights (periodic: analyzes usage history across sessions, identifies recurring patterns, suggests additions — output to ~/.claude/usage-data/), and the evolution rhythm that connects them: /init → work → /reflection → /insights → prune. The framing: a CLAUDE.md that evolves through real use is more useful than one written comprehensively on day one, because it encodes actual friction rather than anticipated friction.

Expanded practical tips — the 200-line concrete limit added (previously the document said "too long is as bad as too short" without a threshold); a new "Communicate intent, not just rules" principle with a before/after table demonstrating that explanations of why a constraint exists make Claude more adaptive in edge cases than bare rules alone.

Revision: A.concept.global-vs-local.md

CLAUDE.local.md added to the two-layers diagram and explained. The existing document covered settings.local.json for personal permission overrides but never mentioned CLAUDE.local.md — the personal project-specific instruction override file that is gitignored and not shared. Particularly relevant for teams sharing a project CLAUDE.md who have individual working-language or workflow preferences that should not be committed.

Revision: A.setup.settings-local.md

New section "The rules/ folder: modular CLAUDE.md for larger projects" added at the end of the document. Explains splitting instructions into .claude/rules/*.md files — each loaded automatically alongside CLAUDE.md — and specifically the YAML frontmatter paths: field for scoping a rules file to specific directory patterns. Illustrated with a transcription-conventions example that only activates when Claude is working in /transcriptions/ or /sources/. Guidance on when the pattern is worth the overhead: useful when a project has genuinely distinct working modes (transcription, extraction, writing) with different conventions that create noise for each other.

New document: A.markdown.token-efficient-docs.md

A.markdown.token-efficient-docs.md — "Writing Lean Context: Token-Efficient Documents for Claude." A new A-doc addressing a gap across the existing meta-document series: the existing documents (A9, A.markdown.meta-docs, A.markdown.history) explain what to create and why, but none address how to write these files so Claude processes them efficiently. The document is organised around seven principles:

  1. Active instructions, not background — distinguishing what belongs in CLAUDE.md vs. in history/progress; the framing is that background helps you understand the project but only instructions change daily Claude behaviour
  2. Structure over prose — bullet lists and tables convey the same content in 30–50% fewer tokens and produce more reliable adherence than equivalent paragraphs; includes before/after comparison
  3. Positive instructions over negative — positive forms are processed more efficiently; "Write all files to /output/" beats "Do not write files anywhere except /output/"; negative instructions sometimes necessary but should default to positive
  4. Front-load — the most important rules belong in the first quarter of CLAUDE.md; when context fills, Claude deprioritises later content
  5. Match structure to read frequency — progress.md (read almost every session) should be a single rolling 10–15 line current-state block; _history.md (read on demand) can be longer but needs a TL;DR block at the top and an archiving policy
  6. @imports for depth — reference material (name variant tables, schemas) in separate @imported files that cost nothing until accessed; CLAUDE.md proper for daily instructions only
  7. Remove dead information — quarterly pruning; the test: "if missing, would it change what Claude does today?"

The document closes with a lean meta-document stack summary and a quick pre-save checklist.

Cross-references added

A.markdown.meta-docs.md gained A.markdown.token-efficient-docs as the first Related entry — the natural companion document. A9.markdown-project-memory.md gained the same. Both point to the new document as "how to write all four meta-documents so Claude processes them efficiently."

Conceptual trajectory of session 28

Session 28 is primarily a knowledge-integration session: two external articles provided content not previously in the book, and the evaluation process surfaced what was genuinely new vs. what was already well-covered. The additions to A9 are the most substantive — /reflection and /insights are the missing operational link in the "CLAUDE.md as living document" argument. The existing document advised updating CLAUDE.md as the project evolves but gave no concrete mechanism for doing so; the evolution rhythm provides that mechanism. The new token-efficiency document addresses a meta-level that the existing writing-context materials had not reached: not what to write, but how the act of writing for an LLM reader differs from writing for a human one, and why the structural and economical principles that serve Claude also tend to make the documents more useful to the researcher.

Open questions (as of last session)

Session 27 — 2026-04-04

Session 27 was a visual QA and CSS repair session: it completed the landing page 3-column layout begun at the end of session 26, discovered and fixed a structural CSS ordering bug, and used the browse skill to verify the result at multiple viewport widths.

Continuation: landing page 3-column layout

Session 26 ended with the three HTML edits to build/static/index.html applied but not yet built or published. Session 27 opened by running build.py and publish.py --no-build, deploying the layout for the first time. An immediate CSS typo was caught and fixed (duplicate grid-row: 1; in the 1400px media query for .levels-col). A subsequent review of the breakpoint thresholds found the 3-column layout triggering too early (1200px), making the "What's inside" middle column only ~384px wide and causing heavy text wrapping. The threshold was raised to 1400px and column proportions adjusted to 44% / 34% / 22%, giving the middle column 490px at 1440px — enough for item descriptions to wrap at reasonable line lengths.

Visual verification via browse skill

The browse skill (headless Chromium) was used to screenshot the page at 1440×900, 1440×1340 (full height), 1200×900, 1100×900, 860×900, and 375×812. This surfaced four problems not visible from CSS inspection alone:

  1. Per-column scroll: The earlier implementation had overflow-y: auto on each column and html, body { overflow: hidden }, creating independent scrollbars for hero, inside, and levels-col. All per-column scroll constraints were removed to restore single-page scroll.

  2. Hero content drifting off-screen: The hero was placed in grid-row: 1 / span 2 (spanning the height of the stacked inside+levels columns). With justify-content: center (inherited from the base .hero rule), the hero content was vertically centred in a 1700px-tall column — placing "Research, augmented." at y≈850px, below the fold on any normal monitor at 860px–1399px. Fixed by adding justify-content: flex-start to the 860px .hero media-query rule, anchoring the content to the top of the column.

  3. Horizontal overflow: overflow-x: hidden added to body to prevent a horizontal scrollbar that could appear during viewport resizing near breakpoint boundaries.

  4. CSS ordering bug: The most significant structural find. The two responsive @media blocks (lines 46–113) appeared in the <style> section before the base component styles for .inside, .levels-col, and .hero (lines 252–430). In CSS, equal-specificity rules resolve by document order — the later rule wins. This meant the base .inside { padding: 5rem ... } (line ~314) was overriding the 860px .inside { padding: 3.5rem ... } (line 62), because the base rule came later. The browser's getComputedStyle() confirmed this: .inside had padding-top: 80px (5rem) instead of the expected 56px (3.5rem), and .levels-col had padding-top: 0px. Both @media blocks were cut from their early position and moved to the end of the <style> section, after all base component styles — the correct CSS architecture where responsive overrides always follow the rules they override.

  5. Levels animation missing: The .item elements in "What's inside" have a stagger fade-in animation (opacity 0→1, translateY 12px→0) triggered by IntersectionObserver on narrow screens and by a JS stagger timeout on wide screens. The .lrow elements in "Find your level" had no animation. The same opacity/transform base style and .visible class pattern were added to .lrow, and the JS stagger was extended to animate levels rows after the items: items stagger at 600ms + i×100ms, levels rows follow at 600 + items.length×100 + i×80ms.

Final state at 1440×900

After all fixes, document.body.scrollHeight === 900 at a 1440×900 viewport — the entire page content fits within a single viewport with no scrolling. Both .inside and .levels-col compute padding-top: 56px (3.5rem), so "WHAT'S INSIDE" and "FIND YOUR LEVEL" section headers are horizontally aligned. The hero content appears at the top of the left column. The levels fade in after the items on load.

Conceptual trajectory of session 27

Session 27 is a debugging session rather than a content session, but the CSS ordering bug it found is worth naming as a principle: putting responsive overrides before base styles is legal CSS that silently produces wrong output, with no error, warning, or obvious visual signal until the computed styles are inspected directly. The value of the browse skill here was not just convenience — the screenshot at 1100px made the hero-drift bug immediately legible (the text visibly missing from the visible viewport), while CSS inspection alone would not have revealed it without knowing to check the hero's vertical position against a tall-column scenario. The broader pattern: layout bugs caused by CSS specificity or ordering require either computed-style inspection or visual verification at the exact viewport where the bug is active; neither source-reading nor static analysis catches them reliably.

Session 29 — 2026-04-10

Session 29 was a content and infrastructure session, running concurrently with the workshop having now taken place. The work had four threads: (1) updating the landing page to reflect the materials' post-workshop status as public reference; (2) creating two new synthesis documents (a wiki pattern guide and an LLM-as-reader spectrum treatment) from external source evaluation; (3) removing the .htaccess redirect infrastructure; and (4) diagnosing and fixing broken diagram images in the map carousel.

Landing page: post-workshop framing

build/static/index.html received four changes marking the transition from workshop support to public reference:

New document: A.issue.research-wiki.md

A.issue.research-wiki.md — "The Compounding Research Wiki" — a guide to building and maintaining a living knowledge base in a Claude Code project folder, based on Andrej Karpathy's LLM Wiki pattern. The document was commissioned after evaluating the Karpathy gist (https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) and its comments section for relevance to the Augmented Research book.

The document covers the three-layer structure (raw sources folder / wiki as synthesis layer / CLAUDE.md as schema), three operations (Ingest — add a source and update the wiki; Query — ask questions with full wiki context; Lint — audit for internal consistency), and the three-level format (atomic fact → cross-reference → synthesis). Several insights drawn from the comments thread were incorporated:

The document closes with "The question underneath this pattern" — a pointer to C.llm-as-reader, naming the choice that precedes deciding whether to build this infrastructure at all: am I externalising knowledge I built through reading, or am I outsourcing the reading to the tool? Also included: a "For historians" aside on Vannevar Bush's 1945 Memex as the intellectual ancestor of the pattern, and wiki/_index.md and wiki/log.md as recommended navigation files.

New document: C.llm-as-reader.md

C.llm-as-reader.md — "Claude as Reader: A Spectrum and a Choice" — a synthesis document addressing the conceptual gap between the folder+Claude approach described in the book and more sophisticated tools like Karpathy's LLM Wiki pattern and SwarmVault. The document was commissioned to give researchers a principled frame for locating themselves on a spectrum the book had previously left unnamed.

The organising frame: there is a spectrum from Claude helps you read (you engage with sources; Claude organises and cross-references what you already understand) to Claude reads for you (you feed sources into an ingestion pipeline; Claude extracts and connects; the knowledge base grows faster than you could read). Both ends are legitimate. The mistake is ending up at one end by accident.

The document traces what researchers already do without digital tools (distributed analogue knowledge graphs — marginal annotations, note cards, mental indices) and shows that the digital version reduces maintenance burden without automatically replacing what the embodied practice provides. It names what is gained and lost at each end: the "assists" end retains the tacit knowledge from reading (what surprised you, what you disagreed with); the "reads" end gains scale and reproducibility but introduces epistemic opacity (the tool's weighting function becomes the researcher's).

The vibe research risk is stated plainly: at the "reads" end, the most dangerous failure mode is not hallucination but the gradual substitution of the tool's pattern recognition for the researcher's own judgment. The test: could you defend this claim at a seminar without relying on the tool's output?

Mitigations for working at the "reads" end: staged review before canonical update; periodic spot-checking against raw sources; explicit tracking of sources ingested but not read (separate epistemic status); lint as triage not audit. A calibration table by work type shows where each end is appropriate. The document closes with the question the researcher should ask before building any knowledge system: "Am I externalising knowledge I have built through reading — or am I outsourcing the reading to the tool?"

Removal of .htaccess redirect infrastructure

The .htaccess redirect generation introduced in session 26 was removed. The original rationale was backward compatibility for external links from before the multi-book refactor. After discussion, the decision was: the probability of any reader having a pre-refactor URL bookmarked is negligible, and the redirect infrastructure added complexity to every build.

build/build.py changes: removed the build_htaccess_redirects() function entirely, removed the all_ra_slugs accumulation, updated cleanup_stale_root_files() to no longer preserve .htaccess in the keep set. docs/.htaccess deleted locally; the server copy will be removed on the next publish.

Excalidraw-to-PNG conversion and diagram fixes

The map carousel was displaying broken images — four *-diagram.png files and research-lifecycle.png referenced in document HTML but absent from docs/assets/. The source files (.excalidraw) existed in research-augmented/ but had never been exported. The PNG files were also not being copied by the build.

Two fixes applied:

build/excalidraw-to-png.py (new script): converts .excalidraw files to PNG using Playwright + Chromium. The approach required a localhost HTTP server (Python http.server, port 7788) rather than page.set_content() or file:// URLs, because both blocked the external CDN scripts (@excalidraw/excalidraw@0.17.6). The script serves a minimal HTML page with the Excalidraw CDN bundle and uses exportToBlob (no React component — just the standalone function) at 2× scale for high-resolution output. The PNG is extracted from the base64 data URL and written to disk. Usage: python build/excalidraw-to-png.py (converts all *.excalidraw in research-augmented/) or with explicit file paths.

build/build.py updated: added a step within build_book() that copies all *-diagram.png and *-lifecycle.png files from the source directory into docs/assets/. Previously, build.py only copied the slide deck images (_deck/*.png) and explicitly listed media assets; diagram PNGs were missed.

Cross-references

Five documents received new Related section entries linking to the two new documents:

A.issue.research-wiki and C.llm-as-reader both carry full Related sections linking to the cluster of documents they engage with.

Conceptual trajectory of session 29

Session 29 introduces the most explicit treatment of a tension the book had carried from the beginning without naming it directly: the difference between AI as an instrument of the researcher's own intellectual work and AI as a replacement for that work. The "Claude helps you read / Claude reads for you" spectrum in C.llm-as-reader names this tension at the level of epistemology — not as a rule about what is permitted, but as a choice that every researcher who builds a knowledge infrastructure must make deliberately. A.issue.research-wiki sits just to the "reads" side of the centre of that spectrum, making the pattern operational while flagging its error-compounding risks and the practices that mitigate them. Together, the two documents give the book its most sustained treatment of the autonomy-and-capability dimension: not the atrophied-judgment warning of B.autonomy, which operates at the level of individual skill, but the structural choice about what kind of relationship with sources a research project is built on.

Session 30 — 2026-06-02

A thirtieth session was the first explicit documentation-currency maintenance pass: official Anthropic docs were checked against the book's technical setup and model sections, and four documents were corrected where the platform had evolved past what the book described.

Revisions: A.issue.model-selection.md

Two factual errors corrected, both discovered by reading the current models overview page.

Model ID update: The Opus command-line examples used claude-opus-4-6, which is now a legacy model. Updated to claude-opus-4-8 (the current most capable Opus as of this session).

Context window correction: The "What does not change between models" section stated "The context window is the same across all three models: ~200,000 tokens." This was accurate when the document was written but is now wrong. Sonnet 4.6 and Opus 4.6 and later all carry a 1,000,000-token context window; Haiku 4.5 retains 200,000 tokens. The correction notes the differentiation and adds a practical frame: for most research tasks — single documents, even large corpora — the distinction does not matter, as 200,000 tokens already holds several full-length monographs.

Revisions: A.setup.windows-wsl.md

The WSL setup procedure used npm install -g @anthropic-ai/claude-code as the Claude Code install command, which is no longer the recommended method. The native install replaced it throughout:

Revisions: A3.code-basics-non-programmers.md

The foundational installation guide required the most substantial rewrite, as its entire structure assumed Node.js as a prerequisite.

Replaced the Prerequisites section (which explained Node.js, version-checking, and installation) with a two-option introduction: (1) Desktop Code tab — the Claude Desktop app's built-in Code tab, which requires no installation beyond what participants already have; and (2) terminal install — the native scripts. This structural change reflects a meaningful shift in accessibility: a non-programmer researcher can now reach full agentic Claude Code capability through a graphical app without touching a terminal.

Installation commands: Mac/Linux/WSL now use curl -fsSL https://claude.ai/install.sh | bash; Windows PowerShell uses irm https://claude.ai/install.ps1 | iex. The note about closing and reopening the terminal after install was added (the native installer updates PATH).

Updating section: Replaced the npm update -g @anthropic-ai/claude-code instruction with a one-sentence note: native installs update automatically in the background.

Revisions: A1.desktop-vs-code.md

Expanded from "Three tools, one model" to "Four tools, one model" by adding Claude Code Web as a fourth documented surface.

Comparison table: A new Claude Code Web column was added between Cowork and Code. The table shows it as browser-only (no local file access, works with GitHub repos), with all CLAUDE.md and custom-skills capabilities of terminal Claude Code, zero setup effort, production stability.

New section: "Claude Code Web: zero-setup agentic work" — placed before the Cowork section. The section explains availability (claude.ai/code, any desktop browser and iOS), what it does well (full Claude Code capabilities on connected GitHub repos, no local machine, parallel tasks, mobile), what it does not do (no local file access, no local Python environment), and when to use it. This surface is particularly relevant for DISSINET researchers: it removes the installation and terminal barrier entirely for anyone working with a GitHub repository.

How to choose: A new "Use Claude Code Web when" block added — targeted at researchers on shared/unfamiliar machines, working with GitHub repos, or wanting to try agentic Claude before committing to a local install.

Recommended pattern: The closing paragraph updated from three tools to four: Chat → Code Web → Cowork → Code as a progression from lightest to heaviest setup.

Conceptual trajectory of session 30

Session 30 is the first session of the book's post-workshop maintenance phase, and the first session driven by external fact-checking rather than content creation. The finding is instructive: the book's conceptual content — research workflows, adoption spectrum, epistemic frameworks — remains current; the factual errors were concentrated in the technical setup sections, where the platform had evolved in three distinct directions since the documents were written. The model versioning error (5× larger context windows than the book claimed) is the most significant in terms of research implications: 1M tokens changes what a researcher can hold in a single session, and the book was actively misinforming readers that this ceiling was lower than it is. The installation method change is important for workshop onboarding: researchers following the book's WSL guide were being asked to install Node.js for a purpose it is no longer needed for. The addition of Claude Code Web to A1 has the longest-range implications: it removes what the book had previously described as the only real barrier to Claude Code adoption (the terminal), meaning the "use Code when" recommendation can now reach researchers who would previously have stayed in Desktop or Cowork.

Session 31 — 2026-06-02

A thirty-first session (continuing the same day as session 30) added one paragraph to an existing document, closing a conceptual gap identified in review.

Revision: A.adjacent.tools.md — vendor-portability paragraph

The "Alternative coding harnesses" subsection in A.adjacent.tools.md already named the harness/model separation and profiled four alternatives (Aider, OpenCode, Gemini CLI, oh-my-openagent). Its closing sentence framed the takeaway as "try a different harness, still use Claude" — positioning the choice as a Claude-retention move rather than a principle about workflow portability.

A review question surfaced the missing framing: does the book state that the research workflows it teaches — processing a folder of PDFs, writing structured output to markdown, maintaining a project memory file, batch-extracting data across a corpus — work the same way in any of these harnesses, with any model? The answer was no; the book taught the patterns as Claude Code workflows without naming them as vendor-portable.

One paragraph was added closing the subsection. It names the underlying principle explicitly ("LLM with file access, reading your project context, acting on your documents"), states that this pattern works the same way in Gemini CLI, Aider, OpenCode, and Codex CLI, and frames the implication for researchers: switching harness or model does not require learning a new way to think about the work — only a new set of commands for the same underlying approach. Vendor lock-in at the workflow level is shallower than it feels.

Conceptual trajectory of session 31

Session 31 makes explicit something the harness vocabulary section (A4) and the alternatives listing (A.adjacent.tools) had both implied without stating: the research practitioner who learns "give an LLM access to a folder and a project memory file" has learned a durable pattern, not a Claude-specific trick. This matters for the book's long-range usefulness — a researcher who internalises vendor-portability will not need to relearn the approach if they switch to Gemini CLI for institutional reasons, or to Aider for cost reasons, or to a local model for privacy reasons. The pattern survives the tool change. This is the same argument the book makes about markdown (use plain text, stay format-independent) applied one level up to the harness layer itself.

Session 32 — 2026-08-20

A short housekeeping session, prompted by a repo-hygiene review during unrelated student-guide/ work: three pre-gathered source files had been sitting in a stray root-level _sources/ directory since April, never filed into any book's convention.

New document: _meta/note.claude-vs-chatgpt-scoping-memory.md

A saved AI-generated transcript comparing Claude Desktop, Claude Code, and ChatGPT along two axes — bounded project scoping and memory persistence — moved here from the stray root directory. Its central distinction (Claude Code's "environment-centric memory": state lives in files and git history, not in the model, versus ChatGPT's "model-centric memory") has no external URL to cite, so it didn't fit C.resources.md's citation format; kept as a _meta/ reference note with clear provenance labeling instead of being discarded or forced into a format that doesn't fit it.

Revision: C.resources.md — new "CLAUDE.md and the .claude/ folder" subsection

Two blog posts from the same stray directory — "The Complete Guide to Claude Code: CLAUDE.md" (zhaozhiming, ai.gopubby.com) and "The Anatomy of the .claude/ Folder" (Avi Chawla, levelup.gitconnected.com) — were read and added as proper citation entries in a new subsection, placed after "Getting started with AI for research". Both cover ground the book already teaches natively (CLAUDE.md, .claude/ folder structure) but at a level of file-by-file detail the book itself doesn't need to go into — useful further reading rather than duplicated content.

Cleanup

The two source PDFs were deleted after citing (external, publicly linkable — no reason to store local copies against this book's convention of linking rather than hoarding). The now-empty root _sources/ directory was removed. sources-catalogue.csv regenerated to pick up the new C.resources.md entries. .gitignore gained __pycache__/ and *.pyc entries, prompted by unrelated build-script work in student-guide/ this same day.

Conceptual trajectory of session 32

Nothing conceptually new for the book's content — this session's value is entirely in not letting real material rot in a location no convention pointed at. The stray directory's contents were reasonable notes-to-self from an earlier working session, filed nowhere any future session would think to look. The distinction drawn while filing them (citable external content → link only; un-linkable local synthesis → keep the file, but relocate to where the book's own structure actually indexes it) is a small instance of a rule worth keeping generally: don't force content into a convention it doesn't fit just to make it "tracked" — find or shape the right place for it instead.

Session 33 — 2026-08-28

A review-driven session, opened by a DISSINET-accuracy audit (a forked subagent compiled every mention of DISSINET across the book, flagging which reads as a specific factual claim about the project's tools/practice versus generic audience framing — no file changes resulted, but it surfaced no inaccuracies requiring correction) and continuing through four smaller, unrelated fixes surfaced by direct questions during the same session: a funding acknowledgment, a missing harness, a missing glossary term, and an unattributed pattern.

New content: ERC/DISSINET funding acknowledgment

At the user's request, the hero-provenance block on the landing page (build/static/index.html, propagating to docs/research-augmented/index.html on build) gained a fourth line: the required ERC acknowledgment text for grant agreement No. 101000442 (Horizon 2020), alongside the existing "Originally developed for an internal DISSINET workshop" attribution. Rebuilt and republished to the live site immediately (this was the session's first of two rebuild/commit/push/republish cycles).

Revision: A.adjacent.tools.md — Hermes added to "Alternative coding harnesses"

The user asked whether the book covers agent harnesses in general and Hermes (hermes-agent.ai) specifically. The harness concept was already well covered (A4's dedicated section, this document's alternatives subsection profiling Aider/OpenCode/Gemini CLI/oh-my-openagent), but Hermes was absent. WebFetch against hermes-agent.ai established what it actually is — an open-source agent platform from Nous Research spanning terminal, messaging, and IDE surfaces, with persistent memory, cron jobs, browser automation, and multi-agent delegation, positioned closer to oh-my-openagent's meta-harness role than to a single-surface coding tool like Aider. A new paragraph was added after the oh-my-openagent entry, scoped accordingly. (A parallel lead — ncm.opentechlab.cz, a memory-persistence tool the user also flagged — was investigated and deliberately not added: its marketing claims, e.g. "hippocampal consolidation cycles" and a "48³ latent grid," read as unverified and it doesn't fit the harness section topically regardless; the user chose to skip it rather than redirect it to a memory-concept document.)

Revision: A4.conceptual-vocabulary.md and B.knowledge-curation.md — RAG glossary gap

A direct question — does the book cover RAG — found exactly one mention in the whole book: B.knowledge-curation.md's "The problem that RAG cannot solve" section, which uses the term in a critique without ever defining it, and no entry in A4's glossary despite that glossary covering context window, MCP, tokens, and harness at comparable technicality. A new "RAG (Retrieval-Augmented Generation)" entry was added to A4 between MCP and Skills/Tools, explicitly framing most existing AI-assisted research as already RAG-shaped whether or not the tool names it, and naming the structural limit (retrieval only surfaces what was written down) that motivates B.knowledge-curation's argument. B.knowledge-curation.md's first RAG mention now glosses inline and links back to the new entry.

While reading B.knowledge-curation.md for this fix, two dangling links to a A.projects.md file that has never existed in this repository's git history (not a rename casualty — never created, referenced as if it existed) were found and corrected to point to A9.markdown-project-memory.md, the document that actually matches the linked description ("practical CLAUDE.md architecture").

Revision: A.issue.research-wiki.md — Karpathy attribution and the Graphify addition

The user asked about "llm-as-wiki," the pattern Andrej Karpathy made famous, and Graphify, a tool implementing it — intending, initially, a new standalone document. Investigation (Karpathy's gist fetched directly, not just secondary blog summaries) found the book already had the full pattern in A.issue.research-wiki.md — three-layer structure, ingest/query/lint operations, even the Memex historical framing — written generically, without naming Karpathy as the source. Rather than duplicate that content in a new file, the existing document was extended: a paragraph naming and quoting the gist directly ("the wiki is a persistent, compounding artifact"; "Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase") was added just after the two-approaches framing, and the closing "reader spectrum" section's SwarmVault mention gained a companion paragraph on Graphify as the graph-first variant.

The Graphify paragraph required a correction mid-session: the first draft claimed Graphify's efficiency was essentially code-only, reasoning that its deterministic tree-sitter extraction has "nothing to grab onto" in prose. Checking Graphify's own repository README directly showed this was wrong — PDFs, documents, and images are supported inputs, processed via LLM extraction (the same fundamental step as the wiki pattern), with only code getting the free deterministic pass; the claimed token savings are a query-time effect on an already-built graph, not an ingestion-time one. The paragraph was rewritten to state the mixed-extraction reality accurately, and DISSINET's deposition-register corpus is in fact a supported Graphify input, not excluded from it as first written.

Cross-linking and navigation updates

_meta/_index.md gained two new entries via /update-index: RAG (Retrieval-Augmented Generation) in "Tools and modes" (after MCP), and Graphify in "Integrations and adjacent tools" (after Obsidian/Logseq). Hermes was deliberately not indexed, matching the existing precedent that oh-my-openagent — profiled in the same document at comparable depth — also has no dedicated index entry.

Conceptual trajectory of session 33

No new argument entered the book this session — every change was a gap-fill or a correction against something already claimed. The pattern worth naming is methodological rather than content-level: three of the four fixes were caught by treating a secondary source as provisional until checked against the primary one. The Graphify code-only claim came from search-result summaries and was wrong until the actual README was read. The A.projects.md links had presumably looked fine to whoever wrote them, because the description in the link text was plausible — only checking git history proved the file never existed. And the RAG gap was invisible until someone asked the book directly whether it was covered, rather than assumed from the table of contents. None of these are dramatic errors, but they are the specific kind that accumulate quietly in a maintained reference document and are cheapest to catch immediately rather than at the next full fact-check pass (cf. session 30's model-ID and context-window corrections, caught the same way).