← Vibe Researching hub  ·  中文版

How to Use This Handbook

This handbook is the participant companion for the two-hour workshop Vibe Researching with Coding Agents. It is not a transcript of the talk. It is a hands-on tutorial you can work through at your own pace, on your own machine, beginning from “Claude is not yet installed” and ending with a complete, verified, journal-ready paper draft built on real CFPS data.

You will see five things repeated on almost every page:

1. Goal — what you should be able to do by the end of the section.
2. What you type — exact commands, prompts, or code, formatted as fenced code blocks. If a line begins with $, type it in your terminal (without the $). If it begins with >, type it inside a running Claude Code session.
3. What you should see — abridged but real terminal output, so you know whether you are on track.
4. Inspect — the artifacts you should open and read after the agent finishes.
5. Stop and check — the question you should be able to answer before moving on.

The running example is a real one: a Social Forces-style paper on the Chinese digital divide, built from six waves of the China Family Panel Studies (CFPS, 2010–2020) using only Claude Code, Codex CLI, and the open-scholar-skill suite. Every command, every figure, every table, every verification finding shown in this handbook came from an actual run — including the seven critical errors that verification caught before the manuscript was sent anywhere. Those errors are the reason this workshop exists.

The handbook has four parts.

• Part I — Foundations (the first hour of the workshop): install the agents, open your first session, learn the project layout, write an agent-quality prompt, and tour the newer Claude Code capabilities — dynamic workflows, subagents, and automation (§5A).
• Part II — Open Scholar Skills, end to end (the second hour): a reference to all 44 skills — every mode, every argument, every gate, every file they write — organized in the order you would actually use them, with the CFPS digital divide as the concrete artifact at each step. §5B is the inventory table; read it first and come back to it.
• Part III — Orchestrators: when a single paper deserves the full pipeline (scholar-full-paper, scholar-auto-research), how to find your place again (scholar-resume), how to run a queue of ideas unattended (scholar-loop), how to audit the suite itself (scholar-auto-improve), and how to get an independent second opinion from a different vendor’s model (scholar-openai).
• Part IV — Responsible practice: the take-home checklist, common participant mistakes, and the five principles.

If you already use Claude or Codex, skim Part I and start at §5B (the skill inventory) or §6 (scholar-init). If you are completely new, do every step.

Using Part II as a reference. Each skill section follows the same shape: the argument-hint grammar copied verbatim from the skill’s own frontmatter, a table of every mode, the internal workflow, the exact files written, the gates that can stop you, and the documented gotchas. Where a rule exists because a real run failed, the failure is named and dated — those are the passages worth reading even if you never run that skill.

PART I — FOUNDATIONS

1. What “Vibe Researching” Is — and Is Not

“The moment an AI touches your files, we are no longer in the world of casual prompting. We are in the world of workflow design.”

Vibe Researching is the practice of using a coding agent (Claude Code or Codex CLI) to do bounded research tasks inside a real project, leaving inspectable artifacts behind, while a human keeps ownership of the question, the standards, and the accountability.

Vibe Researching is NOT:

• “Write me a paper on X.” (Asking the agent to invent the question, the data, and the framing all at once — guaranteed to produce a polished but hollow draft.)
• “Find me a significant result.” (Outsourcing both the hypothesis and the standard for evidence — this is p-hacking with extra steps.)
• “Just trust the output because it sounds smart.” (Polished prose is not validated prose.)

Vibe Researching IS:

• “Here is my data boundary, here is the research puzzle, here is what counts as evidence, here are the artifacts you must produce, here is when you must stop and ask me.” (You define scope, standard, and stop rules; the agent executes.)

The agent has three kinds of power

Treat permissions as method, not bureaucracy. The agent’s read boundary is your data boundary. Its network boundary is your privacy boundary. Its write boundary is your reproducibility boundary.

Claude vs. Codex — division of labor

In this handbook we use two agents on purpose, because we don’t want one model acting as author, analyst, and reviewer.

• Claude Code — the orchestrator. Strong at running multi-step skills, drafting prose, planning, project memory. We use it as the primary research workflow engine.
• Codex CLI — the external reviewer. Strong at code patches, statistical implementation, independent audit. We use it (later) as a second pair of eyes on the same scripts and tables Claude produced.

You do not have to use both on day one. Start with Claude.

2. Installing Claude Code and Codex

Goal: get to the point where typing claude or codex in your terminal launches a working agent.

2.1 Prerequisites

You need:

• macOS, Linux, or Windows (WSL2).
• Node.js ≥ 18 (we recommend 20 LTS) for Claude Code.
• A terminal (Terminal.app, iTerm2, or Windows Terminal).
• An Anthropic API key for Claude (or a Claude Pro/Max subscription) and an OpenAI API key for Codex.
• Optional: R 4.3+ and Python 3.11+, since most scholar-skills run analyses in those.

The lab notebooks find a key differently from Claude Code, and this trips people up. Claude Code and Codex each authenticate themselves. The four lab notebooks do not use either of those logins — they resolve a provider in this order, first one that works:

	Provider	How it is found
1	OpenAI (the workshop default)	OPENAI_API_KEY, else a one-line labs/openai.txt
2	Local Ollama	a server on 127.0.0.1:11434 — free, private, no key
3	Anthropic	ANTHROPIC_API_KEY
4	GLM / Z.ai	ZAI_API_KEY
5	offline	canned [OFFLINE FALLBACK] answers, so every cell still runs

So the usual fix for “The api_key client option must be set” in a notebook is one line, from the repository root:

printf '%s' 'PASTE_YOUR_KEY_HERE' > labs/openai.txt
chmod 600 labs/openai.txt

labs/openai.txt is gitignored and must stay that way. If you would rather spend nothing, run ollama serve instead and the notebooks will use it with no key at all. The full walkthrough is in the pre-workshop setup guide (teaching/03-pre-workshop-setup.md).

Windows users: The commands in this section assume macOS, Linux, or a Linux-like shell. If you are on Windows, do not try to run them in PowerShell or cmd.exe. Go to Appendix K — Windows setup walkthrough first and follow it through WSL2 (Windows Subsystem for Linux). Once you have a working Ubuntu shell inside WSL2, every command in §2 and §3 works unchanged. You only need to read Appendix K once per laptop.

Check your Node version:

$ node --version
v20.11.0

If node is missing or older than 18, install nvm and run nvm install 20.

Prefer not to install anything by hand? Once Claude Code or Codex is running (even with only Node installed), you can ask the agent to install Python, R, Git, and the standard social-science packages for you. See §2.7 — “Let the agent install your research toolchain” — for the exact prompts.

2.1A Accounts, plans, and keys — the three things people confuse

There are two different ways to pay, and they are not interchangeable. This trips up almost everyone, so read the last row twice.

The last row is the one that costs people an hour. A ChatGPT Plus subscription does not give you an API key, and a Claude Pro subscription does not give the lab notebooks anything to use. Subscriptions authenticate you to an app; the notebooks are your own Python calling an API, and that needs a key (or a local model — see §2.1).

Getting a Claude plan (for Claude Code). Go to claude.ai, sign up, then Settings → Plans. Pro is the entry tier; Max raises the usage limits, which matters on Day 3 when everyone runs agents at once. Then run claude and choose Login with Anthropic Console — no key needed.

Getting an Anthropic API key (the alternative). Go to console.anthropic.com → API Keys → Create Key, copy it immediately (it is shown once), and add credit under Billing — a new console has a zero balance and calls will fail with a billing error until you do. Current per-token rates are on the pricing page; as of August 2026 Claude Opus 5 is $5 / $25 per million input / output tokens and Claude Haiku 4.5 is $1 / $5.

Getting Codex working. Either sign in with a ChatGPT Plus/Pro account (codex login, then pick the browser sign-in), or create an OpenAI key at platform.openai.com/api-keys and paste it. OpenAI billing is separate from ChatGPT billing — the same warning about a zero balance applies.

What this workshop actually needs. Claude Code, by either route. Codex, by either route, and only on Day 4 for external review. The lab notebooks need an OpenAI API key in labs/openai.txt — or nothing at all if you run ollama serve, which is free and local and is what we recommend if you would rather not spend anything.

Cost, honestly. Four days of lab work on the default gpt-4o-mini is well under a dollar. The expensive thing is agents on Day 3–4, which is what a Max plan or a funded console is for. If you are paying out of pocket, run the labs on Ollama and spend your budget on the agent days.

2.2 Installing Claude Code

$ npm install -g @anthropic-ai/claude-code

Confirm:

$ claude --version
2.0.x

The first time you launch it, it will walk you through authentication:

$ cd ~/Documents/projects/digital-divide-china-cfps   # cd into your project FIRST
$ claude

You will see a welcome screen asking how you want to authenticate. Choose API key (paste from console.anthropic.com) or Anthropic Console (browser flow).

 ┌──────────────────────────────────────────────────────┐
 │  Welcome to Claude Code                              │
 │  Choose authentication method:                       │
 │   1) Login with Anthropic Console                    │
 │   2) Use ANTHROPIC_API_KEY                           │
 └──────────────────────────────────────────────────────┘

Always start Claude Code from inside the project directory. That directory becomes the working root, and Claude will only read/write inside it (subject to permissions).

2.3 Installing Codex CLI

Codex is OpenAI’s coding agent. We use it for external code review.

$ npm install -g @openai/codex
$ codex --version
codex-cli 0.130.0   # exact version as of 2026-05; yours may be newer

Authenticate once:

$ codex login
# Paste your OpenAI API key when prompted.

2.3A Desktop apps — a friendlier alternative to the CLI

Both vendors now ship a desktop application that bundles the same coding agent behind a window-based interface, so you can try the tools without ever touching npm or a terminal. If the CLI install above stalled — missing Node, PATH headaches, a locked-down work laptop — the desktop app is the fastest way to get a working agent in front of you.

Goal: have a working Claude Code or Codex agent running, by whichever path is least painful for your machine.

Claude Code desktop (macOS / Windows). Download the installer from the official page:

• https://claude.com/download

The desktop app includes Claude Code — you do not need to install Node.js or the CLI separately. Install it like any normal app (drag to Applications on macOS; run the .exe on Windows), launch it, and sign in with your Anthropic account (Pro/Max subscription or Console login). macOS 11 (Big Sur) or newer is required. The first-run walkthrough lives at https://code.claude.com/docs/en/desktop-quickstart.

Codex app (macOS / Windows). Download from OpenAI’s official page:

• https://developers.openai.com/codex/app

Pick the macOS build (Apple Silicon or Intel) or the Windows build; Windows users can also install it from the Microsoft Store. Open it and sign in with your ChatGPT account (Plus / Pro / Business / Edu / Enterprise — Codex is included) or an OpenAI API key. The app runs Codex threads in parallel and has built-in worktree, automation, and Git support.

What you should see: a window-based agent that can open a folder, read and edit files, run commands, and talk to git — the same capabilities as the CLI, with buttons instead of keystrokes.

A third desktop agent — ZCode (Z.ai). If neither vendor’s billing works for you, Z.ai ships ZCode, a desktop agent built on GLM-5.2 that reads Claude Code’s skills and can therefore run the open-scholar-skill suite. It is a different company’s product with its own configuration and its own data-jurisdiction implications, so it gets its own treatment: see §2.6.7.

Let the desktop install the CLI for you. You do not have to run the npm commands from §2.2 by hand. Once the desktop app is open, ask it in plain English — “Install the Claude Code CLI on my machine and walk me through signing in” — and the agent will check your Node version, run the installer, fix your PATH, and hand you a working claude command. It is the same agent that later sets up your whole research toolchain (§2.7); here it simply sets up its own terminal home.

…but for this workshop, please also install and use the CLI. The desktop apps are excellent for first contact and for day-to-day work, and you are welcome to keep using them afterward. The reason to spend ten minutes at the terminal too is not that the desktop is weak — by now it reads your files, runs code, remembers across a session, and connects to MCP servers, exactly like the CLI. The reason is a handful of things a graphical app structurally cannot do. A desktop needs a screen and a human clicking; the CLI is just text in, text out, so it runs anywhere a shell does:

• Headless & remote. The CLI runs over SSH on a lab server or an HPC cluster with no screen attached. When restricted data cannot leave a secure machine, you bring the agent to the data — impossible from a windowed app that needs a graphical desktop session.
• Scriptable. claude -p "…" drops into a shell script, a Makefile, or a cron job, so the agent becomes one automated step in a pipeline rather than a person clicking buttons.
• Unattended at scale. Long or parallel jobs launched under tmux/nohup outlive your session — two hundred model calls overnight with the laptop shut.
• Composes with Unix. Its input and output pipe and redirect straight into git, grep, R, and awk — it drops into the research-computing stack you already run.
• Text-reproducible. Every action is a command you can log, version, and rerun, so a colleague reproduces your exact workflow; a GUI click leaves no trace.

Two workshop-specific reasons reinforce this: everything you learn on the CLI transfers straight back to the desktop app (the reverse is not always true), and the materials assume the terminal — the plugin install (§2.4) runs a shell setup.sh, and hooks (§5A), .claude/settings.json, and MCP wiring are all demonstrated as copy-pasteable commands.

So: if the desktop app is how you get unstuck today, great — use it, or let it install the CLI for you. But do get claude (and ideally codex) working in a terminal too, because §2.4 onward assumes you can type commands at a $ prompt and > inside a session.

2.4 Installing the open-scholar-skill plugin

Skills are not built into Claude Code; you install them by cloning the repository and running its setup script. The repo at https://github.com/joshzyj/open-scholar-skill ships a .claude-plugin/ manifest plus a setup.sh that registers the skills, the agents, and the PreToolUse data-safety hook with Claude Code.

There are two ways to do this. If git, SSH keys, and shell scripts are new to you, use the beginner shortcut (§2.4.0) — ask Claude Code itself to do the install. If you’d rather see every command, follow the manual path in §2.4.1–§2.4.5.

Or install it as a plugin. The repo also publishes a marketplace manifest, so claude plugin marketplace add joshzyj/open-scholar-skill followed by claude plugin install open-scholar-skill@open-scholar gets you the skills and agents in two commands, and is the route ZCode uses (§2.6.7). It is not a substitute for setup.sh: the plugin cannot write the three things that live outside the repo — your .env with the Zotero and CrossRef settings, the executable bits on the skills’ shell scripts, and the PreToolUse data-safety hook in ~/.claude/settings.json. For the workshop, clone and run setup.sh; treat the plugin route as the fast path for a second machine where you will run setup.sh afterwards anyway.

Two editions — which one you have determines which skills exist.

Edition	Repo	Skills	Access
Public	github.com/joshzyj/open-scholar-skill	35	Open — this is what §2.4 installs
Extended	openscholarskills	44	Available on request — email the author

This handbook documents the extended edition, because that is the superset. Nine skills exist only there:

scholar-full-paper · scholar-resume · scholar-loop · scholar-presentation · scholar-image · scholar-grant · scholar-teach · scholar-book · scholar-exemplar-curate

Sections covering those carry an [Extended] tag. Everything else in Part II works identically on the public edition — including the entire analysis-to-verification core (scholar-init → scholar-design → scholar-analyze → scholar-write → scholar-verify → scholar-citation), which is where the workshop’s argument actually lives. On the public edition, run those skills individually in the order of Part II; the orchestrator in §21 is a convenience over that same chain, not a different method.

Check what you have at any time:

$ ls ~/.claude/skills/ | grep -c scholar     # 35 public · 44 extended

2.4.0 Beginner shortcut — let Claude Code install it for you

Once Claude Code is installed (§2.2) and running in any directory, paste this prompt:

> Please install the open-scholar-skill plugin from
>   https://github.com/joshzyj/open-scholar-skill
> into Claude Code on this machine. Clone it under
>   ~/.claude/plugins/open-scholar-skill
> run its setup.sh, install any missing dependencies (git, jq,
> python3), then verify the install by listing the scholar-*
> commands. Stop and ask me before running anything that needs
> sudo or that writes outside ~/.claude.

Claude will read the repo’s README, run git clone, execute setup.sh, install missing tools (pausing for your permission on each one), and confirm by calling /help. Anything that fails is reported with the exact error — you read the transcript instead of memorizing the steps. End state is identical to the manual path.

Safety rules for the shortcut

1. Start Claude Code in default permission mode (not bypassPermissions) so each install step still asks for your approval. Type Shift+Tab until the status line reads default if you are not sure.
2. If the agent proposes sudo, read what it intends to install before typing y. The shortcut should never need sudo for the plugin itself — only, possibly, for jq / python3 on Linux.
3. If the agent reports it cannot reach github.com or that a dependency install failed three times, switch to the manual path below — those failures usually need a human to debug your shell, proxy, or PATH.

When Claude finishes, jump to §2.4.4 to confirm the install, then move on to §3.

2.4.1 Prerequisite — git

The install uses git. Confirm it is installed and configured:

$ git --version            # any 2.x is fine
$ git config --global user.name  "Your Name"
$ git config --global user.email "you@example.com"

If git is missing:

• macOS: xcode-select --install (Apple’s git) or brew install git
• Ubuntu / Debian / WSL: sudo apt install git

For pulling private repos later, also add an SSH key:

$ ssh-keygen -t ed25519 -C "you@example.com"
$ cat ~/.ssh/id_ed25519.pub
# Paste the public key into github.com → Settings → SSH and GPG keys.

2.4.2 Install — clone and run setup

$ git clone https://github.com/joshzyj/open-scholar-skill.git
$ cd open-scholar-skill
$ bash setup.sh

setup.sh will:

1. Create the .claude/skills/ and .claude/agents/ symlinks the plugin uses internally.
2. Auto-detect your Zotero library, or prompt you for the path if it cannot find one.
3. Optionally configure BibTeX, EndNote, and a CrossRef email for the polite API pool.
4. Install every skill in your edition (35 public · 44 extended) and its agents as personal skills in ~/.claude/skills/ and ~/.claude/agents/ — so /scholar-* works in every Claude Code session, in any directory, not just the cloned repo.
5. Register scripts/gates/pretooluse-data-guard.sh as a PreToolUse hook in ~/.claude/settings.json. The hook intercepts every Read, NotebookRead, NotebookEdit, Grep, and Glob call and refuses files whose .claude/safety-status.json entry is NEEDS_REVIEW:* or HALTED.
6. Write a .env file recording your configuration.

Requirements: bash, python3, jq. Install jq first — the data-safety hook fails closed without it, which means every data read gets blocked until you do. Presidio, used for NER-based PII detection, is optional: python3 -m pip install presidio-analyzer presidio-anonymizer.

If setup.sh reports a missing dependency, install it (brew install jq on macOS; sudo apt install jq python3 on Linux) and re-run.

Step 2 is the one people skip, and it silently degrades half the suite. The reference library detected here is what scholar-write drafts against, what scholar-citation verifies against at Tier 1, what scholar-lit-review searches before it touches the web, and what scholar-exemplar-curate harvests paragraph exemplars from. Get it wrong and nothing errors — you just get web-only citations and generic prose. §14.0 shows how to verify it took.

2.4.3 Update later

$ cd open-scholar-skill
$ git pull
$ bash setup.sh    # idempotent — refreshes symlinks and hook registration

2.4.4 Verify

Start Claude Code from any project directory and type:

> /help

You should see a long list of scholar-* commands. Quick check:

> /scholar-init --help

If it prints a help summary, you are ready for §3.

2.4.5 Troubleshooting

• Skills missing from /help — symlinks didn’t install. From the cloned repo, run bash setup.sh again and watch for the ▸ Checking symlinks... block.
• PreToolUse hook blocks an unexpected file — that is the data-safety guard working. Resolve it with /scholar-init review (the review mode is owned by scholar-init, not scholar-safety). Do not disable the hook.

• Behind a corporate proxy — clone via HTTPS with an explicit token:

  $ git clone https://<token>@github.com/joshzyj/open-scholar-skill.git
  

  Or download the repo as a ZIP and extract it before running setup.sh.

2.5 What setup.sh actually does — a walk-through

Goal: know what to expect before you run it, what each of the seven prompts is asking, and how to tell afterwards whether it worked.

setup.sh is interactive. It asks six or seven questions, and every one of them can be skipped by pressing Enter. It is also idempotent — re-running it is safe and is the documented way to repair a broken install. Budget three minutes.

One design note that explains a lot of its behaviour: the script deliberately does not use set -e. Its own header says why — the interactive read prompts return non-zero on EOF (piping /dev/null, or running it in CI), and under set -e that would abort the install halfway through. Instead each step checks its own exit status and continues best-effort. The consequence for you: a warning mid-run does not mean the install failed, and you have to read the summary at the end rather than assuming silence is success.

2.5.1 The seven steps, in order

1 — Symlinks. ▸ Checking symlinks... creates two repo-local conveniences, skills/ → .claude/skills/ and agents/ → .claude/agents/. If one exists but points somewhere unexpected it is repaired; if a real directory sits at that name, the script refuses to delete it and tells you to move it yourself. It will not destroy your files to make room.

2 — Zotero auto-detection. ▸ Looking for Zotero library... probes seven locations, in order, for a zotero.sqlite (or .sqlite.bak):

~/Zotero                              ~/Library/CloudStorage/*/zotero
~/Documents/Zotero                    ~/Library/CloudStorage/*/Zotero
~/snap/zotero-snap/common/Zotero      ~/Google Drive/zotero
                                      ~/Google Drive/Zotero

Then it asks:

  Auto-detected Zotero at: /Users/you/Zotero
  Use this path? [Y/n] or enter a different path:

Three valid answers: Enter or Y accepts, n skips Zotero entirely, or you paste a different path. If you paste a path that does not exist, it warns and keeps the auto-detected one rather than silently accepting a broken path. If nothing was found at all, it asks you to type a path and skips on empty input.

3 — Optional reference managers. Four prompts in a row, each skippable with Enter:

4 — Knowledge graph directory. Defaults to ~/.claude/scholar-knowledge; press Enter to accept. This is the user-scoped, cross-project graph from §8C — one graph for all your papers, deliberately not inside any project.

5 — jq check, then Presidio. ▸ Checking jq... is the step to actually read:

  ⚠ jq is NOT installed.
    ... the guard falls back to a minimal sed-based parser and fails CLOSED
    on data files — every Read of a .csv/.dta/.xlsx will be blocked
    with "install jq" until jq is available.

That is not a soft warning. Without jq the data guard blocks every data read. Install it and re-run.

Presidio is then offered for NER-based PII detection (names, addresses, entities) on top of the built-in regex patterns. It needs roughly 500 MB and defaults to no. If you accept, the script installs presidio-analyzer, presidio-anonymizer, and spaCy’s en_core_web_lg, then smoke-tests that presidio_anonymizer actually imports — because a successful pip install is not proof the package works on that interpreter. Declining is fine; regex detection is used instead, and you can install it later.

6 — The .env file. Before writing, an existing .env is copied to .env.bak.<timestamp> and you are told to re-apply any manual additions. The script never silently clobbers a file you may have hand-edited. The result:

SCHOLAR_SKILL_DIR="/path/to/open-scholar-skills"
SCHOLAR_ZOTERO_DIR="/Users/you/Zotero"
SCHOLAR_BIB_PATH=""
SCHOLAR_ENDNOTE_XML=""
SCHOLAR_CROSSREF_EMAIL="you@university.edu"
HF_TOKEN=""
SCHOLAR_KNOWLEDGE_DIR="/Users/you/.claude/scholar-knowledge"

7 — Installing as personal skills. This is what makes /scholar-* work in every directory. It creates one symlink per skill and per agent inside ~/.claude/skills/ and ~/.claude/agents/ — rather than replacing those directories with a single link to the repo. Three consequences, all good:

• A skill of your own already at ~/.claude/skills/my-thing/ is untouched; the scholar-* entries install alongside it.
• If a real (non-symlink) directory already occupies a scholar-* name, the script skips it and says so rather than deleting your content.
• Uninstalling is just deleting the scholar-* symlinks.

Then three smaller steps run without asking anything:

• chmod +x repair. Helper scripts that lost their executable bit — which happens on cloud-sync mounts and ZIP downloads, though not on a fresh git clone — get it restored. Only files starting with a #! shebang are touched; sourced helpers are deliberately left non-executable.
• The PreToolUse hook. scripts/gates/pretooluse-data-guard.sh is merged into ~/.claude/settings.json with jq — additively and idempotently, preserving every other key you have configured, and replacing rather than duplicating an existing scholar entry. The command is written quoted, which is what makes it survive a path containing spaces (§6.4).
• Bootstrap files. ~/.claude/scholar-skills.path (a one-line absolute path, chmod 600) and a copy of scholar-skill-bootstrap.sh, so skills can find the repo from any working directory even with SCHOLAR_SKILL_DIR unset.

Finally it offers to append export SCHOLAR_SKILL_DIR="..." to your ~/.zshrc (or ~/.bashrc / ~/.bash_profile), detecting your shell. Accept unless you manage your profile some other way.

2.5.2 Reading the summary — the one line that matters

═══════════════════════════════════════════════════
  Setup Complete
═══════════════════════════════════════════════════

  SCHOLAR_SKILL_DIR=/path/to/open-scholar-skills
  Zotero:     /Users/you/Zotero

  Next steps:
  1. Source your shell profile or open a new terminal
  2. Try from any project: /scholar-idea "your research question"

If the safety hook could not be installed, the banner says so instead — and the script exits non-zero:

  Setup Complete (WARNING: safety hook NOT installed)

  The PreToolUse data-safety hook could not be installed.
  Raw data files will NOT be automatically guarded.

That exit code is the machine-readable signal. If you script the install, check it:

$ bash setup.sh || echo "SAFETY HOOK MISSING — install jq and re-run"

2.5.3 Verify it took

$ ls ~/.claude/skills/ | grep -c scholar        # 44
$ ls ~/.claude/agents/ | wc -l                  # 22
$ cat ~/.claude/scholar-skills.path             # the repo path
$ jq '.hooks.PreToolUse' ~/.claude/settings.json | head    # the guard
$ cat "$SCHOLAR_SKILL_DIR/.env"                 # your configuration

Then, in a new terminal (so the profile export is live), from a directory that is not the repo:

> /scholar-idea does hukou status shape internet use in urban China?

If the skill runs from an unrelated directory, the personal-skills install worked. If /help does not list the scholar skills, re-run bash setup.sh and watch the ▸ Checking symlinks... block for errors (§2.4.5).

Stop and check. Open ~/.claude/settings.json and find the PreToolUse entry. Is the script path wrapped in quotes? If your install lives under a path with a space in it — My Drive, Application Support — an unquoted command silently never fires, and you would have no guard at all while believing you did.

2.6 Running the workflow on GLM, DeepSeek, or a local model — including Z.ai’s ZCode

Goal: keep using the same Claude Code CLI, the same open-scholar-skill plugin, and the same project layout, but route the model calls to a different backend — Z.ai/GLM, DeepSeek, or a model you run on your own machine.

You do not need to install another CLI, swap your scripts, or hand-edit JSON before every session. Claude Code reads two environment variables — ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN — and will talk to any provider that exposes an Anthropic-compatible endpoint. GLM (Z.ai and the mainland BigModel host) and DeepSeek both do. For genuinely local models (DeepSeek-R1 distilled, Qwen2.5-Coder, Llama, GLM), Claude Code still needs an Anthropic-compatible front: Ollama, vLLM, and llama.cpp all speak OpenAI-style APIs, so you put a small translation layer — claude-code-router or litellm — in front to re-shape their responses into the Anthropic schema; the rest of the workflow is identical.

Options A–C below all keep Claude Code and swap the model underneath it. §2.6.7 covers the other direction: ZCode, Z.ai’s own agent app built around GLM-5.2, which replaces the harness and the model — and which reads Claude Code’s skills, so the open-scholar-skill suite runs inside it too.

2.6.1 Provider snapshot

The full ANTHROPIC_BASE_URL for Z.ai is https://api.z.ai/api/anthropic; for BigModel it is https://open.bigmodel.cn/api/anthropic; for DeepSeek it is https://api.deepseek.com/anthropic. The trailing /anthropic segment is what makes these endpoints route to the compatibility shim — leaving it off is the most common configuration error.

Model names move fast. The model IDs in this section (glm-5.2, glm-4.7, deepseek-v4-pro, and the rest) are illustrative. Before a session, check the provider’s current model list — Z.ai/BigModel and DeepSeek each publish their own — and use the exact names your account can call; pasting a retired tag is the second most common error after dropping the /anthropic suffix. GLM in particular has moved fast: glm-5.1 was the flagship when the first edition of this handbook was written and glm-5.2 replaced it in June 2026, bringing a 1M-token context window. If you copied the old three-line block into settings.json, update it.

2.6.2 Option A — declare a backend in ~/.claude/settings.json

This is the simplest setup: you point Claude Code at one backend, save the file, and every new session uses it until you change it.

GLM example:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your_zai_key",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "API_TIMEOUT_MS": "3000000"
  }
}

This is Z.ai’s own recommended mapping: GLM-5.2 for both the Opus and the Sonnet tier, the cheaper glm-4.7 for the Haiku tier that Claude Code uses for small background calls. CLAUDE_CODE_AUTO_COMPACT_WINDOW tells Claude Code it may fill GLM-5.2’s 1M-token window before auto-compacting — leave it out and you compact far earlier than you need to, which matters when the agent is holding a codebook and three scripts at once.

DeepSeek example:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your_deepseek_key",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash"
  }
}

Restart Claude Code; run /usage or just trigger any tool call to confirm the backend has switched.

2.6.3 Option B — keep keys outside the project and switch with shell functions

Hand-editing settings.json before every workshop is painful and tends to leak keys into git. Instead, keep all your provider keys in ~/.api-keys (chmod 600), source it from ~/.zshrc or ~/.bashrc, and define small shell functions that export the right environment and then launch claude:

# ~/.api-keys (NOT committed anywhere)
export ANTHROPIC_API_KEY="sk-ant-..."
export ZAI_API_KEY="..."
export DEEPSEEK_API_KEY="..."

# ~/.zshrc
[ -f ~/.api-keys ] && source ~/.api-keys

glm() {
  export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"
  export ANTHROPIC_AUTH_TOKEN="$ZAI_API_KEY"
  export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-5.2"
  export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-5.2"
  export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.7"
  export CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000
  export API_TIMEOUT_MS=3000000
  claude "$@"
}

deepseek() {
  export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
  export ANTHROPIC_AUTH_TOKEN="$DEEPSEEK_API_KEY"
  export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro"
  export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro"
  export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
  claude "$@"
}

claude-anthropic() {
  unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN
  unset ANTHROPIC_DEFAULT_SONNET_MODEL
  unset ANTHROPIC_DEFAULT_OPUS_MODEL
  unset ANTHROPIC_DEFAULT_HAIKU_MODEL
  unset CLAUDE_CODE_AUTO_COMPACT_WINDOW API_TIMEOUT_MS
  claude "$@"
}

From then on, glm opens Claude Code against Z.ai, deepseek opens it against DeepSeek, and claude-anthropic falls back to vanilla Anthropic. The PATH binary claude itself is still the one CLI you trust.

2.6.4 Option C — CC Switch, a one-click GUI for provider switching

Options A and B edit configuration by hand. If you juggle several providers or accounts — an Anthropic login for one project, GLM and DeepSeek for others, a Kimi key for a collaborator’s repo — a GUI that makes those same edits for you is less error-prone. CC Switch is a cross-platform desktop app that manages provider configurations for Claude Code (and Codex, Gemini CLI, Claude Desktop, and more) from one window, with 50+ built-in provider presets and a system-tray menu for instant switching. It is an open-source, third-party tool — not an Anthropic product.

Install.

# macOS (Homebrew) — signed and notarized
brew install --cask cc-switch

# Linux (Arch)
paru -S cc-switch-bin

On Windows, download the .msi installer (Windows 10+); on other Linux distributions, the .deb, .rpm, or universal .AppImage. All builds are on the official releases page:

• Website: https://ccswitch.io
• Downloads: https://github.com/farion1231/cc-switch/releases

How it works. CC Switch keeps your provider definitions in a local SQLite database at ~/.cc-switch/cc-switch.db and, when you switch, writes the matching values into the live tool config — the same ~/.claude/settings.json env keys you set by hand in Option A — using atomic writes with rotating backups in ~/.cc-switch/backups/. Claude Code supports hot-switching without a restart; for the other CLIs you restart the terminal after switching.

Add and switch, in four steps.

1. Add Provider → choose a preset (Anthropic official, GLM/Z.ai, DeepSeek, Kimi/Moonshot, …) or enter a custom base URL + key.
2. Select the provider and click Enable — or pick it from the tray menu for an instant switch.
3. Restart the terminal (not needed for Claude Code) and run any tool call or /usage to confirm the backend changed.
4. To return to your Anthropic login, enable the “Official Login” preset, restart, and sign in normally.

Two cautions — the workshop’s data-boundary rules still apply.

• It stores your API keys unencrypted in ~/.cc-switch/cc-switch.db. Treat that file like any credential store: not on a shared lab machine, not in a synced or backed-up folder you don’t control, never in git. On a borrowed computer, prefer Option B (keys in ~/.api-keys, chmod 600) or clean up afterwards.
• Many presets are community relays, not the vendor’s own endpoint. A relay sees every prompt you send it — including participant text. Before routing a project with sensitive data through any non-official backend, run the trust checks in §2.6.6, and for restricted data prefer an official channel or a provider you have vetted.

CC Switch does not replace Options A/B — it automates them behind a UI. Everything else (the plugin, CLAUDE.md, the permission gates) is unchanged.

2.6.5 Running models locally

If your institution forbids sending data to a hosted API, or you want offline reproducibility, you can run a local checkpoint and route Claude Code to it. The catch: Claude Code speaks the Anthropic Messages API, while local servers (Ollama, vLLM, llama.cpp) speak OpenAI-style chat completions, so you put a thin translation layer in between. claude-code-router (CCR) is the lightest option: it speaks OpenAI-style chat completions to providers, so all three plug in as ordinary OpenAI-compatible backends — no per-server transformer required.

Path A — Ollama, fronted by CCR (simplest local route). Ollama exposes an OpenAI-style API (/v1/chat/completions) and its own native API — not the Anthropic /v1/messages format Claude Code expects — so it needs a shim in front, exactly like vLLM and llama.cpp:

# 1. Install Ollama (macOS / Linux / WSL).
$ curl -fsSL https://ollama.com/install.sh | sh
$ ollama --version

# 2. Pull a local model that fits your VRAM / RAM. Browse
#    https://ollama.com/library for current tags; these exist today:
$ ollama pull qwen2.5-coder:32b   # strong local coding model
$ ollama pull deepseek-r1:14b     # distilled reasoning model
#    GLM checkpoints also appear in the library — search "glm" there.

# 3. Front Ollama with CCR (install it in Path B). In `ccr ui`, add an
#    "ollama" provider with base URL http://localhost:11434/v1/chat/completions and your
#    pulled tag, then launch and select it:
$ ccr code
#    Inside the session: /model ollama,qwen2.5-coder:32b

Pointing ANTHROPIC_BASE_URL straight at http://localhost:11434 does not work: Claude Code would POST /v1/messages, which Ollama does not serve. The translation layer is what bridges the two schemas.

Path B — claude-code-router (CCR), install and routing. CCR is both the shim for a single local model (Path A) and the way to mix providers — different routes per tier (Opus to Z.ai, Sonnet to DeepSeek, Haiku to a local Ollama model), with manual mid-session switching via /model provider,model (add your own fallback logic with a custom router.js):

$ npm install -g @musistudio/claude-code-router
$ ccr ui          # opens a browser config editor and creates
                  # ~/.claude-code-router/config.json
$ ccr start       # launches the router service
$ ccr code        # launches Claude Code routed through CCR

There is no ccr config init; the config file is created the first time you run ccr ui (or ccr start/ccr code) and lives at ~/.claude-code-router/config.json. Edit the default and per-tier routes there or in ccr ui, then ccr restart to apply. Inside a CCR session, /model deepseek,deepseek-v4-pro or /model ollama,qwen2.5-coder:32b switches routes mid-conversation — the provider,model form is a CCR feature, not stock Claude Code.

vLLM / llama.cpp. If you already serve models with vLLM (vllm serve <model>) or llama.cpp (llama-server), they expose OpenAI-style chat completions, not Anthropic-style. vLLM ships its own Claude Code integration guide; otherwise put litellm, an anthropic-proxy, or CCR in front to translate the OpenAI ↔ Anthropic schemas. The Claude Code side never changes.

2.6.6 Workshop checks before you trust a backend

Open Scholar skills are not model-agnostic. They depend on long-context reading, tool use, and JSON-structured output. Before running the CFPS pipeline on a non-Anthropic backend, run this three-step smoke test:

1. Tool-use round-trip. In a sandbox project, prompt: “Read grades.csv, run a Python snippet to compute the mean, and write the result to out.txt.” A backend that silently skips the Bash call, hallucinates the file content, or returns the answer in prose without producing out.txt will fail every scholar-skill that depends on artifacts.
2. Long-prompt stability. Paste a 30-page CFPS codebook excerpt and ask the agent to extract variable names and waves. Backends with smaller effective context windows will start dropping later pages without warning.
3. Skill invocation. Run /scholar-init --slug smoke-test and /scholar-safety scan. If the model refuses to invoke the skill, returns a wrong path, or “forgets” the PreToolUse hook, do not use that backend for real data.

Record the result of each check in a one-line note in logs/backend-test.md. Do not advertise any tested model as fully compatible with the open-scholar-skill suite — say only that you ran the smoke test on a specific date and the listed skills passed.

Workshop rule. During the workshop itself, default to one backend per laptop. Switching providers mid-pipeline is the fastest way to produce two halves of a paper that disagree about CFPS variable definitions because the two models read the codebook differently.

2.6.7 Option D — ZCode, Z.ai’s own agent app, running the scholar skills

Options A–C keep the Claude Code CLI and swap the model underneath it. ZCode does something different: it is Z.ai’s own agent application, built around GLM-5.2, replacing the harness as well as the model. Z.ai calls it an Agentic Development Environment — a desktop app with a Goal mode for long multi-step tasks, browser automation, remote-development and phone-control channels. It is not an Anthropic product and it is not Claude Code; it is a separate program with its own configuration directory, ~/.zcode/.

The reason it belongs in this handbook is one design decision on Z.ai’s part: ZCode reads Claude Code’s skills, plugins, commands, and hooks. The open-scholar-skill suite you installed in §2.4 runs inside it, with GLM-5.2 doing the work. If your department cannot fund an Anthropic subscription, or you need a mainland-China billing path, this is the shortest route from “no Claude budget” to “the scholar pipeline runs on my laptop.”

Which option do you want?

Parts II–IV of this handbook assume a $ prompt and /scholar-* commands. Under ZCode the skill files are the same, but invocation, project memory, and hooks all differ. Read the three “difference” blocks below before you start the CFPS run in ZCode; the third one is a safety issue.

Install. ZCode is a desktop app — macOS (Apple Silicon and Intel), Windows (x64 and ARM64), Linux (x64 AppImage). There is no npm install. Download from the official install page, which always carries the current version:

• English docs: https://zcode.z.ai/en/docs/install
• 中文文档: https://zcode.z.ai/cn/docs/install

# macOS — open the .dmg, drag ZCode.app to /Applications.
# If Gatekeeper blocks it on first launch:
$ xattr -dr com.apple.quarantine /Applications/ZCode.app

# Linux — make the AppImage executable and run it
$ chmod +x ZCode-*.AppImage && ./ZCode-*.AppImage

On Windows, run the .exe installer and follow the wizard.

Connect a model. First launch asks for a workspace folder and a model connection. Three routes, and the right one depends on where you are:

• Z.ai account (international) — sign in; a GLM Coding Plan entitlement covers usage. Coding endpoints are https://api.z.ai/api/coding/paas/v4 (OpenAI-style) and https://api.z.ai/api/anthropic (Anthropic-style).
• BigModel (mainland China) — the Zhipu platform, same GLM models: https://open.bigmodel.cn/api/coding/paas/v4 and https://open.bigmodel.cn/api/anthropic.
• API key — any Anthropic- or OpenAI-compatible provider. ZCode’s own list includes Anthropic, OpenRouter, Moonshot, OpenAI, MiniMax, and custom endpoints, so you can run the ZCode interface against a Claude model if you want to compare harnesses while holding the model fixed.

The selectable GLM models are GLM-5.2 (the flagship, 1M-token context) and GLM-5-Turbo; anything else depends on your account’s permissions. Do not substitute the general endpoint for the coding endpoint — they are region- and billing-specific and are not interchangeable. This is the ZCode equivalent of dropping the /anthropic suffix in §2.6.1: the same category of one-line mistake, with the same symptom of nothing working and no useful error.

Confirm the connection the way Z.ai’s own quickstart does — ask the agent to list the files in the current directory. If it comes back with your real filenames, both the model and the tool loop are live.

Getting open-scholar-skill into ZCode. Three routes. Take the first one; the other two are there for when you already have a Claude Code install you would rather reuse, or when something does not register and you want to see the files with your own eyes.

Route 1 — the plugin store (do this one). The repo publishes a marketplace manifest, so ZCode can install it in one step, and a plugin install registers all of its component types at once — skills/, commands/, agents/, .mcp.json, hooks/hooks.json — which is what makes this the only route that brings the reviewer, code-review, and verification subagents along without extra work.

Open Settings → Plugins, click Create → Add marketplace in the top right, and enter:

joshzyj/open-scholar-skill

ZCode validates the manifest before adding it. The marketplace then appears in the Personal segment as open-scholar; find the open-scholar-skill card and click Install. Newly installed plugins are enabled by default, and enabling one reloads the agent runtime immediately — no restart. Later, the gear icon above the search box opens Marketplace sources, where you refresh to pick up new skills after an upstream release.

The same manifest works in Claude Code, if you would rather install by plugin than by setup.sh:

$ claude plugin marketplace add joshzyj/open-scholar-skill
$ claude plugin install open-scholar-skill@open-scholar

Still run bash setup.sh (§2.4.2) once, even after a plugin install. The plugin gives you the skills and agents. It does not give you the three things setup.sh writes outside the repo: the .env with your Zotero, BibTeX, and CrossRef settings (§2.5.1); the executable bits on the skills’ shell scripts; and the PreToolUse data-safety guard. That last one you must declare in ZCode by hand in any case — see Difference 3 below.

Route 2 — import an existing Claude Code install. If you already ran setup.sh, ZCode detects skills installed for Claude Code — and for Codex CLI, OpenClaw, Augment, and Windsurf — and offers to bring them in. Go to Settings → Skills → import, and choose symlink mode so a later git pull in the skill repo updates ZCode too; copy mode freezes a snapshot instead. Imported skills behave exactly like ones you write by hand in ~/.zcode/skills/<name>/SKILL.md. Note that this route covers skills only — the subagents need Route 1 or Route 3.

Route 3 — symlink by hand. The fallback when a registration misbehaves and you want to place every file yourself:

$ SRC="${SCHOLAR_SKILL_DIR:-$HOME/open-scholar-skill}"   # wherever you cloned it
$ mkdir -p ~/.zcode/skills ~/.zcode/agents
$ for d in "$SRC"/.claude/skills/*/;   do ln -sfn "$d" ~/.zcode/skills/"$(basename "$d")"; done
$ for f in "$SRC"/.claude/agents/*.md; do ln -sfn "$f" ~/.zcode/agents/"$(basename "$f")"; done
$ ls ~/.zcode/skills | wc -l      # should match: ls ~/.claude/skills | wc -l

Then Settings → Skills → Refresh. Whichever route you take, note that ZCode subagents are user-level only — there is no per-workspace agents directory, so every project on that machine sees the same reviewer panel.

Difference 1 — how you invoke a skill. In Claude Code you type /scholar-init. In ZCode, / is for commands (/goal, /compact, and anything in ~/.zcode/commands/), and skills are referenced with $:

$scholar-init initialize a project for the CFPS digital-divide paper

Type $ to open the skill picker, or use the Skills group in the slash menu. Subagents are referenced with @, or the main agent delegates to them on its own. Every /scholar-* command in Parts II–IV becomes $scholar-* here; nothing else about the prompt changes.

Difference 2 — CLAUDE.md is not read. ZCode takes project instructions from AGENTS.md: a user-global ~/.zcode/AGENTS.md, then an AGENTS.md in the workspace root, appended in that order. CLAUDE.md is used only once, during onboarding, as a one-time migration source — it is not re-read at runtime. So the project brief you write in §3.3 has to be copied over:

$ cp CLAUDE.md AGENTS.md     # in the project root — then keep the two in sync

ZCode does not merge AGENTS.md files across directory levels, does not scan child directories, and does not expand @import. Put the data-boundary rules — the Forbidden block from §3.3 — at the top of the workspace AGENTS.md, where they cannot be missed.

Difference 3 — the safety hook must be re-declared. This is the one that can hurt you. setup.sh registers the PreToolUse data guard in ~/.claude/settings.json. ZCode never reads that file. Until you declare the hook yourself, ZCode runs with no data guard at all, and the failure is silent: the agent reads a restricted file, nothing blocks it, and you find out later or not at all.

The good news is that ZCode’s hook contract is close enough to reuse the same script unmodified. ZCode writes one line of JSON to the hook’s stdin and its payload, in Z.ai’s own words, “carries both ZCode camelCase fields and Claude Code snake_case aliases, so legacy plugins can keep reading snake_case” — which is exactly what pretooluse-data-guard.sh parses (.tool_name, .tool_input.file_path, .cwd). Exit code 2 blocks the call, the same convention Claude Code uses.

Declare it in ~/.zcode/cli/config.json for all projects, or <workspace>/.zcode/config.json for one:

{
  "hooks": {
    "enabled": true,
    "events": {
      "PreToolUse": [
        {
          "matcher": "Read|NotebookRead|NotebookEdit|Grep|Glob|Bash|Edit|Write|MultiEdit",
          "hooks": [
            {
              "type": "command",
              "command": "bash '/Users/you/open-scholar-skill/scripts/gates/pretooluse-data-guard.sh'",
              "timeoutMs": 10000
            }
          ]
        }
      ]
    }
  }
}

"hooks.enabled": true is required — without it nothing fires. Quote the script path if it contains a space; the §2.5.3 warning about My Drive applies here word for word.

Then prove that it fires, because a matcher naming a tool ZCode calls something else fails open and looks identical to a working guard:

> read data/raw/cfps2020_adult.dta and show me the first five rows

You want a refusal that cites the guard. If the file is read, the hook is not wired. Stop there, fix it, and do not put restricted data in front of ZCode until you have watched a deliberate read get blocked. Write the result into logs/backend-test.md next to the §2.6.6 checks.

Before you trust it with the pipeline. ZCode changes the harness and the model, so both halves of §2.6.6 apply: run the three-step smoke test (tool-use round-trip, long-prompt stability, and skill invocation — with $scholar-init rather than /scholar-init), plus the hook test above. Note the date and exactly which skills passed. Do not describe the suite as “ZCode-compatible” on the strength of one smoke test; say what you ran and when.

Two data-boundary notes, and they are not optional. First, GLM calls through Z.ai or BigModel are processed under Chinese law whichever host you choose. For restricted, IRB-governed, or DUA-bound participant data, that is a question for your IRB and your data-use agreement, not a matter of preference — the same standard §2.6.4 applies to community relays. Second, ZCode’s extras — browser automation, remote development, the phone and bot channels — widen the surface that can reach into your project directory. Enable only what you need, and keep the §4 layout so raw data sits outside anything an automation touches by default.

2.7 Let the agent install your research toolchain

Goal: once claude (or codex) launches, let the agent do the rest of the install work — Python, R, Git, system build tools, and the standard social-science package stacks (tidyverse, pandas, statsmodels, scikit-learn, etc.). You read the proposed commands, approve them one at a time, and you end up with a reproducible install log you can re-use on another laptop.

The agent is good at this for three reasons: it picks the right package manager for your OS (brew vs. apt vs. winget vs. choco), it sequences dependencies correctly (system libraries first, then language runtime, then packages), and it leaves a record of every command it ran in the transcript.

2.7.1 Before you ask — set the safety expectation

System installs touch shared state. Tell the agent the rules before you ask it to do anything:

> I'd like you to help me install a social-science research toolchain
> on this machine. Before you do anything destructive, follow these rules:
>
>   1. Detect the OS and the package manager first; tell me what you found.
>   2. Propose every install command before running it. Do not run anything
>      under `sudo` without explicit approval each time.
>   3. Use the user-scoped installer when one exists (rustup, pyenv, rbenv,
>      conda --user, renv, R user library) instead of mutating system Python
>      or system R.
>   4. After each install step, run a `--version` check so we can confirm
>      it worked before moving on.
>   5. Append every command you ran to `logs/install.md` in this directory,
>      so I can re-run it on another laptop.
>
> Start by detecting the OS, the shell, and which of {python3, R, git, make,
> pandoc, quarto, jq} are already on PATH. Then show me what you found and
> wait for instructions.

Stay in default permission mode for this. Do not switch to acceptEdits or bypassPermissions — every sudo, brew install, apt install, or npm install -g should be a separate approval click.

2.7.2 The four prompts that cover 90 % of installs

Once the agent has a map of your machine, send these in order. Each one is small enough that you can read and approve every command.

(1) Git, SSH, and the system build tools.

> Please install or repair the basics needed for source builds and version
> control:
>
>   - git (latest stable from the system package manager)
>   - an SSH client and an ed25519 keypair at ~/.ssh/id_ed25519 if I don't
>     already have one (do NOT overwrite an existing key)
>   - GNU make, a C/C++ compiler, pkg-config, and curl
>   - jq (the open-scholar-skill PreToolUse hook needs it)
>
> On macOS use Homebrew (install it if missing). On Debian/Ubuntu/WSL use
> `sudo apt update && sudo apt install`. Show me each command first.
>
> After install, run `git --version`, `make --version`, `cc --version`,
> `jq --version`, and print my public key with `cat ~/.ssh/id_ed25519.pub`
> so I can paste it into GitHub.

(2) Python via pyenv + a project virtual environment.

We deliberately avoid sudo pip and avoid replacing the system Python. A per-user pyenv install plus a per-project .venv is the only setup that survives across OS upgrades.

> Install pyenv (or pyenv-win equivalent if we are on Windows native),
> use it to install Python 3.11.x as the user-default, and then, inside
> THIS project directory, create a `.venv` and install the standard social-
> science stack into it:
>
>   numpy, pandas, scipy, statsmodels, scikit-learn, matplotlib, seaborn,
>   pyarrow, jupyterlab, ipykernel, linearmodels, pyreadstat, openpyxl,
>   tqdm, requests, beautifulsoup4, lxml, plotnine, great_tables, ruff,
>   black, mypy, pytest
>
> Pin versions in `requirements.txt`. Register the venv as a Jupyter kernel
> called "vibe-py311". Print `python --version`, `pip list | head`, and the
> kernel list at the end.

If you’ll be doing computational social-science work (NLP, embeddings, LLM annotation, network analysis, geospatial), append:

> Also install: transformers, sentence-transformers, datasets, accelerate,
> tiktoken, openai, anthropic, spacy, nltk, gensim, networkx, igraph,
> geopandas, shapely, pyproj, rasterio, contextily, folium.
> Don't pull torch with CUDA unless I confirm I have an NVIDIA GPU; default
> to the CPU wheel.

(3) R + the social-science package stack.

R installs differ enough across OSes that letting the agent pick the route is easier than memorizing all four. The key prompt is “install into the user library so we don’t need sudo for every package.”

> Install R 4.4.x and RStudio (the free Desktop build). On macOS use the
> official CRAN .pkg; on Debian/Ubuntu/WSL use the CRAN apt repo
> (cran.r-project.org/bin/linux/ubuntu). After R is on PATH, create a
> user library at ~/R/library if it doesn't exist, point R_LIBS_USER at it
> in ~/.Renviron, and install these into the user library:
>
>   tidyverse, data.table, lubridate, janitor, haven, readxl, writexl,
>   here, fs, glue, scales, broom, modelsummary, gt, gtsummary, kableExtra,
>   flextable, officer, knitr, rmarkdown, quarto, tinytex,
>   fixest, lme4, sandwich, lmtest, marginaleffects, estimatr, sjPlot,
>   ggplot2, ggdist, ggrepel, patchwork, ggeffects, plotly, DT,
>   survey, srvyr, lavaan, psych, mice, naniar, VIM, future, furrr,
>   renv, usethis, devtools, remotes, languageserver, lintr, styler, testthat
>
> For computational social science add (only if I confirm): tidytext,
> stm, quanteda, text2vec, conText, igraph, tidygraph, ggraph, sf, terra,
> tmap, leaflet, gganimate.
>
> After install, run `R -e 'sessionInfo()'` and write the list of installed
> packages to `logs/r-pkgs.md` with versions.

(4) Quarto + a tiny LaTeX so PDF rendering works.

A surprising number of pipeline failures are “I drafted the paper but cannot render a PDF.” Get this out of the way early:

> Install Quarto (latest stable) and a minimal TeX distribution. On macOS
> and Linux/WSL prefer `quarto install tinytex` over a full MacTeX/TeXLive
> install (3 GB vs. 30 GB). After install, render `quarto check` and a
> 10-line hello.qmd → hello.pdf to confirm the toolchain works end to end.

2.7.3 Codex-flavoured prompts

The same prompts work with codex with minor wording changes — Codex is more terse about explaining what it is about to do, so add "Explain each command before running it" at the top of every prompt. Codex tends to prefer python -m venv over pyenv, which is fine on a clean machine but breaks badly if you already have a system Python that conflicts; the pyenv prompt above is the safer route.

2.7.4 Capture the install log

After all four prompts succeed, ask:

> Please consolidate everything you installed in this session into
> `logs/install.md`, organized by step (system tools → Python → R →
> Quarto/LaTeX). Include the exact commands, the versions reported by
> --version, and the OS / shell / architecture you detected at the start.
> I want to re-run this on a second laptop tomorrow.

That log is the artifact. If a colleague asks “how do I get set up?”, you hand them logs/install.md and Claude (or Codex) replays it on their machine.

2.7.5 What to not let the agent install

A few classes of software should always be installed by you, not by the agent:

• System-wide databases (Postgres, MySQL) — too easy to clobber an existing instance and wipe local data.
• Replacement shells or terminal emulators — the agent cannot easily restart its own shell, so changing it mid-session leads to confusing failures.
• GPU drivers and CUDA toolkits — these need a reboot and vendor-specific decisions.
• Anything that requires editing /etc/hosts, the firewall, or VPN clients.

For everything else — language runtimes, packages, command-line tools, build dependencies, document toolchains — letting the agent do the install with per-command approval is faster, more reproducible, and leaves a better paper trail than doing it yourself.

3. Your First Agent Session

Goal: run a 60-second session that touches a file, so you understand the request → propose → approve → artifact loop.

Make a sandbox:

$ mkdir -p ~/sandbox-vibe && cd ~/sandbox-vibe
$ printf "subject,score\nAnna,0.81\nBen,0.74\nCara,0.92\n" > grades.csv
$ claude

Inside Claude:

> Please read grades.csv and tell me the mean score and who scored above the mean.

You will see Claude propose a tool call. Read it before approving. A typical screen:

 Claude wants to use Read on /Users/you/sandbox-vibe/grades.csv
 ───────────────────────────────────────────────────────────
   path: /Users/you/sandbox-vibe/grades.csv
 ───────────────────────────────────────────────────────────
   [a] approve once   [s] always allow this dir   [n] deny

Type a. Then Claude will (perhaps) propose to run a Python or R snippet. Approve again if you trust it. The result:

 Mean score: 0.823
 Above mean: Cara (0.92)

That is the entire loop. Every scholar-skill session is just a longer version of this. The five elements you will repeat constantly:

1. Request — what you ask in plain language.
2. Propose — the agent’s planned action (Read, Bash, Edit, Write).
3. Approve / deny — your decision.
4. Artifact — the file or output produced.
5. Verify — your inspection of the artifact.

If you remember nothing else from the workshop, remember: the answer the agent prints is less important than the artifact and the trace it leaves behind.

3.1 Permission modes — quick orientation

Claude Code’s documented permission modes are default, acceptEdits, plan, auto, dontAsk, and bypassPermissions (six in total). Not all six are reachable in every session: auto requires an eligible account and a recent model, and dontAsk is only set with --permission-mode dontAsk — run /help to see what your build exposes. The two you will use most as a learner are:

• default — every tool / path prompts on first use. Stay here for sensitive data and first runs on a project.
• plan — a read-only “explore” mode where the agent must produce a written plan before it can edit or run anything. Use it before any destructive or expensive multi-step work.

Press Shift+Tab to cycle default → acceptEdits → plan (and into auto if your account is eligible); press it again to keep cycling. The full six-mode list and their safety implications are in §3.2 below: acceptEdits auto-accepts edits, auto runs everything behind a background safety classifier, dontAsk allows only pre-approved tools, and bypassPermissions skips every check.

/sandbox is not a seventh permission mode. It is easy to file it as one, and the two are answering different questions: a permission mode decides whether a tool call runs at all, while the sandbox decides what a Bash command can reach once it is running. They compose, and for restricted data you want both. The sandbox’s own auto-allow mode is likewise not the permission system’s auto mode — auto-allow skips the prompt because the OS boundary contains the command, whereas auto skips it because a classifier judged it safe. See §5A for the panel and both modes.

3.2 The commands you will use most

A note on accuracy. The list below was compiled against Claude Code v2.1.154 (released 2026-05-28 alongside Opus 4.8). The cadence is fast: between this handbook and your installed version, new commands may have shipped and old aliases may have been retired. Run /help in your installed version to see the live command list. The “Autonomy and multi-session” subsection covers commands added during the 2.x cycle, including the Dynamic Workflows research preview (/workflows) and the background-session work (claude --bg, /resume <bg-id>); if any of them is unrecognized in your installed version, treat it as a feature not yet shipped in your release. Where two names exist for the same command, the second one is an alias and works identically.

Setup and project memory

/init                Generate a CLAUDE.md project memory file
/permissions         Inspect or change tool permissions
/doctor              Diagnose configuration / installation issues
/usage   (or /cost)  Show token usage and dollar cost so far.
                     v2.1.149+: a /usage breakdown now categorizes spend
                     by skills, subagents, plugins, and MCP servers — use
                     it to spot which scholar-skill is your biggest cost
                     driver before you turn /effort xhigh on for the
                     whole pipeline.
/reload-skills       v2.1.152+: rescan ~/.claude/skills/ and the project
                     .claude/skills/ directory without restarting the
                     session. Useful right after editing a SKILL.md or
                     pulling a new open-scholar-skills version. A
                     SessionStart hook can set "reloadSkills": true so
                     the new skill is available in the same session.

Session control

/compact                       Summarize history to free context
/rewind  (or /undo)            Roll back to an earlier checkpoint
/resume  (or /continue) [id]   Resume a previous session
/recap                         One-line summary of this session
/rename <name>                 Give the current session a memorable name
                               (so /resume <name> finds it later)
/clear   (or /reset, /new)     Start a new conversation (keeps CLAUDE.md)
/exit    (or /quit)            Quit cleanly
Ctrl+C twice                   Cancel the current operation

Mobility — drive Claude from a phone or another machine

/remote-control  (alias: /rc)  Open the current local session to
                               claude.ai/code and the mobile app.
                               Execution stays on YOUR machine; only the
                               conversation is mirrored. Useful when you
                               start a long pipeline at the office and
                               want to monitor it from a coffee shop.

Closing the remote tab does not stop the local session; the agent keeps running on your machine until you /exit it locally.

Autonomy and multi-session — newer in Claude Code 2.x

These were added during the Opus 4.6 / 4.7 / 4.8 cycle. They change how a researcher can leave the agent running and supervise many sessions at once.

/goal <condition>             Set a completion condition. The agent works
                              across turns without re-prompting until the
                              condition is met, tracking elapsed time,
                              turn count, and token cost. Example:
                                /goal "all pre-analysis diagnostics pass
                                       and pre-mortem returns LOW-RISK"
                              Use it for clearly-scoped, multi-step work
                              that does not need a human between steps.

/workflows                    v2.1.154+ (Opus 4.8): the Dynamic Workflows
                              research preview. Ask Claude to design a
                              multi-step workflow and it writes an
                              orchestration script that dispatches tens
                              to hundreds of parallel subagents in the
                              background with a single resumable state.
                              `/workflows` opens the dashboard that lists
                              your runs (queued, running, completed,
                              failed) and lets you peek at any one. The
                              social-science use case: one workflow per
                              paper, each step a scholar-* skill, fan-
                              out at scholar-respond's reviewer panel,
                              fan-in at scholar-verify. Available on
                              Max, Team, and Enterprise plans and via
                              the API.

/bg   (alias: /background)    Move THIS session to background-agent mode.
                              The terminal returns to your shell prompt;
                              the agent keeps running on your machine,
                              just headless. Re-attach later from
                              `agent view` (below) or with
                              `/resume <session-name>`. Sessions started
                              via `claude --bg` from the shell appear
                              alongside interactive ones in
                              `/resume`, marked with `bg`.

/effort                       Open a slider to tune speed vs. reasoning
                              depth. The Opus 4.8 tiers you'll use:
                                  low  | high (default) | xhigh | max
                              (other levels exist; run /effort to see them)
                              Use `xhigh` on identification-strategy
                              memos, theory drafts, and adversarial
                              review passes; reserve `max` for the
                              hardest verification reruns where token
                              budget does not matter. Drop back to
                              `high` (or `low`) for routine edits —
                              `xhigh`/`max` are slow and expensive.

/focus                        Toggle between the normal compact
                              transcript and the verbose view that
                              shows every tool input/output. Verbose is
                              what you want when /scholar-verify or
                              scholar-code-review is running.

/code-review [--fix]          v2.1.152+: review the current diff.
                              `--fix` applies the agent's suggested
                              fixes to your working tree after the
                              review, with reuse, simplification, and
                              efficiency findings surfaced as commits-
                              in-waiting. Pair with `scholar-code-review`
                              when you want a 6-agent panel; use
                              `/code-review --fix` for the lighter
                              pre-commit pass.

/simplify                     v2.1.154+: cleanup-only review that
                              applies its own fixes — DRY-up duplicate
                              code, drop dead branches, tighten naming.
                              Run before `scholar-replication` so the
                              published replication package isn't
                              carrying the agent's first-draft
                              scaffolding.

To manage many background sessions at once, drop out of any one Claude session (/exit or close the tab) and run this in the shell instead:

$ claude agents       # if shipped in your installed Claude Code version

This is Agent View — a one-screen dashboard that lists every Claude Code background session on your machine, grouped by state (Needs Input, Working, Completed). From there you can dispatch a new session, peek at output without attaching, attach into one for follow-up, rename, or close it. Each background session is a full Claude Code conversation that persists across terminal restarts, managed by a supervisor process; the agent does not stop just because you closed iTerm. On macOS, background agents now survive Claude Code upgrades (v2.1.153+). If claude agents is not recognized in your installed version, fall back to running each session in its own terminal tab.

When you dispatch a new background session from the shell, you can pre-configure it without ever attaching:

$ claude agents \
    --add-dir ../shared-cache \
    --settings ./.claude/settings.bg.json \
    --mcp-config ./.claude/mcp.json \
    --plugin-dir ~/.claude/plugins/open-scholar-skill \
    --permission-mode acceptEdits \
    --model claude-opus-4-8 \
    --effort xhigh \
    --dangerously-skip-permissions   # only inside a worktree

Most workshop participants will never type the full flag set — but --model + --effort lets you fire a “high-effort Opus 4.8 + xhigh” background session for the theory pass while the foreground stays on claude-sonnet-4-6 for routine edits.

Workshop use cases:

• /goal for unattended skill chains (scholar-eda → scholar-analyze → scholar-code-review).
• /workflows for end-to-end paper orchestration: one dispatched workflow runs scholar-init → scholar-lit-review-hypothesis → scholar-design → scholar-eda → scholar-analyze → scholar-verify while you read morning email.
• /bg + agent view when you run two papers in parallel (one CFPS, one CGSS) and don’t want to mash two terminals.
• /effort xhigh only for the theory section and the identification memo; max only when scholar-verify keeps flagging the same numeric mismatch and you need the deepest re-check; switch back to high before drafting Results.
• /code-review --fix after every analysis-script edit; /simplify before you build the replication package.
• /focus verbose before any scholar-verify run, so you can see what each verification agent is reading.

Permission modes

Claude Code has six permission modes, all reachable through the same Shift+Tab cycle or the --permission-mode <name> CLI flag. The mode names below are the exact identifiers Claude Code uses.

Note on availability. All six modes are documented, but the two you can reach in a given session depend on your account and how you launched Claude Code. auto appears in the Shift+Tab cycle only when your account qualifies (all plans, a recent model such as Opus 4.6+/Sonnet 4.6, and — on Team/Enterprise — an admin has enabled it); dontAsk never appears in the cycle and is set only with --permission-mode dontAsk. Confirm what your build exposes with /help before relying on them in workshop demos.

Shift+Tab            Cycle default → acceptEdits → plan, then back.
                     auto slots into the cycle only when your account is
                     eligible; bypassPermissions joins it after you start
                     with an enabling flag; dontAsk never appears in the
                     cycle. The current mode name is shown in the status line.

/permissions         Open the interactive permissions UI to review and
                     edit the allow / ask / deny rules that the modes
                     consult.

You can also start Claude Code already in a particular mode:

$ claude --permission-mode plan        # start in plan mode
$ claude --permission-mode auto        # start in auto mode
$ claude --dangerously-skip-permissions
# Equivalent to --permission-mode bypassPermissions.

Auto mode and bypass mode — power tools, handle with care

auto and bypassPermissions change the consent model. Read this section before using either.

• auto — the agent executes a sequence of low-risk tasks autonomously, but still pauses on destructive or shared-state actions (git push, rm, PR comments, external API calls beyond your project). File edits and tool calls inside the project are auto-approved.
• bypassPermissions (a.k.a. the --dangerously-skip-permissions CLI flag) — every tool call is auto-approved, including destructive ones. The agent can run rm -rf (within the circuit-breaker’s limits), git reset --hard, push to remotes, or anything else without asking.

Safety rules — please read before enabling either.

1. Never use bypassPermissions on a project that contains data you cannot afford to lose. It is appropriate for sandbox repos, throwaway worktrees, or CI containers — not for your dissertation directory.
2. Run bypassPermissions in a git worktree, not your main checkout. A typical safe pattern:

   $ git worktree add ../sandbox-experiment -b experiment
   $ cd ../sandbox-experiment
   $ claude --dangerously-skip-permissions
   

   If the agent corrupts the sandbox, delete the worktree and start over. Your main branch is untouched.

3. Never combine bypassPermissions with scholar-safety LOCAL_MODE files. The whole point of LOCAL_MODE is that you confirm each Read; bypass mode defeats that. Run sensitive-data sessions in default or acceptEdits only.
4. auto is the safer middle ground. It lets the agent chain tasks without prompting on each edit, but still stops at destructive or external-effect operations. Use auto for routine implementation work, not for the first session on a sensitive project.
5. Always check /usage after a long autonomous run. auto and bypassPermissions are how surprise bills happen.

The general rule: the more autonomy you give Claude, the more important your project layout, permissions, and safety scan become. Bypass mode is not a substitute for scholar-init; it is a multiplier for whatever discipline already exists.

3.3 CLAUDE.md — your project’s persistent brief

Two sources write your project’s CLAUDE.md, and they cooperate rather than conflict:

1. Claude Code’s built-in /init writes a user-authored brief — your conventions, forbidden actions, journal target, project-specific notes.
2. /scholar-init and /scholar-full-paper Phase 0 each write an auto-managed block wrapped in <!-- scholar-full-paper:BEGIN auto-rules vN --> … <!-- END auto-rules -->. The block is idempotent + non-destructive — it preserves any user content outside the markers.

The auto-managed block has two profiles:

• Lean (v2-lean, ~50 lines) — written by /scholar-init Step 1.2.5. Carries only the rules that apply across every scholar-* skill: no destructive regex on manuscripts, Objectivity Mandate, data-safety stack + LOCAL_MODE scope, citation rules, cross-skill workflow rules (xelatex, viz_setting.R, file versioning, verification protocol).
• Full (v2-full, ~230 lines) — written by /scholar-full-paper Phase 0. Lean profile plus Pacing Discipline (10 rules + ASK/DO-NOT lists), G3 honest-stop template, G4 decision-trigger memory map, real-agent dispatch heuristic, per-phase contracts (Phase 11/5.5/10/10.5), manuscript-substance rules (Abstract + Limitations), provenance manifest discipline.

Upgrade direction is one-way. Lean → full happens automatically the first time you run /scholar-full-paper on a project. Full → lean is blocked — once orchestrator rules are loaded, /scholar-init re-runs do not strip them. This protects projects where the user has invoked the full pipeline at least once.

Order doesn’t matter: /init first then /scholar-init, or vice versa, both produce the same result (one user-authored block + one auto-managed block, separated by the markers). The auto-managed block refreshes on every scholar-init or scholar-full-paper run, so as the plugin’s rules evolve, your CLAUDE.md picks up the latest contract automatically.

This file is read into every future session in that directory. Use the user-authored portion (outside the markers) for things like:

# CLAUDE.md — digital-divide-china-cfps

## Data
- Raw CFPS waves (.dta) live in data/raw/. Never modify.
- Processed panel: data/processed/cfps-panel-long.rds. Built only by 01-build-sample.R.

## Conventions
- All R packages: tidyverse, fixest, marginaleffects. No data.table.
- All figures: ggplot2 with viz_setting.R. PDF + PNG, 7×4.5 in, 300 dpi.
- Target journal: Social Forces. Descriptive/decomposition design.

## Forbidden
- Never call hukou "treatment". This is descriptive, not causal.
- Never push to GitHub without my approval.
- Never read data/raw/*.dta without explicit permission this session.

Treat CLAUDE.md like a lab manual. Update it when conventions change. Do not put secrets, raw private data, or 200-page documents inside it.

3.4 More ways to get content into a session

Most beginners type prose at the agent and forget that Claude Code has three lighter-weight ways to bring files, commands, and screenshots into a conversation. Each one is a single keystroke away.

@path/to/file — file mentions. Type @ in the prompt box and Claude opens a path-completion picker. Press Tab to accept. The file is loaded into context as if you had pasted its contents, but the prompt stays short and the file path is captured verbatim. This is the cleanest way to feed a codebook, a draft, or a CSV header into the agent:

> Read @data/raw/cfps-2020-codebook.pdf and list every variable
> measuring internet use.

Use @dir/ to attach an entire directory (the agent gets a recursive listing, not all contents).

!command — shell pass-through. Start a prompt with ! and the rest of the line runs in your shell, with the result inserted back into the conversation. No tool-permission prompt — it’s your shell, your responsibility:

> !wc -l data/processed/*.csv
> !git status -s
> !Rscript scripts/01-build-sample.R

This is the fastest way to drop a quick ls, git diff, or head -n 5 file.csv into the conversation without making the agent propose a Bash call.

Drag-and-drop (and paste). Drag a file from your file manager onto the Claude Code terminal window and the absolute path is inserted at the cursor. Useful for one-off attachments like a screenshot of a reviewer’s comment or a PDF you just downloaded. On macOS, Cmd+V pastes images directly; Claude Code will write the image to a temp path and reference it.

Stop and check. Try @CLAUDE.md in a session — Claude should read the file silently, not propose a Read tool call. If you see a permission prompt, you typed > instead of @.

3.5 Picking the right model — and the right tool

/model opens an in-session picker that switches the model without restarting the conversation. By default /model changes the model for the current session only — press d to set the default for future sessions (v2.1.144+). The trade-off is straightforward — speed and cost on one axis, reasoning depth on the other:

What changed at 4.8. Opus 4.8 lifts SWE-bench Verified to 88.6% (up from 87.6%) and SWE-bench Pro to 69.2% (up from 64.3%); USAMO 2026 math jumps from 69.3% to 96.7%; long-context retrieval at 1M tokens roughly doubles (GraphWalks 1M: 68.1% vs. 40.3%). The most important shift for vibe researching is code-honesty: Anthropic reports Opus 4.8 is “roughly four times less likely than Opus 4.7 to allow flaws in code it has written to pass unremarked” — fewer silent regressions in scholar-analyze and scholar-compute outputs. Caveats: prompt-injection robustness regressed slightly (9.6% attack success on Opus 4.8 vs. 6.0% on 4.7), so do not relax safety-status gating on data-sensitive projects.

Fable 5 — the new ceiling. On 2026-06-09 Anthropic released Claude Fable 5 (claude-fable-5), the first public model from its most powerful (Mythos-class) family and now the most capable model you can call. It is state-of-the-art on nearly every tested benchmark — software engineering (highest on Cognition’s FrontierCode even at medium effort), knowledge work (top score on Hebbia’s Finance Benchmark), scientific research, and especially vision: it can read precise numbers off dense scientific figures and reconstruct a web app’s source from a screenshot. Pricing is $10 / $50 per million input / output tokens — roughly twice Opus 4.8, and Anthropic’s most expensive generally-available model. A built-in safeguard routes high-risk prompts (cybersecurity, biology/chemistry, model distillation) to Opus 4.8 instead, in under 5% of sessions. Availability: included at no extra cost on Pro, Max, Team, and seat-based Enterprise plans June 9–22, 2026; after June 23 it draws on credits until capacity allows full plan restoration. (The ungated sibling, Mythos 5, is the same underlying model with some safeguards lifted, and is trusted-access only — not something a workshop project will call.) For vibe researching, reach for Fable 5 only when Opus 4.8 at /effort max still falls short, or when a task is genuinely vision-heavy; Opus 4.8 stays the everyday flagship, and Fable’s credit billing after June 23 makes it easy to overspend if you leave it on.

Fast mode (Claude Code’s --fast flag and the /fast toggle) now uses Opus 4.7 by default (was Opus 4.6 through v2.1.138). With Opus 4.8, Fast mode is priced at 2× standard for 2.5× speed — about three times cheaper per token-second than the previous Opus 4.7 Fast mode. Use Fast mode for big-batch scholar-monitor runs, scholar-eda regenerations, and any time you want the agent to keep up with your typing.

A common cost mistake is leaving Opus on for the entire CFPS pipeline. Switch to Haiku for scholar-monitor, install steps, and large mechanical edits; switch to Sonnet 4.6 for the bulk of analysis and writing; switch to Opus 4.8 with /effort xhigh only for the theory section, the identification memo, the pre-mortem, and the final adversarial review. Use /usage (with the v2.1.149+ breakdown by skills / subagents / plugins / MCP) after the first end-to-end run to spot which step is your biggest line item before reaching for /effort max.

/agents — manage and launch subagents. Subagents are not the same thing as skills.

• A skill (everything scholar-*) is a named workflow: a SKILL.md plus assets and references. You invoke it with /skill-name args.
• A subagent is a lightweight worker spawned in its own context window, with its own tools and prompt, that reports a single answer back. Skills call subagents internally (e.g., scholar-code-review spawns six reviewer subagents in parallel).

You’ll rarely write your own subagent in this workshop. But /agents is the command to list, edit, or create one if you want to reuse, say, a “citation-fact-checker” subagent across projects.

WebFetch and WebSearch — the two web tools you’ll meet first. Claude Code can both fetch a known URL and run a web search; these are the tools scholar-lit-review, scholar-monitor, and scholar-citation use under the hood.

• WebFetch(url) — downloads a single page and gives Claude the rendered text. Prompts for permission on first use per domain.
• WebSearch(query) — runs a search and returns a result list. Prompts on first use; the result links are then candidates for WebFetch.

Permission implication: a project on sensitive data may want to deny WebFetch outside an allow-list of academic domains (crossref.org, openalex.org, *.gov, etc.) to prevent the agent from posting a query that contains participant text to a random site. Configure this in /permissions or in .claude/settings.json.

3.6 MCP — connecting external data sources

Model Context Protocol (MCP) is the open standard Claude Code uses to talk to external systems without ever shipping a custom plugin. A MCP server exposes tools (functions Claude can call) and resources (files Claude can read) over a small JSON protocol; Claude Code is the client. You install a server once, and from then on its tools show up next to the built-in ones.

Every MCP server exposes content through one of three primitives, and which primitive a thing is determines who triggers it:

This is why some MCP actions auto-flow under permissions you already granted (model-controlled tools), while others wait for an explicit user trigger (user-controlled prompts). The primitive name tells you who decides — model, app, or user.

For social-science researchers, the two MCP servers that pay rent quickly:

• Zotero MCP — exposes your Zotero library to Claude. The agent can search your collections, pull a paper’s PDF and metadata, and write into the right collection automatically. This is what makes scholar-lit-review “read entire papers from my library” instead of hallucinating citations.
• GitHub MCP — exposes your repos, issues, and PRs. Useful for scholar-replication (“draft a release note from the last 12 commits”, “open a PR with these changes”) and for managing the repository that holds your project’s output/ artifacts.

Other genuinely useful servers: a Postgres / SQLite MCP for projects that pull data from a local database; a Filesystem MCP when you want to give Claude controlled access to a directory outside the project root (e.g., a shared ~/data/ cache).

Adding a server. The simplest path:

# Zotero: a local stdio server (the zotero-mcp Python package, run via uvx).
$ claude mcp add zotero -- uvx zotero-mcp

# GitHub: the official remote server. The old npm `server-github` package is
# deprecated; use the hosted endpoint with a fine-grained PAT in the header.
$ claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
    --header "Authorization: Bearer $GITHUB_PAT"

$ claude mcp list

Inspect a server’s configuration and status from the CLI, then list the tools it actually exposes from inside a session:

$ claude mcp get zotero      # config + connection status for one server

> /mcp                       # inside Claude Code: shows each connected
                             # server with its tool count and sign-in status

(There is no claude mcp tools subcommand; /mcp is where you see the per-server tool list.)

Most servers need credentials (a Zotero API key, a GitHub PAT). Store them in ~/.api-keys as in §2.6.3 and reference them from the server config; never hard-code them in settings.json.

Workshop rule. Add an MCP server only when the alternative is the agent repeatedly fabricating a citation, a PR description, or a database row. MCP is not a free upgrade — every server is one more piece of surface area that can ship your data somewhere you didn’t intend.

3.7 Running Claude Code inside your editor

Most workshop participants will end up running Claude Code inside an editor rather than a bare terminal. Three integrations matter:

• VS Code extension (publisher: Anthropic). Install from the Marketplace; it adds a Claude panel and binds the editor’s selection, problems list, and git diff to the conversation. Inside a WSL2 / SSH-remote / devcontainer window it stays attached to the right remote root.
• Cursor and JetBrains IDEs. Cursor is a VS Code fork, so it installs the same extension and behaves identically. JetBrains IDEs use a separate Claude Code plugin from the JetBrains Marketplace; it runs Claude Code in the IDE terminal, so mode-cycling and --permission-mode work just like the CLI — same workflow, different package.
• JupyterLab. There is no native Claude extension for JupyterLab today, but the terminal tab inside JupyterLab runs claude exactly like any other shell. For RStudio it’s the same story — open the Terminal pane and run claude from there; the project root will already be set to the RStudio project directory.

What changes in an IDE-attached session:

1. The agent gets the IDE’s current selection and open file as implicit context. You can refer to “this function” without pasting it.
2. Diagnostics (linter errors, type errors) flow into the conversation automatically, so prompts like “fix the type errors below” work without pasting them.
3. The diff viewer is the IDE’s native diff, not a CLI diff — readable on large changes.

What does not change: the project root, the CLAUDE.md, the .claude/settings.json, the PreToolUse hook, the permission modes. The IDE is a frontend; the agent and its safety boundaries are identical to terminal mode.

3.8 Headless, scheduled, and team settings

These three features become useful once you trust Claude Code on a project enough to want it running without you in the loop.

Headless / non-interactive mode. Run a prompt from a shell script or a cron job:

$ claude -p "Summarize today's commits to scripts/ in one paragraph; \
             save to logs/daily-$(date +%F).md"

Add --output-format json to get machine-readable output you can pipe into another tool. There is no interactive approval loop in -p mode, so every tool the prompt needs must be pre-allowed in the project’s .claude/settings.json. Do not enable headless mode on sensitive data without an allow-list.

GitHub Actions. Anthropic publishes a claude-code-action GitHub Action that runs claude -p on every PR. A minimal workflow:

# .github/workflows/claude-review.yml
name: Claude review on PR
on: [pull_request]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review the diff for incorrect causal language."

For research, the use case is not feature shipping — it’s enforcing the same forbidden-claim list your CLAUDE.md declares, on every PR that touches the manuscript repo.

settings.json layers — user, project, local. Claude Code merges three settings files in this order (later overrides earlier):

The split matters: anything you commit (the project layer) is part of the IRB / replication record. Anything you don’t commit (the local layer) is private to your laptop. Keep secrets in local; keep team rules in project.

OAuth vs. API-key auth. Two ways to log in:

• OAuth via Anthropic Console — claude login opens a browser; you authenticate as your Anthropic account and Claude Code stores a refresh token. Billing flows through your Claude Pro / Max / Team subscription. Best for individual researchers.
• API key from console.anthropic.com — paste the key, billing flows through the API console. Best when your institution holds the Anthropic account and grants you a project-scoped key, and when you want to revoke access without touching the user account.

If your institution requires a per-project audit trail, prefer API keys — they can be rotated and revoked per project, and the Anthropic Console shows usage by key.

Stop and check. Run /doctor once after configuring all three settings layers and claude mcp list to see which servers are registered. If /doctor reports a mismatch between the layers, fix it before moving to §4.

4. The Minimum Safe Project Layout

Goal: before you start the CFPS example, your project directory should look like this.

digital-divide-china-cfps/
├── CLAUDE.md                  ← persistent project brief
├── .claude/
│   └── safety-status.json     ← which files are CLEARED / LOCAL_MODE / HALTED
├── data/
│   ├── raw/                   ← CFPS .dta files. NEVER edited.
│   ├── interim/               ← regenerable intermediate files
│   └── processed/             ← outputs of build scripts
├── materials/                 ← codebooks, questionnaires (English & Chinese)
├── output/
│   └── digital-divide-china-cfps/
│       ├── design/            ← idea, blueprint, variable dictionary
│       ├── scripts/           ← all R/Python analysis scripts
│       ├── tables/            ← regression tables, descriptives
│       ├── figures/           ← PDF/PNG figures
│       ├── drafts/            ← manuscript versions
│       ├── verify/            ← verification reports
│       ├── citations/         ← refs.bib, citation logs
│       ├── replication-package/
│       └── logs/              ← timestamped run logs
├── logs/
│   └── init-report.md         ← what scholar-init found at scan time
└── README.md

Why this matters:

• data/raw/ is sacred. Never edit it by hand. Every transformation must come from a script in output/<slug>/scripts/. If you cannot reproduce data/processed/ from data/raw/ by running the scripts, your project is broken.
• output/<slug>/ is the project workspace where every skill writes its artifacts. Each skill writes to a predictable subdirectory, so you can always find verify reports under verify/, drafts under drafts/, etc.
• logs/ is evidence. When verification finds a problem, the first question is “what did the run actually do?” Logs answer that.

If your current project is a pile of .csv files on the Desktop with names like final_v3_REAL.xlsx, the agent will not save you. It will accelerate the chaos. Do scholar-init first.

5. Exercise 1 — Turn a Vague Ask into an Agent Task

Time: 5 minutes. Do this before the workshop continues.

Vague version (don’t do this):

“Use the CFPS data and write me something on the digital divide in China.”

Agent-quality version (do this):

INPUTS
  - Read only: data/raw/cfps2010adult_*.dta through data/raw/cfps2020person_*.dta
  - Codebooks in materials/
  - Variable dictionary in design/variable-dictionary.csv
TASK
  - Build a person-wave panel restricted to ages 16+, harmonizing
    internet access (any-use), weekly internet hours, hukou, education,
    cohort, gender, household size, and province.
OUTPUTS
  - data/processed/cfps-panel-long.rds
  - logs/01-build-sample-<timestamp>.log
  - Exactly one summary printout: row count by wave × hukou.
QUALITY STANDARD
  - All sample restrictions documented in the script header.
  - Missing-value codes (-1, -2, -8, -9, -10) treated as NA.
  - Script runs end-to-end with one command: `Rscript 01-build-sample.R`.
AUDIT
  - Print path of every file read; write a SHA256 of the output rds.
STOP RULE
  - If any wave is missing more than 3 expected variables, STOP and
    report them. Do not impute.
  - If processed panel has fewer than 150,000 person-waves, STOP.

Look at the difference. The first version asks for a paper. The second version specifies a measurable, bounded, inspectable, stoppable task. Every scholar-skill prompt you write should look like the second version.

The six elements:

The most important sentence in any agent prompt: “If you cannot verify it, mark it.” That single line changes the agent’s behavior — it gives it permission to be incomplete rather than confident.

5A. What’s New in Claude Code (2026): Dynamic Workflows, Subagents, and Automation

Goal: know which of Claude Code’s newer capabilities actually change how you do research — and which are just convenience — so you can reach for the right one instead of brute-forcing everything through a single chat.

Everything in Part I treated Claude Code as one assistant in one conversation. That mental model still works, but it leaves most of the 2026 feature set on the table. The releases over the last year added ways for the agent to fan work out, run it in the background, repeat it on a schedule, and enforce your rules automatically. Used well, these turn a one-paper workflow into a small research operation. Used carelessly, they multiply the number of places an unverified claim can hide. The recurring discipline of this handbook — bounded task, inspectable artifact, human owns the standard — matters more as autonomy goes up, not less.

The features below evolve quickly. Treat the exact flag names and defaults as a snapshot of mid-2026; type /help inside a session and read the changelog (claude changelog or the docs) when something behaves differently. The concepts are stable; the spellings drift.

A quick map of what to reach for:

Plan mode — see the plan before any file changes

Press Shift+Tab to cycle permission modes; one of them is Plan mode. In it the agent may read, search, and reason, but it cannot edit files or run shell commands until you approve. It produces a written plan and waits.

> Shift+Tab  (until the prompt shows "plan mode")
> Read the build-sample script and the variable dictionary, then propose a
  plan to add a province-level fixed-effects robustness check. Do not write
  anything yet.

For a researcher this is the cheapest insurance there is: you read the intended approach — which files, which estimator, which outputs — before a single line of your analysis changes. Approve it and the agent switches to execution; reject it and nothing was touched.

Subagents — hand a bounded job to a fresh context

A subagent is a separate Claude instance the main session delegates to. It runs in its own context window, with its own system prompt, an optional restricted tool list, and even its own model. The main conversation gets back only the subagent’s summary — not the 30 files it read to produce it.

You already rely on this without thinking about it: scholar-code-review (“six reviewers, one report”, §13) and the scholar-verify family (§15, Appendices F–J) work by dispatching specialist subagents in parallel. You can also define your own. Drop a file in .claude/agents/:

---
name: lit-triage
description: Screens papers for relevance to a stated research question and
  returns a one-paragraph verdict with a citation. Use for bulk literature triage.
model: haiku
tools: Read, WebSearch, WebFetch
---
You screen one paper at a time against the research question.
Return: RELEVANT / MAYBE / NOT, one paragraph why, and the citation.
Never fabricate findings; if you cannot access the paper, say so.

Then just ask in plain language (“triage these 20 abstracts for the digital-divide question”) and Claude routes each to the lit-triage worker. Routing fast, repetitive jobs to haiku also keeps cost down. The rule from §1 still holds: a subagent’s summary describes what it intended to do — spot-check the artifacts, don’t trust the summary blindly.

Dynamic workflows — fan out, coordinated, in the background

This is the headline addition, and the one the workshop gets asked about most. A dynamic workflow is the agent planning and running a fleet of subagents for you: Claude writes a short orchestration script from your task description, then a runtime executes it — spawning many workers (independent units of the task), running a bounded number at once, and keeping the intermediate results in the script’s variables instead of dumping them all into your conversation. Your session stays responsive while it runs.

Where a single subagent is “do this one bounded job,” a dynamic workflow is “do this across hundreds of units and bring me the consolidated result”:

> Use a workflow: for every .R script under analysis/, check whether missing-value
  codes (-1,-2,-8,-9,-10) are converted to NA before any model is fit. Return one
  table: script, line, status. Run them in parallel and consolidate.

Good research fits for the pattern:

• Repo- or corpus-wide audits — every script, every variable, every figure caption checked the same way.
• Bulk transformations — recode or re-harmonize 500 files split into independent units.
• Cross-checked synthesis — have several workers investigate the same claim from independent angles, then reconcile, instead of trusting one pass.

Cost and caution. A workflow multiplies token spend by the number of workers it spawns. Always test on a narrow slice first — one directory, one wave, one question — confirm the output shape, then widen. And because there is no human in the loop mid-run, the stop-rule discipline from §5 is not optional: build the “if you cannot verify it, mark it” instruction into the task itself.

Self-paced loops and goal-driven runs

Two ways to say “keep going until you’re done” without babysitting:

• /loop repeats a prompt. Give it an interval (/loop 5m check whether the job finished) for polling, or let it self-pace (/loop keep fixing the failing tests, iterating as needed) so the agent decides when to take the next pass.
• A completion goal lets the agent take multiple steps across turns until a measurable condition is met — “until Rscript 11-analyze.R runs clean and the headline table matches Appendix G.”

These shine for the mechanical tail of analysis: reproduce a table, get a script to run end-to-end, drive a linter to zero. They are poor at fuzzy goals (“make the paper better”) — those never terminate cleanly, so keep the condition binary and checkable.

Background tasks and monitoring

Long jobs — a full pipeline, a big batch of model calls, a slow build — can run in the background while you keep working in the same session. The agent hands the job off, you get notified when it finishes, and you can check interim output instead of staring at a blocked terminal. For research this means the 40-minute data build and the manuscript edit you are doing now no longer block each other.

Scheduled routines — /schedule

/schedule creates recurring tasks that run on a clock (and, on the cloud/remote setup, persist after you close the terminal). You describe the cadence and the job in plain language:

> /schedule  every weekday at 8am, search for new arXiv papers on "digital
  inequality" and append a one-line summary of each to lit/inbox.md

Natural research uses: a morning new-paper digest, a Friday-night data-quality sweep, a monthly archive of logs. It bills against your usage and runs with whatever file access you grant, so scope it like any other agent task.

Hooks — make your data boundary an enforced rule, not a hope

§1 said the agent’s read boundary is your data boundary. Hooks let you enforce that mechanically. A hook is a shell command Claude runs automatically on an event — before a tool call (PreToolUse), after one (PostToolUse), at session start, and so on — and a PreToolUse hook can block an action. Configure them in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/guard.sh" }] }
    ]
  }
}

The script inspects the proposed command and exits non-zero (or returns a deny decision) to refuse it — for example, refuse any rm -rf, or any write outside data/processed/. This is how you turn “please don’t touch the raw data” from a polite request in CLAUDE.md into an enforced rule.

Enforced, but still cooperative: the harness runs your script and obeys its verdict, and a determined command can encode its way around a denylist (§6.4). The thing that is not cooperative is the sandbox.

The Bash sandbox — /sandbox, and its two modes

Claude Code ships an OS-level sandbox for the Bash tool. Where a hook asks, the sandbox enforces: the operating system refuses the open(), for the command and every child process it spawns, no matter how the path is spelled. macOS uses Seatbelt; Linux and WSL2 use bubblewrap. Native Windows is not supported — Windows participants run Claude Code inside WSL2 (Appendix K); WSL1 will not work either.

You do not have to hand-write JSON to turn it on. /sandbox opens a panel with three tabs:

A fourth tab, Dependencies, appears only when something is missing, and names which of ripgrep, bubblewrap, socat, or the optional seccomp filter your platform lacks. On Linux/WSL2, sudo apt-get install bubblewrap socat then restart — the dependency check runs at startup, so the panel will not notice an install until you do.

The two modes, specifically. Both enforce identical filesystem and network isolation. The only difference is whether you are asked.

Auto-allow is not “no questions asked”. Four things still stop you: explicit deny rules, always; rm/rmdir aimed at /, your home directory, or critical system paths; content-scoped ask rules such as Bash(git push *); and plan mode, where commands outside the built-in read-only set prompt regardless. Only a bare Bash (or Bash(*)) ask rule is skipped for sandboxed commands — and even that is not skipped in plan mode.

Choosing a mode in the panel writes to .claude/settings.local.json, so it applies to that project only. To sandbox everything you do, set "sandbox": {"enabled": true} in ~/.claude/settings.json.

The default that will surprise you — and it matters for restricted data. The sandbox’s default write scope is the working directory plus the session temp directory. Its default read scope is the entire computer, minus a few denied directories — which still includes ~/.ssh and ~/.aws/credentials. Turning the sandbox on does not protect your microdata. You get that wall only by adding sandbox.filesystem.denyRead, or a sandbox.credentials block ("mode": "deny" for files; "deny" or "mask" for environment variables). Network access is the opposite default: no domains are pre-allowed, and the first time a command needs one you are prompted; approving it lasts the rest of the session.

Two more behaviours worth knowing before you rely on this as a safety control:

• The escape hatch. When a command fails because of sandbox restrictions, Claude may retry it with dangerouslyDisableSandbox, which runs it outside the box through the normal permission flow. Setting "allowUnsandboxedCommands": false makes that parameter ignored entirely — this is what the Overrides tab calls Strict sandbox mode.
• It fails open by default. If the sandbox cannot start — a missing dependency, an unsupported platform — Claude Code prints a warning and runs your commands unsandboxed. Set "failIfUnavailable": true to make that a hard failure instead. For a DUA-bound project, that is the setting you want.

Finally, a distinction the docs are emphatic about and which is easy to get backwards: /sandbox is not a permission mode (§3.1). A permission mode decides whether a call runs; the sandbox decides what it can touch once it does. They compose — and the sandbox’s auto-allow is a different mechanism from the permission system’s auto mode, which uses a classifier.

This is the same machinery /scholar-safety level lockdown configures for you (§6.6) — lockdown generates the OS sandbox config with denyRead over data/, which is why it is the only genuine containment boundary in the suite, and why it blocks your own Rscript too.

Skills and plugins — package a procedure once

A skill is a folder under .claude/skills/<name>/ with a SKILL.md that carries a procedure; its full text loads only when the skill is invoked (/<name>), so it costs no context until used. This is exactly what open-scholar-skill is — a pack of skills (scholar-init, scholar-design, scholar-verify, …). Plugins bundle skills, subagents, hooks, and MCP servers so a lab can share a whole toolkit with one install. The lesson for participants: when you find yourself re-typing the same multi-step instructions across projects, that is a skill waiting to be written.

MCP servers — connect Zotero, databases, and the web

The Model Context Protocol (MCP) lets the agent call external tools and data sources as first-class tools. Add one with claude mcp add … (or declare it in .mcp.json), then /mcp shows status and handles any sign-in.

$ claude mcp add --transport stdio zotero -- uvx zotero-mcp

For research this is the bridge to your reference manager, a results database, a notebook service, or a vetted web-search tool — so the agent pulls structured data directly instead of you copy-pasting it (and introducing transcription errors of exactly the kind §15 exists to catch).

Git worktrees — parallel experiments without collisions

A worktree is a separate working directory on its own branch. Claude Code can run a session — or isolate a subagent — in one, so two lines of work never overwrite each other’s files. Start one with claude --worktree try-province-fe; the agent develops there, and you merge the branch only if the experiment pays off. Ideal for “run the analysis two ways and compare” without polluting your main checkout.

Models, effort, and fast mode

Three dials worth knowing: /model switches between Opus (deepest reasoning), Sonnet (balanced), and Haiku (fast and cheap — good for subagents and triage); an effort setting trades thinking depth for speed and cost; and /fast (on recent Opus 4.x) returns answers noticeably quicker for routine work. A sensible default: Opus for design, analysis, and verification; Haiku for bulk mechanical subagent jobs. There is also /ultrareview, a user-triggered, billed multi-agent review of your current branch or a pull request — a heavier, independent second opinion than scholar-code-review.

A note on autonomy and verification

Every feature in this section moves work away from the single, watched conversation and toward fleets, schedules, and background runs. That is a real productivity gain and a real risk concentration: the more the agent does unattended, the more a wrong number can travel before a human sees it. So the workshop’s central lesson (§15) scales with these tools — the more autonomy you grant, the more non-negotiable verification and inspectable artifacts become. New capability, same contract: you own the question and the standard; the agent owns the execution.

One artifact makes this inspectable. Every /scholar-* run now leaves a Reasoning–Action–Observation (RAO) trace — an append-only logs/trace-<skill>-<date>.ndjson with one {reasoning, action, observation, refs, status} record per step. The process-log-*.md you read is a rendered view of that trace, and a coverage check red-fails any phase that left no trace behind. Dispatched subagents (reviewers, verifiers) emit a .trace.ndjson sidecar that the orchestrator folds in. Privacy rule: a trace records verdicts, counts, and file references only — never raw rows, quotes, or PII, and under LOCAL_MODE only derived aggregates.

PART II — OPEN SCHOLAR SKILLS, END TO END

This is the heart of the workshop. We build a Social Forces-style paper on the Chinese digital divide using only the open-scholar-skills suite. Every code block in this part is from a real run on May 4–5, 2026. Project slug: digital-divide-china-cfps.

The skills appear in the order you actually use them. But before the walkthrough, three things you need in front of you at all times: the complete inventory (§5B.1), the argument grammar every skill shares (§5B.2), and the artifact contract that makes the chain work (§5B.3).

5B. The suite at a glance — inventory, grammar, contract

5B.1 All 44 skills, by stage

The § column points at the section of this handbook documenting that skill in full — every mode, every argument, every gate, every file it writes.

◆ marks the nine skills that ship only in the extended edition (§2.4). On the public edition those commands do not exist; everything unmarked works identically on both.

The suite installs into ~/.claude/skills/<skill-name>/SKILL.md. Anything in that directory is invocable as /<skill-name>. Verify your install with:

$ ls ~/.claude/skills/ | grep -c scholar           # 35 public · 44 extended
$ ls ~/.claude/skills/scholar-full-paper/          # SKILL.md, references/, scripts/

Stage 0 — set up and protect the project

Stage 1 — find and sharpen the question

Stage 2 — design before data

Stage 3 — analyze

Stage 4 — write and verify

Stage 5 — submit, share, and reuse

Stage 6 — downstream products

Orchestrators (Part III)

5B.2 The argument grammar every skill shares

Each skill declares an argument-hint in its frontmatter. Read it before your first run:

$ head -8 ~/.claude/skills/scholar-design/SKILL.md

---
name: scholar-design
description: Plan a rigorous research design, run power analysis, ...
argument-hint: "[quant|qual|mixed|experiment|power|methods-section|pap|
                computational|NLP|ML|network|ABM|premortem|blueprint]
                [research question] [optional: data source, design type,
                journal target]"
---

Three rules follow from that grammar:

1. The first token is almost always a mode. [a|b|c] means “pick exactly one.” If you omit it, the skill guesses from your prose — usually correctly, but guessing costs a turn and sometimes picks the wrong branch. Say the mode.
2. Bracketed optional: items are keyword-ish, not positional. journal=Social Forces and target Social Forces both work; the skills parse loosely. Prefer key=value — it survives copy-paste into scripts.
3. File paths are literal. Relative paths resolve against the directory Claude Code was launched in, not against output/<slug>/. When in doubt, paste absolute paths.

A well-formed invocation names five things: mode, subject, data, journal, constraint.

> /scholar-analyze data=data/processed/cfps-panel-long.rds
                  outcome=y2_hours
                  predictors=hukou_rural,cohort,female,eduy
                  fe=province_x_wave
                  journal=Social Forces

An ill-formed one names one: > /scholar-analyze run the models.

5B.3 The artifact contract — why the chain holds together

The skills do not pass information to each other in the chat. They pass it through files on disk in output/<slug>/. That is the whole trick, and it is why you can stop, close your laptop, and resume three days later.

Two consequences you should internalize now:

• Deleting a file breaks the chain silently. If you rm design/results-lock-*.md, scholar-write will not error — it will draft from imagination. Verification is what catches this, which is why §15 is not optional.
• You can run any skill standalone. Every skill in this part works on its own, against whatever files happen to be on disk. The orchestrators in Part III add gates and ordering; they add no capability the individual skills lack.

5B.4 The trace contract — every step, written down

Part I introduced the agent loop: Thought → Action → Observation. Every skill in the suite now writes that loop down, one append-only record per meaningful step, in logs/trace-<skill>-<date>.ndjson: the reasoning (why), the action (what it did), the observation (what came back), plus refs, status, and the dispatching agent’s id. The readable process-log-*.md you will see referenced throughout Part II is a rendered view of that file, never hand-written. A phase that produces no valid trace RED-fails its gate.

The honest bit — read this one carefully. The harness cannot log the model’s hidden chain of thought. What is recorded is the stated rationale — a short, articulable “why.”

So the trace is not evidence of what the model was thinking. It is evidence of what it said it was doing, next to what it actually did and what came back. That is the part you can audit, and it is the only part that was ever checkable. Treat any stronger reading of it as a claim you cannot support.

Two rules keep the trace shareable:

• Aggregates only. reasoning and observation carry metrics, verdicts, counts and file paths — never data rows, quotes, or PII. Record that you saw something and what shape it had, not the value.
• So where do the quotes live? Under evidence/ — the ledger in §8A.6. A trace step that captures an anchor cites it by anchor_id; it never inlines the passage. Two artifacts, one run, one deliberate split.

Sub-agents have no shell of their own, so they emit a .trace.ndjson sidecar that the orchestrator folds in — cross-checked against the dispatch manifest, so an agent cannot be quietly dropped from the record.

The same contract also archives code: every executed R/Python/Stata/Julia script — including LOCAL_MODE Rscript -e and python3 -c heredocs — is written verbatim into the project scripts/ directory with the skill’s numbering prefix and a run header. This is what makes §13.7’s “the reviewed bytes must be the executed bytes” auditable after the fact rather than at the moment of the run.

Projects pick this up automatically: scholar-init writes it into the project CLAUDE.md auto-rules block (§F in the lean profile, §14 in the full one), and existing projects refresh on the next run. Before this existed, a lean project running standalone skills loaded a CLAUDE.md with zero traceability rules and relied entirely on each skill remembering its own protocol.

6. scholar-init + scholar-safety — start with safety

Goal: create the standard project structure, classify every file, install the guard that enforces those classifications, and write the safety contract all later skills consult.

These two skills share the same machinery — the same scanner, the same anonymizer, the same sidecar file, the same PreToolUse hook. The division of labour is simple: scholar-init owns the project and the file classifications; scholar-safety owns operations, protocols, and enforcement strength.

6.0 The four modes of scholar-init

argument-hint: "[init <slug> <file1> <file2> ...] | [review] | [add <file1> ...]
                | [status] — defaults to init if a slug-looking argument is
                provided, review otherwise"

A slug must match ^[a-z][a-z0-9]*(-[a-z0-9]+)*$, 2–64 characters. If you hand the skill a topic description instead (“digital divide in China”), it will slugify it — downcase, drop stopwords, hyphenate, truncate to 48 characters — and ask you to confirm before building anything.

6.1 Run scholar-init

> /scholar-init init digital-divide-china-cfps \
                ~/data/cfps/raw \
                --materials ~/data/cfps/materials

Flags accepted by the underlying scripts/init-project.sh:

--force destroys prior review decisions. A rebuild rewrites the sidecar from a fresh scan, so every OVERRIDE rationale and LOCAL_MODE choice you made is lost. Fix a broken init incrementally instead, unless you genuinely want to start over.

What it does, in order:

1. Creates <dest>/<slug>/ with data/{raw,interim,processed}/, materials/, output/, logs/, .claude/ — plus corpus/, but only if you passed --corpus, so non-corpus projects do not get an empty directory.
2. Copies (or, with --link, symlinks) raw files into data/raw/, materials into materials/, and text corpora into corpus/. Name collisions get a numeric suffix.
3. Runs a local-only safety scan on every ingested file via scripts/gates/safety-scan.sh — file, wc, grep, awk only. Claude sees counts and pattern categories, never the matching values.
4. Writes .claude/safety-status.json, logs/init-report.md, README.md, .gitignore.
5. Writes the auto-managed project-memory block into CLAUDE.md (Claude Code host), AGENTS.md (Codex host), or both (host undetected).
6. If any file came back YELLOW or RED, transitions immediately into review mode without asking.

Abridged terminal output from the real run:

[scholar-init] Creating project: digital-divide-china-cfps
[scholar-init] Ingesting 38 raw files from data/raw ... ok
[scholar-init] Ingesting 19 materials files ... ok
[scholar-init] Running safety scan ...
  cfps2010adult_201906.dta            : CLEARED        (de-identified PIDs)
  cfps2018crossyearid_202104.dta      : CLEARED        (cross-year ID file)
  cfps2020person_202306.dta           : NEEDS_REVIEW   (location items, COVID)
  CFPS_2020_QnrAdult_EN.pdf           : CLEARED        (codebook)
  ...
[scholar-init] Wrote .claude/safety-status.json
[scholar-init] Wrote logs/init-report.md
[scholar-init] DONE — 35 CLEARED, 3 NEEDS_REVIEW, 0 HALTED

Exit codes from init-project.sh, worth knowing when you script it: 0 success, 1 usage error (bad slug or missing file), 2 project directory exists without --force, 3 safety-scan.sh not found (your install is broken — run bash setup.sh in the skill repo).

6.1.1 The project CLAUDE.md that init writes

Step 5 above is easy to miss and matters a lot. scholar-init writes a lean project-memory profile — five sections, roughly 50 lines: the objectivity mandate, the data-safety stack and LOCAL_MODE scope, citation rules, and workflow rules. Every later Claude Code session in that directory reads it automatically.

If you later run /scholar-full-paper, the orchestrator upgrades that file to the full 13-section, ~230-line profile. The upgrade is one-way: re-running /scholar-init on an upgraded project prints already at v2-full ... lean request ignored and changes nothing. This is deliberate — a lean re-init must never silently strip the gate conventions the orchestrator depends on.

Idempotency messages you may see: created <path> (v2-lean), appended auto-rules block to <path>, migrated <path> from v1 to v2-lean, already at v2-lean, no-op.

6.1.2 Text corpora — --corpus and why the directory name is load-bearing

Linguistics and text-as-data projects usually keep a corpus outside data/, and until recently that meant it fell outside the guard too. It no longer does: corpus/ and corpora/ are gated path segments, so everything beneath them is treated as data regardless of extension — including extensionless files, and including the linguistics formats (.eaf, .TextGrid, .trs, .cha) that no extension rule would otherwise catch.

Ingest a corpus through the skill rather than dropping it in by hand. Ingesting is what earns those files a reviewed entry in safety-status.json; a corpus you merely copied in gets re-scanned live on every read instead.

> /scholar-init init hanyu-metalinguistic-corpus \
                --corpus ~/data/hanyu/videos \
                --corpus ~/data/hanyu/comments

A corpus is not one kind of thing, and the policy differs by what is in it:

This works because the classifier matches on path segments, so the qualitative segments (transcripts/, interviews/, field-notes/, participants/, subjects/, respondents/) keep their strict treatment when nested inside corpus/:

corpus/news/article.txt        gated, OVERRIDE allowed
corpus/transcripts/i01.txt     gated, OVERRIDE refused
corpus/recordings/s1.wav       gated, OVERRIDE refused (extension rule)

The name is an exact segment match. mycorpus/, corpus-2024/, texts/, speeches/, and tweets/ are not gated. Name the directory exactly corpus/ or corpora/, or keep the material under data/raw/. This is the kind of rule that looks pedantic until the day a directory called transcripts-2024/ sits one rename away from protection.

6.2 Resolve NEEDS_REVIEW with scholar-init review

You cannot advance to brainstorming or analysis until every file is resolved. The guard will block the reads.

> /scholar-init review

Claude walks each NEEDS_REVIEW item interactively — re-running the scanner for live detail, and never reading the file itself to “help decide.”

File: cfps2020person_202306.dta
Reasons flagged:
  - Contains community-level codes (ck01, ck02) below-county granularity
  - Contains COVID-related items that may be sensitive
Options:
  [c] CLEARED          - Claude may read directly
  [l] LOCAL_MODE       - Claude may invoke R/Python loaders that compute
                          summaries, but raw rows never enter context
  [a] ANONYMIZED       - Replace with derived/aggregated file before reading
  [o] OVERRIDE         - Claude may read directly; you log a written rationale
  [h] HALTED           - File is off-limits for this project
Choice [c/l/a/o/h]:

The option set is not the same for every file. The skill classifies each file as structured or qualitative — by extension (.wav .mp3 .flac .m4a .mp4 .mov .eaf .textgrid .cha …) or by path (a .txt/.docx/.md living under transcripts/, interviews/, field-notes/, participants/, respondents/, materials/):

The qualitative-OVERRIDE refusal is enforced twice — once in this menu, and again inside the PreToolUse guard itself, so hand-editing the sidecar does not get you past it.

Choosing OVERRIDE requires a typed rationale of at least 20 characters. “n/a”, “ok”, and “false positive” alone are rejected; the prompt blocks until you write something real or cancel. The rationale lands in logs/init-report.md under Decision history, with the prior status, new status, and who decided.

Choosing ANONYMIZE runs python3 scripts/gates/anonymize-presidio.py anonymize <file>. Three things to know:

• Output goes to output/qual/anonymized/ANON_<basename> — never next to the original — alongside pseudonym-key-DO-NOT-SHARE.csv.
• If Presidio finds no PII it exits 0 without writing a file. The original stays NEEDS_REVIEW; nothing is auto-cleared.
• The ANON_ file is re-scanned. Only if it comes back GREEN does the original become HALTED and the anonymized copy become ANONYMIZED. Still YELLOW or RED and you are back in the loop.
• Presidio is optional for scanning (there is a regex fallback) but mandatory for anonymizing. Without presidio-analyzer, presidio-anonymizer, and spacy + en_core_web_lg, this option dies with an ImportError and your only valid choices are LOCAL_MODE or HALT.

For CFPS we typically choose LOCAL_MODE for any wave-level person file: scripts can load the data and produce summary counts, regression tables, and figures, but the raw row values never reach Claude’s context window. This is a real privacy boundary, not a slogan — §6.5 spells out exactly what LOCAL_MODE permits.

Changes need a restart. Claude Code snapshots hook configuration at session start. After a review pass that changes statuses, restart Claude Code before expecting the guard to honour the new values. Under Codex, the project must be trusted before the hook activates at all; until then AGENTS.md instructs the agent to self-enforce against the sidecar.

6.3 Inspect safety-status.json

$ jq . .claude/safety-status.json | head -30

{
  "_safety_level": "standard",
  "/Users/you/digital-divide-china-cfps/data/raw/cfps2010adult_201906.dta": "LOCAL_MODE",
  "/Users/you/digital-divide-china-cfps/data/raw/cfps2018crossyearid_202104.dta": "CLEARED"
}

The sidecar is a flat map — an absolute file path → a status string — plus the single meta key _safety_level. The full status vocabulary, validated by scripts/gates/sidecar-schema.sh:

Two schema violations that fail the guard closed, so they are worth avoiding: an object-valued entry (the value must be a bare string), and a relative-path key. The lookup has no relative-path or basename fallback. A hand-written {"foo.csv": "OVERRIDE"} is silently ignored, and moving the project directory invalidates every entry in the file.

Every later skill reads this file before touching data. If the status is LOCAL_MODE, the analysis script must enforce summary-only loading — and scholar-analyze will refuse to print raw rows.

6.4 The guard — what actually enforces this

The classification is only as good as the thing that enforces it. That is scripts/gates/pretooluse-data-guard.sh, registered as a Claude Code PreToolUse hook in ~/.claude/settings.json (and mirrored into <proj>/.codex/config.toml for Codex hosts). It intercepts Read, NotebookRead, NotebookEdit, Grep, Glob, Bash, Edit, Write, and MultiEdit. Exit 0 allows; exit 2 blocks and hands the refusal reason back to Claude.

What it does, channel by channel:

• Read channel. Canonicalizes the path (resolving symlinks), refuses anything resolving into a system directory (/etc, /dev, /proc, /sys, /System, /var/db, /var/log), then consults the sidecar: CLEARED/ANONYMIZED/OVERRIDE → allow; LOCAL_MODE/HALTED → block with a hint to use a Bash loader; NEEDS_REVIEW* → block and tell you to run /scholar-init review.
• Bash channel. A cooperative speed-bump, not a wall. It blocks the obvious dump verbs — cat, head, tail, less, od, xxd, strings, base64, sqlite3, jq, sed, awk, perl, and grep without -c/-l/-q — when they target a sensitive path. On ambiguity it fails open, because bricking the shell is worse than the marginal leak it would prevent.
• How the Bash channel decides what “the target” is. Two rules, both added in July 2026 after the original shape-matching classifier proved wrong in both directions. (a) A token is classified only if it resolves to something that exists — file or directory. This kills a whole family of false positives: a regex handed to grep (grep -nE "data/raw|materials/" script.sh) is no longer read as a sensitive target, and one such block had been stopping the very command used to check whether that directory existed. Declining to classify a nonexistent path cannot open a leak, because this is a read gate and a dump verb aimed at nothing reveals nothing. Globs are rewritten to their literal directory prefix, since a glob can only reach files underneath it. (b) Variables are expanded before classification. Tokens containing $ used to be skipped as unresolvable, so SP=/abs/proj; grep x "$SP/corpus/transcripts/i01.txt" evaded the gate outright. A tokenizer pass now resolves $VAR and ${VAR} from assignments made in the same command, plus a small ambient-environment allowlist. That scope is exactly right: Claude Code starts a fresh shell per Bash call, so a variable neither assigned in-command nor exported expands to empty and cannot address a file at all.
• Grep/Glob channels. Blocks searching or enumerating raw-data paths, and any direct target with a data extension.
• Which paths count as data. Segment matching, not extension matching: data/raw/, data/interim/, data/processed/, and — since July 2026 — corpus/ and corpora/ (§6.1.2), plus the qualitative segments transcripts/, interviews/, field-notes/, participants/, subjects/, respondents/, which additionally refuse OVERRIDE.
• Edit/Write/MultiEdit. Guards exactly one thing: writes to .claude/safety-status.json. It refuses to promote a RED or HALTED path to CLEARED/OVERRIDE unless /scholar-init review provenance exists in logs/init-report.md. Everything else fails open.
• Images. Pixels cannot be grep-scanned, so images are classified by path: inside data/raw/ → blocked; inside output/figures/ → allowed.

Failure behaviour is deliberately asymmetric: if jq is missing, the read channels fail closed (blocked, with an install-jq message) while the Bash/Edit/Write channels fail open. An abnormal script termination is converted into a block by an EXIT trap whenever the target had already been classified as data-risk.

The footgun that silently disables everything. If the hook’s command path contains a space — and it will, if you installed under ~/Library/CloudStorage/GoogleDrive-…/My Drive/… — both Claude Code and Codex fail to execute it, with no visible error. The guard becomes globally inert. Register it wrapped in quotes:

{ "command": "bash '/Users/you/My Drive/open-scholar-skills/scripts/gates/pretooluse-data-guard.sh'" }

Verify with a deliberate probe: ask Claude to Read a file you know is HALTED. If it succeeds, your hook is not wired up.

6.5 The LOCAL_MODE contract

LOCAL_MODE is the workhorse status for real survey data, so learn its rules. The analysis runs as one Rscript -e or python3 -c heredoc per analysis, and only aggregate output may come back:

Intermediate files written by a LOCAL_MODE script must be saved to data/interim/ or data/processed/ and are auto-registered as LOCAL_MODE in the sidecar — derived data inherits the constraint rather than escaping it.

6.6 scholar-safety — the six modes

argument-hint: "[scan|gate|protocol|status|level] [file path / operation
                description / level name] [optional: data type, project name,
                journal target]"

> /scholar-safety scan data/raw/cfps2020person_202306.dta
> /scholar-safety gate "about to read data/interviews.txt for coding"
> /scholar-safety protocol digital-divide-china-cfps journal="Social Forces"
> /scholar-safety status
> /scholar-safety level strict

The critical operating rule, stated in the skill itself: never Read a flagged file until the user explicitly selects PROCEED or OVERRIDE — and note that LOCAL MODE is the opposite of Read permission and must never trigger a Read.

6.6.1 What the scanner actually looks for

The scan counts pattern hits across: SSNs; names; emails; phones; street addresses; ZIP codes; IP addresses; health and HIPAA markers; mental-health items; legal and immigration items; financial fields; restricted-dataset markers (NHANES, PSID, NLSY, IPUMS, Census RDC, DUA, “confidential”); international restricted-dataset markers (UK Biobank, ALSPAC, NHS Digital, SOEP, EU-SILC, CFPS, CHARLS, CGSS, CLHLS, IHDS, JGSS, Understanding Society, KLoSA, plus SHARE / HILDA / Add Health matched case-sensitively); IRB and participant markers; and fine geographic granularity.

The classification matrix, abridged to the rows you will actually hit:

Two fail-closed rules make this trustworthy. A missing, unreadable, or directory target returns SCAN-ERROR at 🔴 HIGH — never LOW. And a binary file floors at 🟡: a clean regex pass over a .dta, .sav, .rds, .xlsx, .parquet, or .sqlite file is not evidence of safety, because the scanner cannot read the container. This is exactly why CFPS .dta files land in review rather than sailing through.

6.6.2 The three safety levels — and what each actually guarantees

> /scholar-safety level lockdown

The skill verifies the redactor is really registered before claiming strict protection, rather than reporting a level it cannot deliver.

Lockdown has a sharp edge worth planning around: denyRead on data/ blocks all reads of that directory — including the sanctioned LOCAL_MODE Rscript/python3 loader. Either run your analysis first and lock down afterwards, or generate the config with --allow-escalation so human-approved unsandboxed commands can still run.

What lockdown is, underneath. It writes the configuration for Claude Code’s own Bash sandbox (§5A) — the same Seatbelt/bubblewrap machinery you can drive by hand with /sandbox. Two consequences follow. First, --allow-escalation is the suite’s name for leaving allowUnsandboxedCommands on; omitting it is what the /sandbox Overrides tab calls Strict sandbox mode. Second, everything the sandbox does not do by default still applies here: read access defaults to the whole machine, so the denyRead over data/ is doing all the work, and if the sandbox cannot start at all, Claude Code warns and runs unsandboxed unless failIfUnavailable is set. If your DUA requires containment, verify the level rather than assuming it — /scholar-safety status, then a deliberate probe on a file you know is HALTED.

Everything below lockdown is evadable in principle — by another interpreter (ruby, node), by an encoding (base64, gzip, hex), by assembling the path from shell variables, or by copying the file to a benign path and reading that. The suite documents this openly rather than pretending otherwise. Design your workflow so that the honest path is also the easy path, and reserve lockdown for data where the DUA genuinely requires containment.

6.7 The scripts you can run yourself

Every gate is a plain shell or Python script. You do not need Claude in the loop to use them, and running them by hand is the fastest way to build trust in the system:

6.8 Inspect

1. logs/init-report.md — the ingested-files table, the scan-level counts, and the append-only Decision history.
2. .claude/safety-status.json — every key an absolute path, every value one of the seven status strings.
3. README.md — auto-generated, and genuinely worth reading once: it contains the decision-flow diagram and the effects table for each status.
4. CLAUDE.md — confirm the auto-managed block is present and says v2-lean (or v2-full after an orchestrator run).

Stop and check. Point at one file marked LOCAL_MODE and say, out loud, (a) why it was flagged, (b) what a script may still compute from it, and (c) what would happen if you asked Claude to head it. If you cannot answer all three, do not brainstorm yet.

7. scholar-brainstorm — widen the question menu

Goal: produce a ranked list of candidate research questions, each with variables, method sketch, and risks. Do not ask brainstorming to pick your dissertation; ask it to widen the menu.

7.0 Three modes — auto-detected from your inputs

scholar-brainstorm operates in three modes and chooses one automatically based on what you point it at:

The auto-detection looks at file extensions and (for PDFs) at content — a PDF with “Abstract / Introduction / Methods / References” is classified as PAPER; a PDF with “Variable / Codebook / Questionnaire” as MATERIALS.

All three modes share the same downstream pipeline: literature scan → Top-10 shortlist → 5-role evaluation panel (five Task-dispatched evaluator prompts — theorist, methodologist, domain expert, editor, devil’s advocate — internal to scholar-brainstorm; these are skill-internal roles, not entries in .claude/agents/) → refined Top-10 → research program overview → executive summary. Only Steps 0–4 differ.

The CFPS digital-divide example uses MATERIALS mode. We walk through that first, then show how the same project would look in DATA and PAPER modes.

7.1 MATERIALS mode — start from a codebook

Use this when you have codebooks or questionnaires but the raw data is not yet ingested — either because access is pending, or because you deliberately want a theory-driven menu before touching the data.

7.1.1 Run

> /scholar-brainstorm materials top 5 RQs on digital divide in China,
                       target Social Forces, descriptive/decomposition

The skill detects MATERIALS mode (codebooks present, no data/raw/ opened directly), reasons over the questionnaires and the variable dictionary, and queries verified sources. About 4–7 minutes on a typical run. Cost in this run: ≈ $1.20.

7.1.2 Real output (truncated)

From output/digital-divide-china-cfps/ scholar-brainstorm- digital-divide-china-cfps-top5-summary-2026-05-05.md:

# Research Question Brainstorm — Executive Summary
## Digital Divide in China Using CFPS Materials
*Generated by /scholar-brainstorm on 2026-05-05*
*Operating mode: MATERIALS*

## Top 5 RQs

### #1: Access Convergence, Use Divergence
**RQ:** In China from 2010 to 2020, did the hukou, education, and cohort gaps
in internet access narrow while gaps in productive use, use intensity, and
use breadth persisted or widened?
**Variables:** U201, U202, U250M, U701-U705, hukou, education, cohort,
gender, income, household composition.
**Why strongest:** Best flagship paper. Uses CFPS panel structure to separate
first-level access from second-level productive use.
**Method sketch:** Panel models, wave/province controls, individual fixed
effects where feasible, Oaxaca decomposition of rural-hukou gaps.

### #2: Remote-Work Divide During COVID-19   […]
### #3: Online-Learning Outcome Divide        […]
### #4: Older-Adult Digital Health and Social-Connection Divide  […]
### #5: Information Trust, Privacy Concern, and Platform Dependence  […]

## Recommendation
Pursue RQ1 as the main paper. […]

7.1.3 Files written (MATERIALS mode)

output/<slug>/
├── scholar-brainstorm-<slug>-<date>.md         ← full report (15–20 candidates)
├── scholar-brainstorm-<slug>-summary-<date>.md ← exec summary (Top 5 + recommendation)
└── logs/process-log-scholar-brainstorm-<date>.md

Plus a .docx, .tex, and .pdf of each (rendered via pandoc).

7.1.4 Inspect

Open the full file. Check four things:

1. Variable claims — does CFPS actually have U201, U250M? (Use the codebook.)
2. Verified sources — every external citation should resolve. Click them.
3. Risks surfaced — for RQ5 the brainstorm correctly notes “some 2020 items are restricted data”. Good.
4. Over-broad RQs — RQ4 (“does internet use improve health among older adults”) is too broad. The output flags this honestly.

Stop and check. Choose one RQ to carry forward. The rest of the handbook follows RQ1, because it is feasible, theoretically connected, and measurable.

7.2 DATA mode — start from the data itself

Use this when the raw data is already on disk and resolved by scholar-init. DATA mode adds two things that MATERIALS mode cannot:

1. A safety gate — before reading anything, the skill checks .claude/safety-status.json (the sidecar scholar-init wrote). If any input file is NEEDS_REVIEW:* or HALTED, the skill refuses to run and tells you to fix it via /scholar-init review. If the sidecar is missing, the skill falls back to a grep-only local scan that emits only counts of PII / HIPAA / restricted markers — never the matching values.
2. Empirical signal tests — for each of the 15–20 candidate RQs, the skill writes one R script (scripts/brainstorm-signal-tests.R), submits it to a 3-agent pre-execution code review, then runs it. Each candidate gets a real bivariate effect size (Cohen’s d for continuous outcomes, η² for ANOVA, Cramér’s V for cross-tabs, Pearson’s r for correlations) and a signal rating: STRONG, MODERATE, WEAK, NULL, MECHANISM PLAUSIBLE, MODERATION DETECTED, or UNTESTABLE.

The Top-10 score then weights these six criteria — novelty 20%, data readiness 15%, theory 20%, identification 15%, publication potential 10%, empirical signal 20% — instead of the 5 criteria used in MATERIALS / PAPER mode.

7.2.1 Run (the version we would have used on the CFPS example)

> /scholar-brainstorm data/raw/cfps_panel_long.rds
                     top 5 RQs on digital divide in China,
                     target Social Forces

If scholar-init had already classified the file as LOCAL_MODE, the skill inherits that decision (the “scholar-init handshake”) and runs all empirical tests via Rscript brainstorm-signal-tests.R heredocs — Claude itself never Reads the data.

7.2.2 What you would see — the signal table

A typical DATA-mode signal table looks like this:

EMPIRICAL SIGNAL TABLE  (sample sizes from cfps_panel_long.rds)

| RQ | x_var       | y_var       | test   | n     | effect_size      | p       | signal   |
|----|-------------|-------------|--------|-------|------------------|---------|----------|
| 1  | hukou_rural | y2_hours    | t-test | 119k  | d = -0.42 (med.) | 1.4e-5  | STRONG   |
| 1  | cohort      | y1_access   | χ²     | 148k  | V = 0.31 (med.)  | <1e-60  | STRONG   |
| 2  | mobile_only | covid5      | t-test | 34k   | d = +0.18        | 4.2e-3  | MODERATE |
| 4  | u703_social | sf12_mh     | r      | 41k   | r = +0.11        | 7.8e-4  | WEAK     |
| 5  | u11_wechat  | u13_trust   | r      | 26k   | r = +0.08        | 0.04    | WEAK     |

Caveats the skill prints alongside the table (verbatim):

• Signals are bivariate-only — confounding is not addressed here.
• Multiple-testing corrections are NOT applied at this stage; do not treat any single p as a confirmatory test.
• NULL is not the same as “uninteresting” — it can mean the gap is mediated by other variables.

7.2.3 The pre-execution code review

Before any Rscript actually executes, the skill spawns three review agents in parallel against the signal-test script:

• review-code-correctness — variable references, NA handling, off-by-one
• review-code-statistics — correct test for the variable types, effect-size package usage
• review-code-data-handling — sample restrictions, missing-value codes, codebook alignment

Their output is aggregated into scripts/brainstorm-signal-tests-review.md with severity tags. The execution gate has four resolutions:

• PROCEED — no CRIT/MAJOR findings; run the script.
• FIX-AND-RERUN — fix the flagged issues, re-review, then run.
• OVERRIDE — user types a rationale ≥ 20 chars; logged to the process log.
• HALT — stop the skill; no candidate is worth running as-is.

This means DATA mode produces a real audit trail before any data is touched — exactly the discipline the workshop teaches.

7.2.4 Files written (DATA mode)

In addition to the two MATERIALS-mode files, DATA mode also writes:

output/<slug>/scripts/
├── brainstorm-signal-tests.R                  ← the actual R script (auditable)
├── brainstorm-signal-tests.log                ← stdout from running it
├── brainstorm-signal-tests-review.md          ← aggregated 3-agent review
├── brainstorm-signal-tests-review-correctness.md
├── brainstorm-signal-tests-review-statistics.md
└── brainstorm-signal-tests-review-data-handling.md

Replication-ready by design — scholar-replication will pick these up automatically later.

7.2.5 Inspect (DATA mode adds two checks)

In addition to the four MATERIALS-mode checks, also verify:

1. The signal-test script is real R, not pseudocode. Open scripts/brainstorm-signal-tests.R, run head -40 on it. Every test should be wrapped in tryCatch() so one failing candidate does not crash the run.
2. Effect sizes use proper packages. The script must use effectsize::cohens_d(), effectsize::eta_squared(), effectsize::cramers_v() — not hand-rolled formulas.

Stop and check. Look at the signal table above. Would you treat the WEAK signal on RQ5 as “this hypothesis is dead”? No — it might just mean the test is bivariate and needs covariates. The signal is one input to the Top-10 score, not a verdict.

7.3 PAPER mode — start from a published paper

Use this when you’ve read a paper and want a structured menu of follow-up projects: methodological extensions, population transfers, mechanism deepening, limitation address-als, or computational upgrades.

PAPER mode is triggered three ways:

# (a) PDF on disk
> /scholar-brainstorm ~/papers/li-ouyang-hu-2025-digital-divide-aging.pdf

# (b) DOI string
> /scholar-brainstorm 10.1038/s41746-025-02076-1

# (c) Pasted abstract (just paste a "Title: ... Abstract: ..." block in the chat)
> /scholar-brainstorm
> Title: A ten-year analysis of digital divides among older Chinese adults
> Abstract: Using six waves of CFPS we document persistent age-related gaps in [...]

7.3.1 What the skill does

1. Extract the seed paper’s elements — title, abstract, core findings, methods used, limitations the authors acknowledge, future directions they suggest, theoretical framework, population/context, data source. (For DOIs the skill calls the CrossRef API; for PDFs it uses pdftotext; for pasted abstracts it parses inline.)
2. (Optional) SciThinker ideation — if HF_TOKEN is set in the environment, the skill calls OpenMOSS-Team/SciThinker-30B on HuggingFace with a structured prompt asking for one follow-up paper title + abstract. If HF_TOKEN is missing or the call fails, the step is logged as SKIPPED and the run continues with Claude-only ideation.
3. Claude expansion — generate 15–20 candidate follow-up RQs across eight dimensions:

| Dimension              | Strategy                                              |
|------------------------|-------------------------------------------------------|
| Methodological extension | Apply a stronger / different method to the same Q   |
| Population transfer    | Same Q, different population or context               |
| Mechanism deepening    | Test the proposed mechanism directly                  |
| Limitation address-al  | Tackle a limitation the original authors named        |
| Scope expansion        | Broaden to a related phenomenon                       |
| Contradictory test     | Design a study that could falsify the finding         |
| Computational upgrade  | Apply NLP/ML to reveal patterns the original missed   |
| SciThinker proposals   | Refine and ground the AI-generated ideas in theory    |

1. Standard pipeline — every candidate goes through literature scan → Top-10 shortlist → 5-agent evaluation panel → refined Top-10 → research program overview, identical to MATERIALS / DATA mode.

7.3.2 What you would see for the CFPS digital-divide seed

If you ran PAPER mode on Li, Ouyang, & Hu (2025), the kinds of follow-up RQs you would expect to see:

#1 (Mechanism deepening) — Does household digital transmission (co-resident
   young-adult presence) attenuate the age-related digital divide identified
   by Li et al.? CFPS family-conf links + intra-household FE.

#2 (Population transfer) — Does the same age × digital exclusion pattern hold
   in the rural migrant population, where hukou + age compound? CFPS migrant
   sub-sample.

#3 (Limitation address-al) — The seed paper notes it cannot separate cohort
   from age. Apply HAPC + Deaton-Paxson bounds to the same panel.

#4 (Methodological extension) — The seed paper uses descriptive trends.
   Apply Oaxaca-Blinder decomposition to the rural-urban Y2 gap to separate
   endowment from coefficient components.

#5 (Computational upgrade) — Use STM topic models on CFPS open-text items
   about internet use to identify use-type heterogeneity that the closed
   items cannot.

(If you had scoped the digital-divide focal paper from a seed paper instead of from the CFPS codebook, this is the shape PAPER mode would have produced — treating Li et al. as the seed and identifying the second-level / institutional gap as the unfilled lane. The actual workshop run used MATERIALS mode, per §7.1.)

7.3.3 Files written (PAPER mode)

output/<slug>/
├── scholar-brainstorm-<slug>-<date>.md          ← full report
├── scholar-brainstorm-<slug>-summary-<date>.md  ← exec summary
└── logs/
    ├── process-log-scholar-brainstorm-<date>.md
    └── scithinker-response-<date>.txt           ← raw SciThinker output if called

7.3.4 Inspect (PAPER mode)

Use the four MATERIALS-mode checks, plus:

1. Connection to the seed. Each candidate should explicitly say which seed-paper element it extends (a finding? a limitation? a stated future direction?). If a candidate cannot cite a specific anchor in the seed, it is hallucination, not extension.
2. SciThinker grounding. If SciThinker was called, its proposals appear flagged. They are seed ideas, not finished RQs. Treat them as Claude treats them — refine, theorize, and ground them before scoring.

Stop and check. PAPER mode is the easiest mode to misuse: it is tempting to take its top-ranked follow-up and start writing. Don’t. Run the chosen candidate back through scholar-idea (§8) and scholar-design (§9) before committing — PAPER mode is a menu generator, not a design.

8. scholar-idea — sharpen the puzzle

Goal: turn an area into a specific puzzle, with mechanisms, scope conditions, hypotheses, and a fatal-flaw screen.

8.1 Run

> /scholar-idea broad puzzle: "China's digital divide — access converging
  while use intensity persists by hukou, cohort, and gender"
  data: CFPS 2010-2020 long panel
  target: Social Forces

8.2 Real output (excerpt from idea/scholar-idea-...md)

## Step 1 — The Puzzle

China entered 2024 with the world's largest internet user base (1.07 billion
CNNIC), yet remains a textbook case of *layered* digital inequality. The
first-order access gap has narrowed sharply since 2015, but second-order
(skill, autonomy of use) and third-order (returns to use) gaps appear to
have widened — particularly along hukou, generational, gender, and
educational lines.

## Step 2 — Candidate Angles

| # | Framing                | Mechanism                       | Rival explanation     |
|---|------------------------|---------------------------------|-----------------------|
| A | Hukou as durable axis  | Institutional sorting           | Pure SES absorbs hukou|
| B | Cohort-as-cause        | Birth-cohort socialization      | Period effects        |
| C | Household as skill unit| Intra-household spillovers      | Selection             |
| D | Gender × age × hukou   | Triple penalty                  | Additive only         |
| E | Returns to engagement  | Capital-conversion (Bourdieu)   | Equal returns         |

Angles A, B, D tractable in CFPS. E demoted to discussion.

## Step 5 — Hypotheses

H1 (hukou persistence). Net of X3, X4, regional infrastructure, agricultural-
hukou status reduces the probability of access (Y1) and weekly use hours
(Y2). The hukou effect on Y1 narrows across waves (access convergence) but
the hukou effect on Y2 does not (skill-use divergence).

H2 (cohort layering). Birth cohorts post-1985 show systematically higher Y1
and Y2 net of period and age. Within cohort, the age trajectory of Y2 is
flat — i.e., the divide tracks cohort replacement, not within-person
learning.

H3 (intersectional triple penalty). A three-way interaction (rural-hukou ×
female × born ≤ 1965) yields a use-intensity penalty larger than the sum
of the three additive marginal effects.

H4 (household spillover, secondary). Co-residence with at least one digital-
native (born ≥ 1990) is associated with higher Y1 and Y2 for older members.

8.3 What to look for

• Hypotheses are pre-specified. H1 has a directional prediction and a “narrows on Y1 but not on Y2” subtlety. That is good — it means the analysis can falsify the institutional account, not just confirm it.
• Forbidden language is named. The memo records the forbidden causal language and the descriptive-only design (“no causal interpretation of hukou; descriptive design only”).
• One hypothesis is high-risk. H3 is an intersectional claim. Decide now whether you are willing to publish a null if the data show the triple penalty is just additive. (Spoiler: in our run, H3 turned out null, and we kept the null in the paper.)

Stop and check. Can you state the directional prediction of each hypothesis in one sentence, without consulting the document? If not, the puzzle isn’t sharp enough yet.

8A. scholar-lit-review-hypothesis — integrated lit review + theory + hypotheses

Goal: in one workflow, map the existing literature, identify the unresolved gap, choose the theoretical framework that addresses that gap, specify the mechanism, and derive testable hypotheses — producing a publication-ready Literature Review and Theory section.

This skill replaces running /scholar-lit-review and /scholar-hypothesis separately. Use it after /scholar-idea (§8). For the CFPS digital-divide paper, this is the skill that wrote the entire 1,400-word “Theoretical Framework” + “Hypotheses” block in drafts/manuscript-final-...md.

8A.1 The five-step internal logic

The skill enforces a single five-step argument — every step feeds the next, and the prose cannot drift away from this chain.

8A.2 Run

> /scholar-lit-review-hypothesis
   RQ: In CFPS 2010-2020, did hukou/cohort gaps in internet access narrow
       while gaps in weekly use hours persisted?
   target: Social Forces
   anchor theories: layered digital divide; hukou as institutional sorting;
                    cumulative advantage; cohort-as-cause

The skill executes a tiered literature search:

• Tier 0 — knowledge graph — the cross-project scholar-knowledge graph, queried first when configured
• Tier 1 — local library (Zotero / Mendeley / BibTeX / EndNote) — verified citations
• Tier 2 — external APIs — CrossRef, Semantic Scholar, OpenAlex, Google Scholar
• Tier 3 — WebSearch — only for residual gaps

Then it runs an anti-plagiarism + claim-verification panel: three Task-dispatched evaluator prompts in parallel (originality-auditor, claim-verifier, attribution-analyst — skill-internal roles, not entries in .claude/agents/) cross-check every paraphrased sentence against the source, every effect-direction claim against the cited paper, and every citation against the local library. The agreement matrix is appended to the output.

8A.3 Real output (excerpt from the CFPS run)

The skill produced the following Hypotheses block — verbatim, this is what ended up in the final manuscript:

## Hypotheses

H1 (Hukou persistence and access-intensity divergence). Net of education,
household income, occupation, and province-level infrastructure, agricultural-
hukou status reduces both the probability of internet access and the weekly
hours of internet use among users. The hukou coefficient on internet access
narrows monotonically across the 2010-2020 panel waves, consistent with
access convergence. The hukou coefficient on weekly internet hours does not
narrow, and may widen, consistent with the institutional-sorting mechanism
producing a durable second-level divide.

H2 (Cohort layering, not within-person learning). Birth cohorts born after
1985 exhibit systematically higher internet access, weekly internet hours,
and use breadth than earlier cohorts, net of period and chronological age.
Within cohort, the within-person age trajectory of weekly internet hours is
approximately flat. Aggregate population-level growth in weekly internet
hours across waves is therefore primarily driven by cohort replacement.

H3 (Intersectional triple penalty). The use-intensity penalty associated
with the joint condition rural-hukou × female × born ≤ 1965 exceeds the
sum of the three additive marginal effects.

H4 (Household spillover, secondary). Co-residence with at least one
digital-native household member (born 1990 or later) is associated with
higher internet access and weekly internet hours for older co-residents,
with the spillover larger for women and rural residents.

Notice the causal-language calibration — H1 says “is associated with” / “reduces the probability of,” not “causes.” That is enforced by the skill’s explicit rule: hypotheses for observational designs without IV / RD identification must use associational language.

8A.4 Files written

output/<slug>/
├── drafts/scholar-lrh-<slug>-<date>.md             ← lit review + theory + hypotheses (+ .docx/.tex/.pdf)
├── drafts/scholar-lrh-<slug>-<date>.bib            ← materialized by /scholar-citation MODE 6b (not hand-authored)
├── logs/
│   ├── process-log-scholar-lit-review-hypothesis-<date>.md
│   └── scholar-search-log-<slug>-<date>.md         ← every query + hit count
└── reports/
    ├── source-integrity-panel-<date>.md            ← 3-agent verification
    ├── source-integrity-originality-<date>.md
    ├── source-integrity-claim-<date>.md
    └── source-integrity-attribution-<date>.md

8A.5 Inspect

1. Every paraphrased sentence in the lit review must trace to a verified citation in refs.bib. Open the source-integrity panel report to see which sentences flagged.
2. Every hypothesis must derive from a named mechanism. If the hypothesis appears without a mechanism step in the prose above it, the chain is broken.
3. Causal-language audit. Search the draft for “causes,” “leads to,” “effect of.” For observational designs without identification, every hit is a candidate for revision.

8A.6 The evidence ledger — what you actually read, next to what you wrote (v5.28)

The tier hierarchy in §8A.1 says where a citation may come from. It does not say what you read before you wrote the sentence. Since v5.28 that is a separate file, and it is the artifact behind this section’s promise that every paraphrased sentence traces to a source.

Whenever a source passage becomes the basis of a finalized claim, one record is appended to evidence/claim-anchors.ndjson: the verbatim quote (≤ 60 words), a locator, the tool that retrieved it, and an honest label for how good the evidence actually was.

Two rules do all the work:

1. Discovery is not capture. A 25-hit search produces no anchors. Capture happens when a claim is finalized — a landscape-map cell, an effect magnitude, a hypothesis premise, a drafted sentence. Searching is not reading.
2. Capture is tier-honest. Anchor with the best evidence already in context. An abstract snippet is a legal anchor (T3_abstract). When nothing is quotable the record carries evidence_quote: null — which makes “cited on metadata alone” visible instead of silent.

Read the ledger’s tier label carefully — it is not the Tier 0–2 hierarchy above. The ledger’s access_tier answers how good is the evidence I read: T1_fulltext (a PDF, or a rag_search hit) > T2_oa_fulltext > T3_abstract > T4_none. The citation tiers answer where may this citation come from. Same word, different axis. A paper can be Tier-1 verified and still anchored at T3_abstract — you confirmed it exists; you only ever read the abstract.

Downstream this produces an Evidence Dossier pairing “what the source said” against “what we wrote,” and a required log row Evidence anchors: N created / M reused. scholar-write and scholar-citation consume the ledger rather than re-deriving it (§14, §16), and Phase 7 carries a tag gate that checks it.

Quotes live only under evidence/, and are excluded from replication packages by default — verbatim third-party text is exactly what you do not want to redistribute by accident.

Stop and check. Can you point at one citation in the draft, open the BibTeX file, and find the matching key? If not, run /scholar-citation verify (§16) before going further. Then open evidence/claim-anchors.ndjson and count how many of your finalized claims are anchored at T3_abstract or T4_none. That number is the honest size of what you are citing without having read.

8B. scholar-conceptual — build the theory object, not the prose

Goal: produce the theoretical objects a paper rests on — typologies, mechanism chains, multi-level frameworks, scope conditions, process models — and render them as publication-quality figures (TikZ → PDF, with Mermaid as a fallback).

This is not hypothesis derivation (/scholar-hypothesis does that), and not identification (/scholar-causal does that — see §8D for the fourteen identification strategies and the DAG / Potential-Outcomes scaffolding it ships with). scholar-conceptual works at the level of theory construction: what is the theory made of, and how do its parts connect?

8B.1 Two modes

argument-hint: "[theorize|diagram] [topic], e.g., 'theorize a framework for
                digital labor precarity' or 'diagram mechanism model for
                segregation and health'"

> /scholar-conceptual theorize a typology of immigrant civic incorporation
> /scholar-conceptual diagram multi-level model for algorithmic management
> /scholar-conceptual full framework with figure for cumulative disadvantage

THEORIZE further classifies the task into eight types — typology construction (Lazarsfeld property-space), process theorizing, mechanism specification (Coleman’s boat / Hedström DBO), scope-condition mapping, multi-level model, abductive theory-from-anomaly, synthetic framework, concept clarification.

Two things this skill deliberately does not do. It will not make identification claims — those route to /scholar-causal. And it is the only skill in this part of the suite that dispatches no subagents at all: it has a narrow tool list and no verification panel, so its output is checked by you, or by /scholar-auto-improve observe afterwards.

The HARKing disclosure gate. scholar-conceptual carries the suite’s theoretical-pivot protocol, which fires when all three conditions hold: (a) the project has pre-registered hypotheses, (b) at least one focal hypothesis came back null or opposite-signed, and (c) the Discussion now introduces a theoretical concept that was not in the original account list — or uses reframe-signal phrases like “reinterpret as,” “post-hoc explanation,” or “in retrospect.”

When it fires, you must produce design/theoretical-pivot.md recording the pre-registered account and its status per hypothesis, the pivot account and its inferential status, what changed and what did not, and guidance for the reader — and tag the affected manuscript sections [REGISTERED] or [EXPLORATORY].

Note carefully what this is not: it is not a prohibition on post-hoc reframing, which is a normal and often valuable part of research. It is a requirement to disclose and bound it. Reframing after a null result is legitimate; presenting the reframe as though you had predicted it is not.

8B.2 Run (the digital-divide example)

> /scholar-conceptual build mechanism model: access convergence,
                    persistent intensive-use stratification,
                    hukou and cohort sorting
                    target: Social Forces
                    diagram type: Coleman's boat

What the skill writes:

• output/<slug>/theory/mechanism-memo-<date>.md — a 1,500-word memo naming each mechanism step (institutional sorting → infrastructural exposure → skill formation → use-intensity stratification), with rival explanations explicitly listed and each arrow’s falsifying evidence stated.
• output/<slug>/figures/fig-mechanism-coleman.tex — TikZ source for a Coleman’s-boat diagram (macro condition → individual situation → individual action → macro outcome).
• output/<slug>/figures/fig-mechanism-coleman.pdf — compiled vector PDF, ready to drop into LaTeX.
• output/<slug>/figures/fig-mechanism-coleman.mmd / .svg — Mermaid fallback (renders quickly during iteration).

8B.3 The compiled figure — Coleman’s boat for the CFPS case

The skill emits ready-to-compile TikZ, and latexmk / xelatex compiles it to a standalone PDF you can drop straight into the manuscript. Here is the real compiled output from running this skill on the digital-divide project — not a redrawn mock-up:

Underneath, the TikZ source the skill wrote (excerpt — full file at output/<slug>/figures/fig-mechanism-coleman.tex in a fresh run; in this handbook artifact it was emitted to output/theory/fig-mechanism-coleman.tex because the run pre-dated the standardized figures/ layout):

\begin{tikzpicture}[
  box/.style={draw=primary, rounded corners=3pt,
              minimum width=3.6cm, minimum height=1.1cm,
              align=center, font=\small, fill=white},
  macrobox/.style={box, fill=lightbg, font=\small\bfseries},
  arrow/.style={-{Stealth[length=7pt]}, primary},
  microarrow/.style={-{Stealth[length=7pt]}, accent},
  label/.style={font=\scriptsize\itshape, muted}]

% MACRO LEVEL
\node[macrobox] (M1) at (0, 3) {Hukou system\\(institutional sorting)};
\node[macrobox] (M2) at (10, 3) {Population-level\\use-intensity gap (Y2)};

% MICRO LEVEL
\node[box] (m1) at (2.6, 0) {Differential digital\\infrastructure exposure};
\node[box] (m2) at (7.4, 0) {Differential\\skill conversion};

% Coleman arrows: 4 numbered legs of the boat
\draw[arrow]      (M1) -- (M2) node[midway, above, label] {Observed gap (descriptive)};
\draw[microarrow] (M1.south) -- (m1.north) node[midway, left,  label] {(1) Situational};
\draw[microarrow] (m1) -- (m2) node[midway, below, label] {(2) Action-formation};
\draw[microarrow] (m2.north) -- (M2.south) node[midway, right, label] {(3) Transformational};
\end{tikzpicture}

The skill also writes a figure caption block ready to paste under the figure in your manuscript, and a Rival explanations to test: checklist (visible at the bottom of the compiled diagram) — these are the empirical falsifiers the paper must address in its robustness section.

8B.4 Eight diagram types the skill can render

8B.5 Inspect

• Every arrow needs a labeled mechanism. Open the diagram. If an arrow has no label, it is a graphic element pretending to be theory.
• Every box should have a falsifier. The memo should state, for each box and each arrow, what observation would weaken the claim. If a participant cannot answer “what evidence would falsify this arrow,” the diagram is decorative.

Stop and check. Hand the figure to a labmate without the memo. Can they reconstruct the mechanism story from the diagram alone? If not, the diagram is over-stylized and under-informative — re-run with more labels.

8C. scholar-knowledge — the cross-project memory layer

Goal: maintain a single, user-scoped knowledge graph across all your projects so that every paper you ingest, every finding you extract, every method note, and every relationship between papers is reusable next time. This is what stops the agent from re-discovering the same literature on every project.

This is the most under-used skill in the suite and arguably the most valuable. The CFPS digital-divide paper, the CFPS hukou-marriage paper, and a dozen others in the audited corpus all share the same intellectual neighborhood — Wu & Treiman 2004, Xie & Jin 2015, van Deursen & Helsper 2015, DiMaggio et al. 2004, etc. Without scholar-knowledge, each project starts from zero. With it, ingestion is an investment that pays back forever.

8C.0 Three ways to SELECT — and why a wiki, not just RAG

Getting the right text into the model’s window (the “SELECT” move) has three distinct strategies, and scholar-knowledge is the third:

• RAG — chunk your corpus, embed it, and at query time pull the top-K nearest chunks by vector similarity. Fast and scalable, but it returns opaque fragments ranked by surface similarity, the index goes stale when sources change, and you cannot easily read why a chunk was chosen.
• Agentic search — no index; the agent greps and reads the live files in a loop (this is how Claude Code reads your repo). Always current and fully auditable, but bounded by what a handful of searches can reach, and it re-reads from scratch every session.
• Knowledge wiki (the “LLM-wiki” approach) — the model reads each source once, extracts the findings, mechanisms, and relationships, and writes them as a human-readable, interlinked markdown wiki. To answer, it reads the index page and follows [[links]] to the few pages that matter. This is exactly what /scholar-knowledge compile and ask do.

Why a wiki can beat RAG for a corpus you return to: the synthesis is precomputed (topic overviews, contradictions.md, gaps.md) instead of re-derived on every query; relationships are explicit links you can traverse (extends, contradicts, same-dataset), not implicit vector neighbours; it is just markdown — auditable, editable, and needs no embedding model or vector database; and it compounds — you file your own outputs back in, so paper #5 stands on the shoulders of #1–4. The cost is that extraction is upfront and lossy (the wiki is the model’s reading of a source, not the source — which is why raw/ keeps the originals), and the wiki must be kept current (the LLM maintains it; you rarely edit by hand). This is Andrej Karpathy’s “LLM wiki” idea: the model writes and maintains the knowledge base, and you file outputs back to enrich it for future queries.

The three are complementary, not rivals. Keep the wiki as durable memory, wrap a live retriever (OpenAlex, Zotero) as an MCP tool for reach (Lab 3 §4b), and let the agent choose which to reach for. As of v5.27 the suite ships the first strategy too — scholar-rag (§8F) builds a real local vector database over the same library and exposes it as MCP tools, so you no longer have to choose: the wiki holds the synthesis, the vector index holds the verbatim passages, and both key on the same paper identity. To see the whole mechanism in ~250 lines of dependency-free Python — ingest → graph → compile → navigate — run the Day-3 demo:

cd demo/day3-claude-code/llm-wiki
python3 build_wiki.py     # 7 papers -> graph -> 34 interlinked wiki pages
python3 ask.py "why doesn't closing the access gap close the divide?"

ask.py prints the exact navigation path (index.md → topics/… → concepts/… → papers/…), making the contrast with RAG’s opaque top-K concrete.

This graph is also the seed for scholar-rag’s GraphRAG (§8F). rag_py graphrag.py seed imports these concepts and citation edges before any LLM extraction runs — it is the fast, no-LLM head start. On a 5.5k-paper library the seed edges alone reached about 12% of the corpus, which is why §8F.6’s citation and semantic stages exist. The two skills are complementary: scholar-knowledge answers what does the field claim, scholar-rag answers show me the passage, cited.

8C.1 What lives where

~/.claude/scholar-knowledge/                (override with $SCHOLAR_KNOWLEDGE_DIR)
├── papers.ndjson         ← one JSON object per paper (rich extracted content)
├── concepts.ndjson       ← named concepts, theories, mechanisms
├── edges.ndjson          ← inter-paper relationships (cites, contradicts, extends, …)
├── meta.json
└── raw/                  ← APPEND-ONLY archive of original sources
    ├── pdfs/             ← symlinks to Zotero PDFs (no copies of large files)
    ├── abstracts/        ← extracted text
    ├── api-responses/    ← raw CrossRef / Semantic Scholar JSON
    ├── web/              ← fetched preprints, NBER WPs, blog posts
    └── images/           ← figures extracted from PDFs (per-paper subdirs)

A single paper node looks like this (real schema, abbreviated):

{
  "id": "fiel-zhang-2018",
  "doi": "10.1007/s13524-017-0632-9",
  "title": "Three Dimensions of Change in School Segregation: A Grade-Period-Cohort Analysis",
  "authors": ["Fiel, Jeremy E.", "Zhang, Yongjun"],
  "year": 2018,
  "journal": "Demography",
  "findings": ["Age-period-cohort decomposition of U.S. public-school segregation, 1999–2000 to 2013–2014, separates grade, period, and cohort effects on between-school segregation."],
  "mechanisms": ["compositional change (demographic shifts)", "cohort succession"],
  "theories": [{"name": "spatial assimilation", "role": "tests"}],
  "methods": ["age-period-cohort decomposition", "multilevel models"],
  "populations": ["K-12 students in US public schools"],
  "data_sources": ["Common Core of Data (CCD)"],
  "limitations": ["Data limited to public schools"],
  "future_directions": ["Within-district heterogeneity at the classroom level"],
  "projects": ["segregation-paper-2026", "digital-divide-china-cfps"],
  "raw_path": "abstracts/fiel-zhang-2017.txt"
}

The point is the findings, mechanisms, methods, limitations, future_directions fields — stuff your reference manager does not store, but stuff you reach for constantly.

Edges look like:

8C.2 The eight modes — concrete commands

Mode 1 — INGEST: bulk-load from Zotero

> /scholar-knowledge ingest from zotero collection "digital divide"
> /scholar-knowledge ingest from zotero tag "hukou"
> /scholar-knowledge ingest from zotero keyword "second-level digital divide" 30

For each paper found:

1. Read Zotero SQLite → bibliographic metadata
2. Symlink the PDF (no copy) into raw/pdfs/<slug>.pdf
3. Run pdftotext on the first 400 lines for extraction
4. Optionally extract figures via pdfimages (if poppler is installed)
5. Extract findings, mechanisms, theories, methods, populations, data sources, limitations, future directions, key quotes (with page numbers when available)
6. Append a paper node to papers.ndjson
7. Append concept nodes for any new theories/mechanisms
8. Re-deduplicate by DOI / title hash so re-ingesting is idempotent

Mode 1 — INGEST: from PDF, DOI, URL, or your own work

> /scholar-knowledge ingest from pdf ~/papers/li-ouyang-hu-2025.pdf
> /scholar-knowledge ingest from doi 10.1038/s41746-025-02076-1
> /scholar-knowledge ingest from url https://www.nber.org/papers/w29234
> /scholar-knowledge ingest from output \
       output/digital-divide-china-cfps/drafts/manuscript-final-2026-05-04.md

The last one — from output — is the feedback loop. After every paper you finish, ingest your own work back into the graph. The paper type becomes "own_work" and the findings become searchable for your next project.

Mode 2 — SEARCH

> /scholar-knowledge search "second-level digital divide China"
> /scholar-knowledge search papers using-method "Oaxaca-Blinder"
> /scholar-knowledge search papers contradicts spatial-assimilation

Returns paper IDs, titles, ranked relevance, and a short rationale per hit. Feeds directly into scholar-lit-review-hypothesis (§8A) — instead of asking external APIs first, the lit-review skill reads papers.ndjson first.

Mode 3 — RELATE: the edges you assert yourself

Ingestion extracts findings; it does not claim two papers disagree. That edge is a scholarly judgement, so you make it — and then it is queryable.

> /scholar-knowledge relate [Paper A] contradicts [Paper B]
> /scholar-knowledge relate [Paper A] extends [Paper B]
> /scholar-knowledge relate show relationships for [Paper A]
> /scholar-knowledge relate show all contradicts
> /scholar-knowledge relate map residential segregation

Both papers must already be in the graph; if one is missing the skill offers to ingest it first rather than inventing a node. contradicts is the one worth the effort — a literature review that can enumerate its own disagreements is doing something a summary cannot.

Mode 4 — STATUS (the dashboard)

> /scholar-knowledge status

Real output:

Knowledge graph at ~/.claude/scholar-knowledge
  Papers:   1,142
  Concepts: 287
  Edges:    3,901
  Raw archive: 4.2 GB across 1,142 PDFs and 318 web fetches

Top theories (by paper count):
  1. cumulative advantage / Matthew effect            (87 papers)
  2. spatial assimilation                             (54 papers)
  3. layered (three-level) digital divide             (41 papers)
  4. hukou as institutional sorting                   (33 papers)
  5. second-demographic transition                    (29 papers)

Coverage gaps (theories with <3 papers):
  - distributed cognition + digital practice (1 paper — extend)
  - intersectional algorithmic harm           (2 papers — extend)
  - capability approach × digital inclusion   (0 papers — gap)

Project tags:
  digital-divide-china-cfps    (76 papers)
  hukou-marriage-cfps           (94 papers)
  segregation-paper-2026       (108 papers)
  …

Mode 5 — EXPORT: a subset, for one project or one bibliography

> /scholar-knowledge export for project digital divide
> /scholar-knowledge export for collection [zotero collection]
> /scholar-knowledge export by author [name]
> /scholar-knowledge export all as bibtex

Markdown is the default; as bibtex writes a .bib. Use this to hand a collaborator the slice of your graph that touches one paper, without handing them your whole library.

Mode 6 — COMPILE: turn the graph into an Obsidian wiki

> /scholar-knowledge compile

Produces a fully linked markdown wiki at ~/.claude/scholar-knowledge/wiki/ with one page per paper, one page per theory/mechanism, and [[wiki-link]] cross-references throughout. Open in Obsidian (or any markdown viewer) and the graph view becomes browsable. Re-run after every ingest pass.

Mode 7 — ASK: research questions across the graph

> /scholar-knowledge ask what are the main theories of the second-level digital divide?
> /scholar-knowledge ask compare the mechanisms in van Deursen & Helsper 2015 \
                     vs Hargittai 2002
> /scholar-knowledge ask which CFPS papers in my graph use Oaxaca-Blinder decomposition?

The skill reads the compiled wiki and answers with paper-level citations. Every claim it makes is grounded in the wiki, so hallucinated references are bounded by what you’ve actually ingested.

Mode 8 — RE-EXTRACT: upgrade the schema

When you add a new field to the paper node (e.g., “data-availability statement” or “preregistration link”), run:

> /scholar-knowledge re-extract all abstract_only
> /scholar-knowledge re-extract field=data_availability

The skill walks raw/ and re-runs extraction with the updated schema — without re-fetching anything from the internet. This is why the raw archive is append-only: the schema can change, the source cannot.

8C.3 Why this matters for the CFPS workshop

In the workshop pipeline, scholar-lit-review-hypothesis (§8A) checks papers.ndjson first, before WebSearch. If you have already ingested Wu & Treiman 2004, Xie & Jin 2015, van Deursen & Helsper 2015, etc., the lit-review skill cites them with full verified bibliographic data instead of generating “[CITATION NEEDED]” placeholders. Same for scholar-citation verify (§16) — local hits are Tier 1, free, and instantaneous.

The right cadence is:

After every paper you finish:
   /scholar-knowledge ingest from output drafts/manuscript-final-...md
   /scholar-knowledge compile

Before every new project:
   /scholar-knowledge ask what do I already know about <topic>?
   /scholar-knowledge export for project <new-slug>

8C.4 Inspect

• raw/ is append-only. Never rm from it. The audit trail depends on it.
• Edges should outnumber concepts by ~10×. If your graph has 400 papers and 12 edges, you’ve ingested papers but not connected them — run relate mode.
• Re-extraction is cheap. New schema field? re-extract is your friend; do not re-ingest from sources.

Stop and check. Run /scholar-knowledge status once a month. If the “Coverage gaps” section names a theory you cite, ingest 5–10 anchor papers for it before your next lit review.

8C.5 The Obsidian wiki — set up, configure, browse

/scholar-knowledge compile produces an Obsidian-compatible vault at ~/.claude/scholar-knowledge/wiki/. Obsidian is free, local-first, and the most ergonomic way to actually read and navigate the graph. This subsection walks through the setup the skill expects.

8C.5.1 What compile writes

~/.claude/scholar-knowledge/wiki/
├── index.md                ← dashboard: stats, recent ingests, quick links
├── knowledge-map.png       ← rendered network graph (if generated)
├── contradictions.md       ← contested findings (papers where edges = contradicts)
├── gaps.md                 ← research gaps and unfilled future-direction lanes
├── papers/                 ← one page per paper
│   ├── fiel-zhang-2017.md
│   ├── li-ouyang-hu-2025.md
│   ├── van-deursen-helsper-2015.md
│   └── …                                       (often hundreds of files)
├── concepts/               ← one page per theory / method / mechanism
│   ├── spatial-assimilation.md
│   ├── layered-digital-divide.md
│   ├── oaxaca-blinder-decomposition.md
│   └── hukou-as-institutional-sorting.md
├── topics/                 ← auto-clustered topic pages
│   ├── digital-inequality-china.md
│   └── residential-segregation.md
└── answers/                ← Q&A archive (grows with each /scholar-knowledge ask)
    └── second-level-digital-divide-mechanisms-2026-05-08.md

A typical paper page (papers/li-ouyang-hu-2025.md) renders as:

# Li, Ouyang & Hu (2025) — Ten-Year Analysis of Digital Divides Among Older Chinese Adults

**Journal:** npj Digital Medicine
**DOI:** 10.1038/s41746-025-02076-1
**Data:** [[CFPS]] 2010–2020

## Findings
- Persistent age-related gap in healthy-aging outcomes attributable to digital exclusion.
- Gap does not narrow across the decade despite access growth.

## Mechanisms
- [[skill-conversion]] — older cohorts' lower marginal returns to use.

## Theories used
- [[layered-digital-divide]]  (role: applies)
- [[cumulative-advantage]]    (role: extends)

## Methods
- [[OLS-with-fixed-effects]]
- [[descriptive-decomposition]]

## Limitations (per authors)
- Cannot separate cohort from age in single panel —
  [[APC-identification]] is non-identified without restriction.

## Future directions (per authors)
- Within-household digital transmission — see [[household-spillover]].

## Edges
- This paper **uses-theory** [[van-deursen-helsper-2015]]
- This paper **extends** [[ren-zhu-2024]]
- This paper is **cited-by** [[zhang-2026-digital-divide-china-cfps]]   (own-work)

---
*Ingested: 2026-04-12 from Zotero. Raw: `raw/pdfs/li-ouyang-hu-2025.pdf`.*

A concept page (concepts/layered-digital-divide.md) renders as:

# Layered (Three-Level) Digital Divide

A theoretical framework distinguishing access (Level 1), skill / use intensity
(Level 2), and conversion of online activity into offline returns (Level 3).

## Anchor papers
- [[dimaggio-hargittai-celeste-shafer-2004]] — original five-dimension formulation
- [[hargittai-2002]] — coined "second-level digital divide"
- [[van-deursen-helsper-2015]] — named the third level
- [[robinson-et-al-2015]] — life-course / gender / race consolidation

## Papers using this framework      (41 in graph)
- [[li-ouyang-hu-2025]]
- [[ren-zhu-2024]]
- [[zhang-2026-digital-divide-china-cfps]]   (own-work)
- …

## Mechanisms
- [[skill-formation]]
- [[content-sorting]]
- [[opportunity-matching]]

## Empirical predictions in this graph
- Access gaps narrow as penetration saturates.
- Use-intensity gaps **persist or widen** under cumulative advantage.
- Returns gaps depend on cultural and economic capital.

## Contradictory evidence (in graph)
- [[zhao-et-al-2022]] — finds narrowing intensity gap among rural Chinese
  students under online learning.

The [[double-bracket]] references are wiki-links — Obsidian renders them as clickable, follows them with Cmd+Click, and exposes them in the backlinks sidebar so each paper page knows which other pages link to it without you maintaining a back-pointer manually.

8C.5.2 Install Obsidian and open the vault

# macOS
$ brew install --cask obsidian

# Linux (AppImage from obsidian.md)
$ # download Obsidian-1.x.AppImage, chmod +x, run

# Windows (WSL participants: install Obsidian on Windows side, point at WSL path)

Open the vault:

1. Launch Obsidian.
2. Click Open folder as vault.

3. Press Cmd+Shift+G (macOS) or Ctrl+L (Linux) and paste:

   ~/.claude/scholar-knowledge/wiki
   

4. Confirm. Obsidian indexes the vault — first time can take 30–60 seconds for a 1,000-paper graph.

A useful convenience symlink:

$ ln -s ~/.claude/scholar-knowledge/wiki ~/Desktop/scholar-wiki

After this you can just open ~/Desktop/scholar-wiki from Finder.

8C.5.3 Recommended Obsidian settings

Files & Links:

• Detect all file extensions → ON
• Default location for new notes → “In the folder specified below” → answers/
• Use [[Wikilinks]] → ON (default)

Editor:

• Readable line length → ON

Core plugins to enable (Settings → Core plugins):

• Graph view (Cmd+G) — visual network of papers ↔ concepts ↔ topics
• Backlinks — for each page, sidebar shows incoming [[…]] references
• Outgoing links — for each page, sidebar shows what it links out to
• Quick switcher (Cmd+O) — jump to any page by typing
• Search (Cmd+Shift+F) — full-text across the vault
• Tags — if you add #topic/segregation style tags

Recommended community plugins (Settings → Community plugins → Browse):

• Dataview — query the wiki as a database. Example:

  TABLE journal, year FROM "papers"
  WHERE contains(theories, "layered-digital-divide") AND year >= 2020
  SORT year DESC
  

  Renders a live table of every post-2020 paper in your graph that uses the layered framework.

• Graph Analysis — centrality, clustering, betweenness over the wiki graph
• Breadcrumbs — navigate paper → concept → topic hierarchies
• Calendar — view papers by ingest date

8C.5.4 Configure Graph View

Open Graph View with Cmd+G. The default view is undifferentiated; configure it like this:

Filters panel:

• Tags — show / hide by tag
• Orphans toggle — flips to show isolated papers (candidates for relate mode)

Groups (color-coded by node type) — click “+ Add group” five times:

Display panel:

• Node size → “By number of links” — highlights well-connected papers (these are usually the anchor citations of a sub-field)
• Arrow → ON — shows direction of [[…]] references
• Line thickness → “By number of connections”

The result: dense red clusters are theories with many supporting papers; dense blue clusters are sub-fields; bridge nodes connecting two clusters are integrative papers worth reading carefully.

8C.5.5 Four browsing patterns

(a) Browse the research landscape.

Open index.md. Click a topic (e.g., [[digital-inequality-china]]). You see the topic page with a list of papers and concepts. Click any paper to see findings, theories, methods. Use the Backlinks sidebar to see what cites or extends it.

(b) Find connections.

Open Graph View (Cmd+G). Type a concept name in the search box (e.g., “hukou-as-institutional-sorting”). It highlights in the graph. Adjacent nodes are the papers using that concept. Identify bridge papers — nodes connecting two otherwise-separate clusters. These are the papers most likely to give you a novel framing.

(c) Ask research questions.

Run /scholar-knowledge ask <question> from Claude Code. The answer is saved to wiki/answers/<question-slug>-<date>.md with full citations to the wiki pages it consulted. Open the answer file in Obsidian — its Backlinks sidebar shows every paper that fed the answer. Over a year your answers/ folder becomes its own searchable Q&A archive.

(d) Track research progress.

• wiki/gaps.md — what your graph says is unstudied (low coverage in STATUS mode)
• wiki/contradictions.md — debated findings (where the graph has contradicts edges)
• wiki/answers/ — the questions you’ve already explored
• Graph View — dense clusters are well-studied, sparse regions are gaps

8C.5.6 Keeping the wiki current

The wiki updates automatically:

• After each ingest — paper pages, concept pages, and index.md are regenerated for just the new entries (incremental).
• Full rebuild — run /scholar-knowledge compile full to regenerate topic clusters, contradictions.md, gaps.md, and the visualization. Use this monthly or after major ingest passes.
• Manual edits — you can edit a wiki page by hand (e.g., add a personal note in the Findings section), and incremental rebuilds preserve the change. A full rebuild may overwrite it, so if you want a permanent personal annotation, put it in a separate notes/ folder you create yourself, not inside the auto-generated pages.

Stop and check. Open Obsidian → Graph View. Filter to your current project’s papers (path:papers/ + tag your current project tag). The cluster you see is the literature you actually have. Anything labeled “Coverage gap” in STATUS mode but visually missing from this cluster — that’s where your next ingest pass should aim.

8D. scholar-causal — pick an identification strategy on purpose

Goal: before you write the design blueprint, decide whether the question is causal and — if so — which of fourteen identification strategies the data actually supports. The skill sits between /scholar-hypothesis and /scholar-design, and is the place where you commit (in writing) to the assumptions you will defend.

The recent update broadens this skill substantially. Earlier versions handled OLS, DiD, RD, IV, FE, matching, and synthetic control. The current build covers fourteen strategies, each with assumptions, diagnostics, R and Stata code, and a journal-ready write-up template:

1. OLS under selection-on-observables (with Oster δ).
2. 2×2 Difference-in-Differences.
3. Sharp and Fuzzy Regression Discontinuity.
4. Instrumental Variables / 2SLS.
5. Panel Fixed Effects (TWFE).
6. Matching / Reweighting — PSM, CEM, IPW, doubly robust.
7. Synthetic Control / SynthDiD.
8. Causal Mediation (ACME) under sequential ignorability.
9. Staggered DiD — Callaway-Sant’Anna, Sun-Abraham, de Chaisemartin-D’Haultfœuille, Borusyak-Jaravel-Spiess (with a runnable CS workflow template at references/did-cs-workflow.R).
10. Double Machine Learning and causal forests for high-dimensional confounding.
11. Bunching estimation at kinks and notches.
12. Shift-share / Bartik instruments for local exposure to aggregate shocks.
13. Distributional and quantile methods — quantile regression, RIF-OLS, changes-in-changes.
14. Factorial DiD (FDID) — for a universal-exposure event (no clean control group) with a pre-event baseline factor G; distinguishes effect modification from causal moderation, with a runnable workflow template at references/fdid-workflow.R.

8D.1 Run

> /scholar-causal effect of agricultural hukou on weekly internet hours,
                  using CFPS 2010-2020 panel; candidate confounders:
                  household income, education, parental occupation,
                  village infrastructure

The skill asks three things up front: (1) the causal question (effect of X on Y), (2) the data structure (cross-section, panel, natural experiment), and (3) candidate confounders and mechanisms. Everything downstream depends on those answers.

8D.2 What the skill produces

A typical run yields four artifacts in the project directory:

design/
  ├─ causal-dag.tex             # dagitty + TikZ DAG, with adjustment sets
  ├─ identification-memo.md     # which strategy, why, what it assumes
  ├─ diagnostic_plan.json       # Tier 1: always emitted — checks to run pre-design
  └─ sensitivity-registry.md    # Oster δ / E-value / HonestDiD / Rosenbaum / Manski
logs/process-log-scholar-causal-<date>.md

The identification memo is the most important file. It names the chosen strategy, walks through the four canonical steps — estimand → identifying assumption → estimator → threats — and lists the forbidden claims that will be enforced later by scholar-write, scholar-verify, and scholar-polish. (Forbidden-claim enforcement is how the CFPS pipeline catches an Abstract that says “reduces” when the design only licenses “is associated with.”)

8D.3 The method-selection decision tree

The skill ships with a single decision table the agent walks through with you. The collapsed form:

8D.4 The sensitivity-analysis suite

Picking a strategy is half the work. The skill also writes a sensitivity registry that pre-commits you to robustness checks before you see results:

• Oster (2019) δ — for OLS with selection-on-observables.
• E-values (VanderWeele & Ding 2017) — minimum unmeasured-confounder strength to nullify the effect.
• Rosenbaum bounds — sensitivity to hidden bias for matched estimators.
• HonestDiD (Rambachan & Roth 2023) — bounded violation of parallel trends.
• Manski bounds — partial identification with weaker assumptions.
• Placebo / falsification tests — pre-treatment outcomes, never-treated leads, in-time placebos.
• Spillover sensitivity — SUTVA violations under contagion or interference.
• Specification curve / multiverse — every plausible specification, ranked.

8D.5 Tier 1 vs. Tier 2 — what runs on your data

The skill has two execution tiers. Tier 1 always emits diagnostic_plan.json — a machine-readable list of checks to run before the design is locked. Tier 2 is opt-in and executes a small set of pre-design diagnostics directly:

• Panel-data preview via panelview + fect — to inspect treatment timing and pre-trends.
• Synthetic-control preview via gsynth (Xu 2017) — feasibility of synth/SynthDiD for your case.
• Interaction-effect diagnostic via interflex (Hainmueller, Mummolo, Xu 2019) — whether your moderator looks linear at all.
• Factorial-DiD preview via fdid (Xu, Zhao & Ding 2026) — for crossed-treatment / factorial-DiD designs.

Tier 2 is gated: you have to explicitly say “run diagnostics on this dataset” in the prompt. Tier 2 does not estimate the focal effect, fit a final model, or produce numbers that will appear in the paper. It produces diagnostic plots that inform the choice you commit to in §9 (scholar-design).

8D.6 Why the CFPS workshop routes around scholar-causal

The digital-divide example in this handbook is deliberately not a causal design. Hukou is assigned at birth and rarely changes; there is no manipulable “treatment.” We have neither an instrument nor a discontinuity. The right move — the one the workshop demonstrates — is to decline a causal identification strategy and write a descriptive-decomposition design instead. scholar-causal is still useful in that case: it produces the DAG that justifies your covariate adjustment, and it stamps the identification memo with causal_status: descriptive so that downstream skills enforce the right language ceiling.

For projects where you do have causal leverage — a CCT-style RCT, a policy shock, a regression discontinuity, a credible IV — start the project with scholar-causal, then run scholar-design. The decision is which strategy; the discipline is committing to its assumptions in writing before the analysis runs.

8D.7 Inspect

Before moving to §9, open the three artifacts and ask:

• causal-dag.tex — Is the adjustment set sufficient? Are there back-door paths the DAG missed?
• identification-memo.md — Could a hostile reviewer attack each of the named assumptions? Is one of them empirically testable?
• sensitivity-registry.md — If the focal effect survives Oster δ > 1 and an E-value above the strongest control, the headline claim is defensible.

Stop and check. If the identification memo lists causal_status: descriptive, read §9.3’s “Forbidden claims” block before you start drafting — the language ceiling is now binding.

8E. scholar-lit-review and scholar-hypothesis — when you want them separately

§8A showed the integrated skill. Both halves also exist on their own, and there are good reasons to reach for them individually: a literature landscape you are not yet ready to turn into hypotheses, or hypotheses derived from a literature you already know.

8E.1 scholar-lit-review — three depths

argument-hint: "[topic or research question] [optional: landscape|targeted|rapid]
                [optional: target journal] [optional: population, time period,
                geographic scope]"

> /scholar-lit-review "digital divide in China" landscape "Social Forces" 2010-2025
> /scholar-lit-review "remote work and the gender wage gap" rapid

The waves are cumulative: Wave 1 core topic · Wave 2 mechanisms and theories · Wave 3 methods and data (targeted and full) · Wave 4 recent frontier (full only) · Wave 5 contested terrain and null findings (full only).

Three features distinguish it from “search and summarize”:

• The Annual Reviews checkpoint always runs. The skill searches site:annualreviews.org, prioritizes the Annual Review of Sociology, and extracts at least five cited papers from any relevant review. One good review article is worth twenty search results.
• Citation-chain expansion (required in full mode): backward from the reference lists of three to five key papers, then forward via “cited by” for the top foundational works.
• Wave 3 hunts for named critics. Before running methods searches, the skill loads a method-critics reference and searches for each planned method’s principal critic by name — Bell & Jones for age-period-cohort, Goodman-Bacon for staggered DiD. Finding the objection to your method before you commit to it is much cheaper than finding it in review.

The output is a landscape map along eight dimensions: field-evolution timeline · theoretical landscape (framework, core claim, proponents, predictions, support, status) · established findings · contested findings with a weight-of-evidence table · null and absent findings, kept distinct from each other · mechanism inventory (proposed vs. actually tested) · methodological landscape · ranked gap analysis. Full mode also emits a PRISMA flow diagram.

The ninth dimension is a theory handoff table — gap → theoretical implication → candidate framework → why the rivals are insufficient — plus a paste-ready paragraph for /scholar-hypothesis.

Two hard behaviours: the skill hard-stops if no local reference library is detected rather than quietly falling through to web-only search; and it writes the search log to disk before the first query and appends after every query, because context compaction silently destroys in-memory hit counts.

The full-text tier (v5.27). Phase 1 searches your library before it searches the web, and it does so in order: knowledge graph (pre-extracted findings) → scholar-rag → Zotero (bibliographic metadata) → web. The middle tier is new. When /scholar-rag status reports embedded > 0, the skill queries your index for full-text passages out of your own PDFs — rag_search("<topic>", k=8, hybrid=true) if the MCP server is registered (§8F.4), otherwise the query.py CLI. What comes back is cited paragraphs with page numbers, which is a different kind of evidence from either neighbour: the graph gives you findings, Zotero gives you metadata, this gives you the sentences. Retrieved passages are leads to verify, never citations in themselves; every reference still passes Tier 0–2 verification.

There is also a theory gate: if your prompt mentions hypotheses or theory sections, the skill stops and redirects you to /scholar-lit-review-hypothesis (§8A) rather than producing half of what you need.

8E.2 scholar-hypothesis — formalizing predictions

argument-hint: "[phenomenon or RQ] — optionally: [design type: quant/qual/comp/
                computational] [journal: ASR/AJS/Demography/NHB/NCS/SciAdv]
                [theory hint]"

> /scholar-hypothesis "why cumulative disadvantage widens the wealth gap" quant ASR
> /scholar-hypothesis "language shift among heritage speakers" qualitative \
                      "Language in Society" Fishman

The eight steps: frame the puzzle (as an anomaly, contradiction, extension, mechanism, or scope condition) → select frameworks (one primary, at most one secondary) → determine hypothesis placement mode → specify the mechanism chain → derive and formalize → map competing predictions → build a text DAG → write the theory section.

Placement mode is dictated by the journal, not by preference:

Getting this wrong fails the skill’s own pre-save check.

The derivation chain table is the core mechanism. Every hypothesis must fill every column:

| H# | Literature gap | Gap type | Framework prediction | Mechanism-chain link | Hypothesis | |—|—|—|—|—|—|

If you cannot fill every column, the hypothesis is dropped. The named failure mode is a hypothesis that matches the framework’s general prediction without pointing at a specific step in the mechanism — which reads like theory but tests nothing in particular.

Mechanisms are specified through Coleman’s boat (situational → action-formation → transformational) or Hedström’s DBO (desires, beliefs, opportunities), classified by Elster’s types (cognitive, motivational, interactional, institutional, material), and bounded by a mandatory scope-condition matrix.

Seven hypothesis forms are supported: main effect · moderation (fan-spread vs. crossover) · mediation · curvilinear or threshold · comparative/group-level · boundary condition · null-as-finding. Intersectional hypotheses have their own required form: stated multiplicatively as an interaction term to be tested, not as two separate main-effect hypotheses.

Every hypothesis also gets a competing prediction: what a rival theory predicts, what the data would look like if the rival is right, and the specific test that distinguishes them. Plus an alternative-explanations checklist — selection, reverse causation, omitted variables, measurement artifact, compositional difference — each requiring a sentence of the form “We address [alternative] by [design feature].”

Causal-language calibration is enforced here as everywhere: observational data without an identification strategy gets “is positively associated with” and “predicts,” never “causes” or “the effect of.”

Theory-section word budgets: ASR/AJS 1,000–1,500 · Demography 600–1,000 · NHB/Science Advances 300–600 (embedded in the introduction) · NCS 200–400.

The skill ships a reference library of 25+ frameworks — stratification, networks and capital, culture, assimilation, life course, Coleman’s boat, DBO, racial formation, status characteristics, social movements, signaling, rational choice, contact hypothesis, labeling, intersectionality, neo-institutional theory, organizational ecology, practice theory, feminist standpoint, labor process, actor-network theory, and non-Western traditions including coloniality, world-systems, postcolonial theory, Ubuntu, and Confucian/guanxi frameworks — each with its core claim, mechanisms, best-use cases, key papers, and ready sentence starters.

Stop and check. Take one hypothesis from your own work and fill in the derivation chain table for it. If the “mechanism-chain link” column is the hard one, that is diagnostic: you have a prediction, not yet a theory.

8F. scholar-rag — a local vector database over your own library

Goal: turn every PDF you own into searchable, cited passages — and hand that search to Claude Code and Codex as a tool, so a lit-review session can quote your library instead of paraphrasing its memory of it.

argument-hint: "[setup|ingest|query|mcp|graph|status] [args], e.g. 'ingest' or
                'query how does segregation affect mobility' or 'graph run'"

This is the newest skill in the suite (v5.27, July 2026) and the one that changes the texture of literature work most directly. §8C.0 laid out three ways to get the right text into the model’s window — RAG, agentic search, and the knowledge wiki — and argued they are complementary. scholar-rag is the first of the three, built properly:

They share paper identity (doc_id = sha256 of the normalized DOI or title), so a passage hit cross-links to the same paper’s extracted findings, and the GraphRAG layer seeds its entity graph from the knowledge graph rather than starting cold.

Everything is local. bge-m3 for embeddings, ollama for the GraphRAG LLM, LanceDB for vectors, a stdio MCP server for the interface. The only network traffic is the optional open-access PDF fetch. This matters more than it sounds: the alternative — uploading your whole Zotero library to a hosted vector service — is a data transfer you would have to disclose, and for anything under embargo or IRB restriction, one you could not make.

It is self-contained. The engine provisions its own CPython 3.12 venv via uv, reads Zotero directly, and bundles its own logging. It has no hard dependency on the rest of the plugin, and degrades gracefully when scholar-knowledge is absent.

8F.1 The nine modes

full runs 0 → 1 → 3. GraphRAG (mode 4) is deliberately not in full, because it is the long, LLM-bound stage — hours of local inference over a real library.

8F.2 Build it

# one-time
> /scholar-rag setup

# the whole Zotero library, auto-detected; --limit to trial a subset first
> /scholar-rag ingest

Under the hood that is run-ingest.sh, and it is worth knowing you can drive it directly for the long runs:

$ bash "$RAG_ASSETS/run-ingest.sh" --batch 64                  # foreground, watch it
$ bash "$RAG_ASSETS/run-ingest.sh" --batch 64 --background     # detach; tail the log
$ bash "$RAG_ASSETS/run-ingest.sh" --source folder --folder ~/pdfs
$ bash "$RAG_ASSETS/run-ingest.sh" --ocr                       # scanned PDFs, via llama3.2-vision

Three stages, and every document carries a status through them — new → extracted → embedded, or no_pdf / failed:

Zotero/PDFs ──ingest──▶ documents(new)
   PDF ──extract (PyMuPDF → pdftotext → vision-OCR)──▶ raw/text + documents(extracted)
   text ──chunk (section-aware, ~500 tok, overlap) + bge-m3──▶ LanceDB + documents(embedded)

Each stage processes only rows not yet advanced, so a killed run continues where it stopped — which you will need, because a full library is embedding-bound: thousands of PDFs is hours even on Apple-silicon MPS. Run it detached.

The extraction ladder is worth understanding, because it determines quality: PyMuPDF first (fast, keeps page mapping), pdftotext as fallback, and vision-OCR last for scanned documents. Extracted text is cached page-mapped in raw/text/<doc_id>.json, which is what makes re-chunking or re-embedding with a different model cheap — you do not re-extract.

8F.3 Query it

> /scholar-rag query how does residential segregation affect intergenerational mobility?

# or directly, with filters and reranking:
$ rag_py query.py "identification strategy" -k 6 \
         --section methods,results --year-min 2010 --rerank --json

Every hit comes back with an author-year citation, section, page range, DOI, and similarity score. That page number is the point: it is what lets you verify a claim in ten seconds instead of re-reading a paper, and it is what scholar-citation uses to check a claim against its source (§16.5).

8F.4 Hand it to the agent — the MCP server

> /scholar-rag mcp

$ bash "$RAG_ASSETS/mcp-setup.sh"              # register with every detected host
$ bash "$RAG_ASSETS/mcp-setup.sh" --print-only # just print the .mcp.json / config.toml snippets

This registers a stdio MCP server (§3.6) exposing four tools:

Restart the session to pick the tools up.

8F.4.1 The three skills it is wired into

This is the part that changes your workflow without you doing anything. Once an index exists, three skills reach for it on their own — you do not invoke scholar-rag during a lit review, you just have a better lit review. Each checks /scholar-rag status first and degrades silently to its old behaviour if there is no index.

What this does not do. rag_search surfaces text; it does not mint citations. Every reference still passes through the Verified Citation Pool and /scholar-citation (§16). Treat a retrieved passage as a lead to verify, not as a source you have confirmed — the index can only be as honest as the PDF it chunked, and a passage torn from its section can still be misread. The division of labour is worth stating once and remembering: scholar-rag owns the text, /scholar-citation owns the bibliographic record.

8F.5 GraphRAG — the long pole

Vector search finds passages near a query. It cannot answer “what are the major theoretical camps in this literature?”, because no single chunk contains that answer. GraphRAG builds the structure that can:

$ rag_py graphrag.py seed        # import scholar-knowledge concepts + citation edges (fast, no LLM)
$ rag_py graphrag.py extract     # LLM entity/relation extraction per paper — the long stage, resumable
$ rag_py graphrag.py build       # dedup entities → Leiden communities
$ rag_py graphrag.py summarize   # LLM community summaries (the global-search corpus)
$ rag_py graphrag.py run --limit 50                                     # the whole chain, bounded

run is the SHORT chain, and that is a trap. It executes exactly seed → extract → build → summarize. It does not run citations, keywords, or semantic — the three stages that must land before build, because build is what dedups entities and computes the Leiden communities. Run build early and those communities are computed on a graph with no bibliographic edges, no keyword nodes, and no entity merges; fixing it afterwards means re-running build and summarize, which is the expensive LLM stage. Use the order in §8F.6.

$ rag_py graphrag.py local  "mechanisms linking neighborhood to health" # entity-grounded passages
$ rag_py graphrag.py global "what are the major theoretical camps here?" # map-reduce over communities
$ rag_py graphrag.py neighbors <doc_id>

Model selection is the thing that will bite you. Extraction defaults to deepseek-r1:32b, which runs and honors format=json but is a reasoning model — slow for bulk work. gpt-oss:20b is the faster ideal, but fails with a tensor "blk.0.ffn_down_exps.weight" size overflow on older ollama builds; brew upgrade ollama, restart the server, then export RAG_GRAPH_MODEL=gpt-oss:20b. If that is unavailable, a fast instruct model is the practical answer: ollama pull qwen2.5:7b-instruct. Extraction is section-bounded (12k chars by default) and resumable per document, so run it detached and let it cross sessions.

8F.6 The three stages that make the graph worth having

Entity co-mention answers “which papers use the same words.” These three answer “which papers actually build on each other,” “what does the field already call this,” and “which papers are plainly about the same thing.” All three were added after the first version of this handbook and none of them is in graph run.

$ rag_py citations.py fetch      # one OpenAlex call per DOI — resumable, cached
$ rag_py citations.py build      # direct cites + coupling + co-citation → paper communities
$ rag_py keywords.py load        # Zotero tags + OpenAlex topics + the in-text Keywords line
$ rag_py semantic.py entities    # link entity synonyms the normalizer cannot merge
$ rag_py semantic.py docs        # paper↔paper kNN — reaches papers with no DOI at all
$ rag_py semantic.py duplicates  # the same work ingested twice

Why each earns its runtime:

• citations — seed alone covered about 12% of a 5.5k-paper corpus. Coupling (A and B cite the same work) reaches far more pairs than direct citation, and stays useful for recent papers that nothing cites yet.
• keywords — inherently multi-document: one tag covers dozens of papers, which is exactly what an entity graph built per-paper is short of. And no hallucination risk.
• semantic — a paper with no DOI never enters the OpenAlex cache, so it is invisible to the whole bibliographic layer. Adding semantic edges lifted paper-graph coverage from 72% to 95% (3,923 → 5,189 papers) on that same corpus. It also merges residential segregation / neighborhood segregation / spatial segregation, which normalize to three distinct keys and are one concept.

The order is not arbitrary — later stages consume earlier ones, keywords need the OpenAlex cache, and every graph stage must precede build:

setup → ingest → mcp → citations fetch → citations build
      → graph seed → graph extract → keywords load → semantic entities
      → graph build → graph summarize

Thresholds are not interchangeable between docs and entities. Document similarity sits far higher than phrase similarity: the median top-10 paper neighbour scored 0.886, so a 0.55 floor keeps essentially everything (10 edges/paper, including a historical-sociology monograph next to an LLM benchmark paper). The 0.90 default gives 3.5 edges/paper. Check the distribution before trusting a cutoff.

8F.7 Where it lives

~/.claude/scholar-rag/                      (override with $SCHOLAR_RAG_DIR)
├── corpus.sqlite       ← documents + chunks manifest (the source of truth for status)
├── raw/text/<doc_id>.json   ← page-mapped extracted text (cache; enables re-chunk)
├── raw/meta/<doc_id>.json   ← full bibliographic record
├── index/              ← LanceDB table `chunks` (vector + metadata + BM25 FTS)
├── graph/              ← entities, relations, doc_edges, communities, summaries
├── manifest.json       ← embed model + dim + chunk params + build stats
├── logs/               ← trace-scholar-rag.ndjson, ingest-run-*.log
└── .venv/              ← self-contained CPython 3.12

It is user-scoped, not project-scoped — the same store serves every project, exactly like scholar-knowledge. That is the right call for a reference library, which is a property of the scholar rather than the paper.

The feedback loop back to §8C. Extraction is the expensive part of both skills, and now only one of them pays it. Once a build finishes, run /scholar-knowledge re-extract: nodes that were ingested from an abstract alone can be upgraded from the full text scholar-rag already extracted. A library you index once makes the wiki deeper for free.

Configuration, all via .env or environment: SCHOLAR_RAG_DIR · SCHOLAR_ZOTERO_DIR (auto-detected) · EMBED_MODEL (default BAAI/bge-m3) · RAG_CHUNK_CHARS / RAG_CHUNK_OVERLAP · RAG_GRAPH_MODEL / RAG_SUMMARY_MODEL · RAG_OCR_MODEL · OLLAMA_HOST.

8F.8 Inspect

$ rag_py ingest.py status      # documents by stage, chunk counts, no_pdf coverage
$ rag_py graphrag.py status    # entities / relations / communities / summaries

Four checks before you trust it:

1. setup-venv.sh reported every import ok, and told you whether torch has MPS. (No MPS means a much slower build — plan accordingly.)
2. ingest.py status shows embedded > 0 and a sane no_pdf count. A large no_pdf means Zotero items whose attachment never synced locally; fix that in Zotero, or let the open-access fetch fill them.
3. A query on a topic you know returns the paper you expect, with the right author-year and a page number you can check.
4. The MCP handshake lists all four tools. If it lists none, you did not restart the session.

Data safety. The corpus is published papers, so it is normally CLEARED. But folder mode will happily ingest a directory of unpublished drafts or a colleague’s shared PDFs. If a project sidecar marks any input NEEDS_REVIEW or HALTED, route through /scholar-safety or /scholar-init first (§6) — the fact that embedding is local does not make ingestion consent-free.

9. scholar-design — design before data

Goal: lock the estimand, the model ladder, the sample restrictions, and the forbidden language. After this skill, the analysis script is essentially a template-fill.

This is the largest skill in the suite (roughly 16,000 words of instructions) and the one that most repays reading its dispatch table before you type.

argument-hint: "[quant|qual|mixed|experiment|power|methods-section|pap|
                computational|NLP|ML|network|ABM|premortem|blueprint]
                [research question] [optional: data source, design type,
                journal target]"

9.0 Sixteen design modes

> /scholar-design quant "did hukou/cohort gaps in internet access narrow while
                  use-hours gaps persisted?" CFPS 2010-2020 "Social Forces"
                  descriptive/decomposition
> /scholar-design power "MDES for a 2,000-respondent survey experiment"
> /scholar-design computational NLP "polarization in news coverage with BERT"
                  "Science Advances"
> /scholar-design premortem digital-divide-china-cfps
> /scholar-design blueprint digital-divide-china-cfps

9.1 The twelve steps

Step 0 — Setup. Derives the project root, opens the RAO trace, confirms RQ, data constraints, and target journal with you.

Step 1 — Design selection decision tree. A fourteen-row table mapping (goal × data structure × assignment) to a recommended design and journal fit. Any DiD / FE / RD / IV / matching / mediation / natural-experiment claim triggers the causal gate, which hands off to /scholar-causal (§8D) and comes back with an identification strategy.

Step 1.5 — Multi-comparison policy declaration. Mandatory whenever a pre-registered hypothesis family carries K ≥ 3 tests. It emits a YAML block naming the family, K, the correction method, alpha, and the decision rule — and it makes peer-reviewer-demographics a required member of every later review panel.

Why this step exists. A real run in this corpus (cohab-fertility-cfps) shipped “PARTIAL support” for a nine-test family with no correction applied. Declaring the correction at design time — before you have seen a single p-value — is the only version of this that is not p-hacking.

Step 1.6 — Data-source requirements. Emits a ## Data-Source Requirements YAML block (unit_of_analysis, geographic_scope, time_window, design_structure, required_n, required_constructs[], excluded_designs[]) that scholar-data (§9A) consumes to score candidate datasets.

Step 2 — Experimental design module. Seven sub-modules, each with a design template, R analysis code, an assumptions checklist, and a write-up template: 2a RCT · 2b survey/vignette · 2c list experiment · 2d cluster RCT · 2e audit/correspondence · 2f stepped-wedge · 2g SMART.

Step 3 — Power analysis. Eleven sub-modules:

For secondary data your N is fixed, so 3c is the honest step: you are not choosing a sample size, you are reporting the smallest effect your fixed sample could have detected.

Step 4 — Variable specification. The variable dictionary table (Role · Name · Construct · Operationalization · Source · Type · Range · Notes), a measurement-validity checklist, and a DAG sketch.

Step 5 — Analytic strategy. Model selection by outcome type; SE and clustering choices; the presentation sequence (Model 1→4 plus appendix robustness). Note the sociology-journal rule the skill enforces: always report average marginal effects, not odds ratios or raw log-odds, for any binary, ordinal, or GLMM outcome in ASR/AJS-style venues.

Step 6 — Robustness plan. A pre-committed sensitivity registry. Each entry becomes blocking at analysis time unless marked optional: true with a rationale. A limitations-section bullet does not satisfy this gate — only a spec_id that later shows up in the spec registry does.

Step 7 — Pre-analysis plan. Ten sections — RQ and hypotheses, design, primary outcome, covariates, primary analysis, subgroup/heterogeneity, robustness, multiple-comparisons correction, deviations policy, sample size — plus an OSF registration checklist.

Step 8 — Write the Data and Methods section, calibrated to the target journal’s word budget and structure.

Step 9 — Computational methods design. Claim-type taxonomy (measurement / description / prediction / causal); corpus and sampling design with minimum-N-by-method tables; annotation design with a codebook template and inter-rater-reliability targets (κ ≥ 0.70 minimum, ≥ 0.80 preferred, plus Krippendorff’s α and ICC); train/test/validation splits with the no-peek rule; pre-specified evaluation metrics; network-boundary specification and ERGM/SAOM data requirements; ABM design under the ODD protocol with SALib Sobol/Morris sensitivity analysis.

Step 10 — Bayesian design. Prior elicitation, brms fitting, convergence diagnostics, Bayesian sample size and assurance, reporting template.

9.2 What appears in design/

From the real CFPS run — note that some of these are written by scholar-design and some by the orchestrator’s later phases, which is why the folder accumulates:

design/
├── design-blueprint-digital-divide-china-cfps-2026-05-04.md  ← scholar-design
├── data-blueprint-digital-divide-china-cfps-2026-05-04.md    ← scholar-data
├── pre-mortem-quant-2026-05-04.md                            ← Step 11 panel
├── pre-mortem-demographics-2026-05-04.md
├── pre-mortem-senior-2026-05-04.md
├── limitations-accepted.md         ← RED dimensions you accepted, with reasons
├── variable-dictionary.csv
├── model-specs.json
├── coef-map.csv
├── test-inventory.json
├── project-brief.md
└── results-lock-2026-05-04.md      ← written later, at the results-lock phase

9.3 The estimand and model ladder (from the real blueprint)

## 0. Headline finding (locked at Phase 3.5)

This design commits to Y2 (weekly hours of internet use among users) as the
focal outcome for the headline table and abstract sentence.

> Net of education, income, occupation, household composition, and
> province × wave fixed effects, the rural-hukou penalty on weekly internet
> hours among Chinese adults who use the internet (Y2) in 2018 is
> statistically indistinguishable from the penalty in 2014 — Y2 being
> measured only in CFPS waves 2014, 2016, and 2018 — even as the binary
> access gap (Y1, observed across CFPS 2010–2020) closed from approximately
> 40 to 15 percentage points between 2010 and 2020 […].

## 1.1 Estimation strategies in correspondence with hypotheses

| H  | Estimator                       | Identifying assumption                |
|----|---------------------------------|---------------------------------------|
| H1 | Logit (Y1) + OLS with province×    | Conditional indep. of hukou and       |
|    | wave FE on Y2|Y1=1                 | unmeasured infra within province×wave |
|    | (Tobit MLE cross-check in          | (cross-check adds censoring + tail-   |
|    | robustness section)                | distribution assumptions)             |
| H2 | Person FE within-changes;       | HAPC: cohort & period exchangeable    |
|    | HAPC; Deaton-Paxson bounds      | given age                             |
| H3 | Three-way interaction;          | Common support; linearity within      |
|    | threefold Oaxaca-Blinder        | group                                 |
| H4 | Person FE on co-residence       | No third unmeasured time-varying      |
|    | changers                        | confounder                            |

## 1.3 What we explicitly do NOT claim
- No causal interpretation of hukou
- No causal interpretation of cohort
- No third-level (returns) claim in this paper

One line in this blueprint is load-bearing and easy to skip past:

outcome_mechanism_alignment: prevalence-stock

The permitted values are entry-process, prevalence-stock, dissolution, and multi-state. If this line is missing, design verification fails. It exists because an April 2026 audit found a design applying an entry-process mechanism story to a prevalence-stock outcome — a silent mismatch that produces a coherent-sounding paper answering a question the data cannot address.

9.4 Step 11 — the pre-mortem panel

scholar-design dispatches a peer-reviewer panel before any data is touched. The roster is chosen by design type:

Each reviewer scores thirteen dimensions RED / YELLOW / GREEN with a justification: RQ clarity · theory↔hypothesis linkage · operationalization validity · identification strategy · sample adequacy · internal validity · external validity · ethics · measurement and missingness · analytic-plan specificity · feasibility · journal fit · multi-comparison policy. Each memo closes with OVERALL:, TOP-3 FATAL CONCERNS:, and RECOMMENDED ACTIONS:.

The panel is mandatory to dispatch but advisory in adjudication: you accept or revise each RED dimension, up to three iterations, and design-review-check.sh blocks the next phase on any un-accepted RED. Exit codes: 0 GREEN proceed, 1 RED un-accepted → halt, 2 YELLOW → may proceed with approval. After three iterations it hard-halts, on the theory that persistent RED is a structural design problem needing human judgment, not more auto-critique.

The provenance requirement — this is the one to internalize. Every pre-mortem memo must carry a Reviewer Provenance table with real columns: reviewer_agent | task_invocation_id | dispatched_at | model. Placeholders like TBD or — fail the gate, and design-review-check.sh cross-checks the process log for zero peer-reviewer-* dispatches. The skill names inline-roleplayed reviewers — the model writing a “review” in its own voice instead of dispatching a real subagent — as the #1 silent failure of the whole pipeline. A post-mortem traced roughly 71% of manuscript defects to skipped or simulated review. §13’s surrogate disclosure is this same failure mode, caught and declared.

In our actual run, the senior reviewer flagged: “Y1 (binary access) is the wrong headline outcome. Y2 (use intensity) is the theoretically distinctive contribution and should be the abstract-target sentence.” That single comment changed the focal outcome before any analysis ran, saving an entire revision cycle.

9.5 Step 12 — the section blueprint

Run late — after the results lock, before drafting — and notable because it is deterministic: generate-section-blueprint.sh reads the results lock, the design blueprint, and the hypotheses, and emits the contract with no LLM in the loop. The drafting skill cannot negotiate with it.

> /scholar-design blueprint digital-divide-china-cfps

Writes drafts/section-blueprint.json (canonical, schema v5) plus a human-readable .md companion whose footer says, accurately, “Hand-edits will be overwritten.”

Per section — abstract, introduction, theory, methods, results, discussion — the contract carries target_words_min/max, required_hypotheses[], required_tokens[], reader_outcomes[], exemplar_paths[], derived_moves, structural_moves[], and forbidden_patterns[]. Those fields sit in a precedence ladder that scholar-write must obey:

Exit codes: 0 GREEN (JSON and MD written), 1 RED (missing results-locked/LATEST.txt, manifest, or design blueprint). Downstream, blueprint-completeness-check.sh re-validates the schema before drafting may start.

9.6 Inspect

• limitations-accepted.md — every RED you accepted, in the form [RED-N: dimension] rationale. If this file is empty and the panel raised REDs, something was waved through.
• model-specs.json — the focal outcome, focal table, focal sample.
• The pre-mortem memos — read the TOP-3 FATAL CONCERNS of each, and check the provenance table has real invocation IDs.
• The outcome_mechanism_alignment line — does the mechanism story match the outcome type?

Stop and check. Name the focal outcome, the focal table, and the focal sample without looking. Then name one thing the design says you may not claim. If you cannot do both, do not proceed.

9A. scholar-data — find, fetch, and govern the data

Goal: locate a dataset that actually fits the design, download it where possible, and produce the variable dictionary, IRB materials, and management plan the rest of the pipeline assumes exist.

This skill is invisible in the CFPS walkthrough because we arrived with data in hand. For most participants starting a new project it is the single most useful skill in the suite: it ships a directory of 100+ datasets across 14 categories, of which 57 are machine-scored and 42 can be downloaded automatically.

argument-hint: "[dataset|survey|interview|irb|manage|vignette|scrape|web|api|
                social media] [topic or research question]
                [optional: population, journal, design]"

9A.1 Eight workflows

> /scholar-data dataset "childhood poverty and adult health" US NHB
> /scholar-data survey "hiring discrimination by race and record" vignette
> /scholar-data irb "web scraping public tweets on immigration policy"
> /scholar-data manage "codebook and DMP for an NSF proposal"

9A.2 The dataset directory

Fourteen categories, each a table of datasets with coverage, unit, N, key variables, and access tier:

1. Sociology / stratification / labor — GSS, PSID, NLSY79/97, Add Health, SIPP, ACS, CPS
2. Demography / family / health — HRS, NHANES, NHIS, NCHS Vital Statistics, CDC PLACES, UN World Population Prospects
3. Education — NELS/ELS/HSLS, NAEP, College Scorecard, IPEDS
4. Political behavior — ANES, CCES, Pew datasets
5. Immigration / ethnicity / language — CPS-ASEC, New Immigrant Survey, ISSP, WVS/EVS, Luxembourg Income Study
6. Neighborhoods / spatial / administrative — Census tract, HMDA, TIGER/Line, HOLC redlining maps, Opportunity Atlas
7. Text / digital / computational — Congressional Record, Common Crawl, Google Trends, Twitter/X historical
8. Crime and criminal justice — NCVS, UCR/NIBRS, NSDUH, NCRP, Sentencing Commission
9. International surveys — WVS/EVS, ISSP, ESS, Eurobarometer, Afrobarometer, Latinobarómetro, Asian Barometer, LIS/LWS, PISA, TIMSS/PIRLS, DHS, MICS
10. Economic / labor / macro — FRED, Penn World Table, EU-KLEMS, LEHD, OECD, Eurostat, ILO
11. Global health / environment — WHO GHO, Global Burden of Disease, IPUMS International, NASA SEDAC, FAOSTAT
12. Science of science — OpenAlex, Semantic Scholar, Dimensions, ORCID, NSF SED, Crossref, Web of Science
13. General repositories — Harvard Dataverse, ICPSR, Zenodo, OSF, Figshare, QDR, Roper iPoll, Data.gov, UK Data Service, GESIS, Google Dataset Search, Kaggle
14. Restricted federal / linked — SSA earnings via FSRDC, IRS/Treasury linked microdata, state administrative records, CMS claims

Plus an international/longitudinal supplement: UKHLS, German SOEP, IHDS, CFPS, EVS, UK Biobank, Fragile Families.

9A.3 The dataset scorer — how a recommendation is actually made

Step 0c.5 runs a deterministic Python scorer, not a vibe:

$ python3 scripts/gates/dataset-suggester.py "$PROJ" --top 3 --auto

It reads design/data-requirements.yml (the YAML scholar-design Step 1.6 emitted), falls back to the blueprint and then to project-state.md, and scores every entry in references/datasets-index.json — 57 datasets with fields unit_of_analysis, geographic_scope, time_window, design_structure, key_constructs[], access_tier, auto_fetch{}.

The decision rule: ≥ 6.0 auto-select · < 6.0 needs user confirmation · zero candidates passing the hard filters exits 3, at which point the orchestrator must ask you to relax a constraint or add a dataset to the directory. There is also an existing-data audit mode: if you brought your own dataset and something in the directory outscores it, you get a YELLOW flag telling you so.

9A.4 Auto-fetch

Step 0d runs real downloads for anything in the “Immediate” access tier — 18 datasets via an R package, 24 via direct URL. Sources that need no key at all, and are therefore the fastest path to a working project: World Bank, NHANES, CDC PLACES, GSS, Google Trends, BLS v1, College Scorecard, Opportunity Atlas, GDELT, OpenAlex, Eurostat, WHO GHO, Penn World Table, FAOSTAT, Harvard Dataverse, Zenodo, Semantic Scholar, Crossref, Data.gov.

Keys and registrations you may need:

Store them in .Renviron or .env, both gitignored. Never in a script.

On a successful fetch the skill writes data/raw/download-manifest.md (File · Source · Date fetched · N rows · Variables) and flips PROJECT STATE from data-status: no-data to existing-data, which unlocks data-available mode downstream. If an API key is missing, the skill is required to ask you for it rather than silently degrading to a code template.

9A.5 Workflow 7 — the web-data rules that matter

The legal and ethical framework comes before any code: robots.txt, terms of service, rate limits, CFAA, GDPR, IRB. The web-data IRB decision table maps public tweets → Exempt, Reddit → Exempt/Expedited, private groups → Full board. The governing principle is AoIR 2019, quoted in the skill: legal accessibility ≠ ethical appropriateness.

Platform realities the skill documents, current as of this build:

• Twitter/X — the Academic Research track was discontinued in January 2025. Full-archive search now needs Pro (~$5K/month) or Enterprise; the free Basic tier caps at 10,000 tweet reads per month. For new projects, consider Bluesky (AT Protocol, free firehose) or the Meta Content Library.
• Reddit — Pushshift archive access was restricted in 2023; use PRAW against the live API.
• Never share raw tweet text. Share tweet IDs only.

The API-first order is: platform API → GDELT / MediaCloud / Internet Archive → rvest + polite (R) or requests + BeautifulSoup (Python) → chromote / playwright for JavaScript pages. Everything gets logged to docs/scraping-log.md with robots.txt status, ToS review, IRB determination, rate limiting, and record counts.

9A.6 Files written

output/<slug>/data/scholar-data-<topic>-<date>.md   ← the data plan
<proj>/data/dataset-selection.json                  ← scorer output + fetch params
data/raw/download-manifest.md                       ← what was fetched, when
data/raw/<source>-<params>.{rds,csv,parquet}        ← the actual data
data/codebooks/                                     ← var_name | var_label | type |
                                                       values | missing_codes | source
docs/scraping-log.md · docs/data_cleaning_log.md
.gitignore                                          ← raw data, credentials excluded

The directory scaffold sets data/raw/ read-only (chmod -w). Raw data is an input, never an output.

9A.7 Gotchas

• scholar-data is a Tier B skill: it checks the safety sidecar but does not implement the full LOCAL_MODE dispatch contract. A LOCAL_MODE file must be routed to /scholar-analyze or /scholar-eda instead.
• List experiments are statistically inefficient — plan N ≥ 500 per arm.
• Conjoint designs need roughly N ≥ 500 × 5 tasks to detect an AMCE of 0.05.
• Probabilistic record linkage (fastLink) must report match rates and characterize matched vs. unmatched cases; selective linkage is itself a validity threat.

Stop and check. Run /scholar-data dataset on your own research question. Look at the top three scored candidates and the score breakdown. If the top score is under 6.0, the honest reading is that your design and the available data are not yet aligned — fix that now, not at Phase 5.

10. scholar-eda — look before you leap

Goal: build the analytic sample, diagnose missingness, produce Table 1, and check distributional assumptions — before running any model.

argument-hint: "[dataset path or 'paste data below'] [outcome variable(s)]
                [optional: key predictor, causal design, journal,
                panel/cross-sectional]"

10.1 Run

> /scholar-eda data/processed/cfps-panel-long.rds
              outcomes=y1_access,y2_hours,y3_breadth
              focal=hukou_rural,cohort,female,eduy
              panel
              journal="Social Forces"

More examples across the input modes:

> /scholar-eda data/gss2022.dta happiness education income
> /scholar-eda NHANES 2017-2018 systolic_bp age race cross-sectional
> /scholar-eda paste data below wage education, tenure for ASR panel

10.2 Three input modes, and the gate in front of all of them

Before any of that, Phase 0a — the Data Safety Gate runs safety-scan.sh on every input, sets SAFETY_STATUS, and blocks on YELLOW or RED until you choose. If scholar-full-paper already set a status at Phase −1, scholar-eda inherits it and never downgrades it.

Phase 0c is the causal gate. The skill scans your prompt for DiD, difference-in-differences, FE, RD, regression discontinuity, IV, instrumental variable, matching, synthetic control, mediation, propensity score. On a hit it prints a redirect to /scholar-causal (§8D) before resuming at Phase 1. This is advisory, not a hard stop — but taking the redirect is nearly always right, because covariate choice depends on the DAG.

10.3 The eleven phases