E156 Ecosystem Starter

Easiest — open in your browser, full install, zero terminal

If you have never used a terminal, click this button. A free GitHub-hosted workspace opens with the full system pre-installed: rules, memory, Sentinel pre-push hook, Overmind verifier with a TruthCert HMAC key, ProjectIndex seed, and Gemini CLI. Nothing installs on your laptop.

Open in GitHub Codespaces → ~2-3 minute build. Best on a desktop or laptop — Codespaces in a phone browser technically works but the terminal is unreliable. Requires a free GitHub account (see below if you don't have one yet). What is a Codespace?

No GitHub account yet? Read this first.

If you have a university email ending in .ac.ug, .ac.za, .edu.pk, .edu, etc. — apply for GitHub Education first. You get 90 free Codespaces hours/month (vs 60), no phone-verification step, and access to other paid tools (Copilot, JetBrains, etc.).
If you only have personal email (Gmail/Yahoo) — sign up at github.com/signup. GitHub will ask for SMS phone verification; this can fail silently on some African mobile networks (Airtel, MTN). If your code never arrives, retry from a different network or use the GitHub Education path above.
If your phone is your only device — borrow a friend's laptop for the first 90 minutes of setup; after that you can do most writing from your phone via the GitHub web editor.

What is a GitHub Codespace? (1-paragraph version)

A Codespace is a Linux computer that runs in GitHub's cloud, with VS Code (a code editor) opened in your web browser. Nothing installs on your laptop — everything happens on the cloud machine. You write code in the browser, save it to GitHub, and it's still there when you close the tab. Free for 60 hours/month on personal accounts (90 on Education accounts), then pauses until next month. Like Google Docs, but for a programming environment.

Already installed an older version? (upgrading)

If you ran the installer before (e.g. v0.7.0 in March), just re-run the same one-liner at the top of this page. The new bootstrap pulls the latest tagged release and overwrites your rules + memory templates. Files you've edited yourself (*.md.user) are preserved. To check what version you have installed, in any Codespace terminal run e156 version.

If a re-install fails with "install.ps1 hash mismatch", that just means your locally-cached install.ps1 is older than the recorded hash for the new version — re-running the bootstrap one-liner will pull a fresh copy and resolve it.

…or install locally on your own machine:

Windows

Recommended — PowerShell one-liner (works under Smart App Control):

irm https://mahmood726-cyber.github.io/e156-ecosystem-starter/bootstrap.ps1 | iex

Open PowerShell, not Command Prompt. Press Win+R, type powershell, press Enter. Paste the line above, hit Enter. (PowerShell has a blue background; cmd.exe has a black background and won't recognize irm.)

Download .bat installer

Double-click to install. May be blocked by Smart App Control — see workarounds below.

macOS / Linux / WSL

One-liner for any Unix shell:

curl -fsSL https://mahmood726-cyber.github.io/e156-ecosystem-starter/e156-setup.sh | bash

Works on macOS Terminal, Linux distros, and Windows Subsystem for Linux (WSL). Requires python3, curl, and unzip on PATH.

Download .sh installer

Then: chmod +x e156-setup.sh && ./e156-setup.sh

If Smart App Control or SmartScreen blocks the .bat: Windows 11 Smart App Control (different from SmartScreen) blocks unsigned downloaded scripts without a "Run anyway" button. Three ways through, in order of effort:

Easiest — use the PowerShell one-liner above. Smart App Control allows iex from a trusted Microsoft origin (your shell), and the script runs in memory without writing an unsigned executable to disk first.
Unblock the .bat manually. In File Explorer, right-click e156-setup.bat → Properties → tick Unblock at the bottom → OK. Then double-click again. Or in PowerShell:
```
Unblock-File ~\Downloads\e156-setup.bat
~\Downloads\e156-setup.bat
```

Power-user fallback — clone the repo directly (Smart App Control trusts git.exe):

git clone https://github.com/mahmood726-cyber/e156-ecosystem-starter
cd e156-ecosystem-starter
.\install\install.ps1

The source is open and auditable here (PowerShell) and here (.bat).

Verify your install worked

After the installer says it's done, run this to confirm the rules + memory landed correctly:

# Windows PowerShell
ls $env:USERPROFILE\.claude\rules
ls $env:USERPROFILE\.claude\memory

# macOS / Linux / WSL
ls ~/.claude/rules
ls ~/.claude/memory

You should see four .md files in rules/ (e156, lessons, advanced-stats, rules) and MEMORY.md + a templates/ folder in memory/.

Then start an agent in any directory and ask it about the rules:

cd ~          # or any folder you want to work in
gemini "Summarise the rules I have configured in my .claude/rules/ folder"

If the agent answers with E156, lessons, advanced-stats, and rules content, you're set. If it says "I don't see those rules" the agent CLI isn't reading the global config dir — check "Set up an AI agent CLI" below.

Next step — produce work at the same quality bar

Installing the rules is half the job. The other half is using them with the same method: brainstorm → spec-lock → plan-lock → TDD → audit. That workflow is what turns the enforcement machinery (Sentinel, Overmind) into shippable papers instead of just "code that doesn't break."

Read STUDENT-WORKFLOW.md for:

The 5-step path to your first E156 paper (with the student new CLI from e156-student-starter).
The brainstorm → spec-lock → plan-lock → TDD → audit method, with the case studies that validated each step.
Worked-example repos to clone and reproduce: ma-workbench (sglt2i-hfpef), repro-floor-atlas, responder-floor-atlas, impossible-ma.
How Sentinel + Overmind verdicts function as quality gates (and what UNVERIFIED means — it is not a release pass).

What this installs

Layer	Purpose
AI agent rules	Four curated rules files that load into Claude Code, Gemini CLI, and Codex automatically.
Memory scaffold	Cross-session memory the AI grows as you work. Four types: user profile, working-style rules, project notes, external references.
AGENTS.md / CLAUDE.md / GEMINI.md / CODEX.md	Per-agent context files so all three CLIs behave consistently.
Sentinel (optional)	Pre-push hook with 28 rules that block the common AI-agent defects (hardcoded paths, placeholder HMAC, silent sentinels, XSS sinks, empty-DataFrame access, leaked secrets, lockfile integrity, baseline drift) in about 2 seconds per push.
Overmind + TruthCert (optional)	On-demand verifier that runs tests + smoke + numerical baselines and emits HMAC-signed certification bundles for submissions.
ProjectIndex (optional)	Portfolio tracker + fail-closed reconcile script that catches registry drift.
long-term-plan (optional)	Weekly-refreshed deterministic backlog reranker. No LLM in the loop. Clones mahmood726-cyber/long-term-plan as a reference; you replace its ideas with your own.

Install in 3 steps

1. Click Download for Windows above.

2. Open your Downloads folder and double-click e156-setup.bat.

3. Answer the Yes/No prompts (all default to Yes). Done in about 2 minutes.

Prerequisites

You'll need three free tools installed before running the bootstrap. Do these in order — the bootstrap will fail-closed with a clear message if any are missing.

1. Python 3.11 or newer

Critical: Windows 10/11 ships with a Microsoft Store stub at python.exe that looks like Python is installed but actually opens the Store when you try to use it. You must install real Python from python.org, not the Store. The bootstrap detects the stub and refuses to continue if it's all you have.

1. Download from python.org/downloads (latest 3.x — currently 3.13).

2. Run the installer. On the first screen, tick "Add python.exe to PATH" — this is the most-missed step.

3. Click Install Now. It takes about 1 minute.

4. Verify in a new PowerShell window:

python --version

You should see Python 3.13.x (or whichever version you installed). If you see "Python was not found" or it opens the Microsoft Store, the Store stub is shadowing your install — fix it via Windows Settings → Apps → Advanced app settings → App execution aliases → toggle off python.exe and python3.exe.

2. R 4.5 or newer

Used for cross-validating meta-analysis pools against the gold-standard metafor package. Without R, the validation step in your dashboards will be skipped.

1. Download from cran.r-project.org/bin/windows/base/ (the big "Download R x.y.z for Windows" link near the top).

2. Run the installer. Default options are fine. R installs to C:\Program Files\R\R-x.y.z\.

3. Add R to PATH (the installer doesn't do this automatically). In PowerShell:

# find where Rscript was installed
$rDir = (Get-ChildItem 'C:\Program Files\R' -Directory | Sort-Object Name -Descending | Select-Object -First 1).FullName + '\bin'
[Environment]::SetEnvironmentVariable('Path', "$env:Path;$rDir", 'User')

Close and reopen PowerShell so the new PATH loads.

4. Verify:

Rscript --version

You should see Rscript (R) version 4.x.x.

5. Install the metafor package (used for validation):

Rscript -e "install.packages('metafor', repos='https://cloud.r-project.org')"

Takes about 2 minutes. You only need to do this once per machine.

3. Node.js 20 or newer

Needed because Gemini CLI / Claude Code / Codex are all distributed via npm.

1. Download the LTS version from nodejs.org/en/download.

2. Run the installer with default options.

3. Verify in a new PowerShell window:

node --version
npm --version

You should see v20.x.x or higher.

4. An AI agent CLI

See "Set up an AI agent CLI" below. Gemini CLI is recommended for new students because Google gives you a generous free API key (no credit card needed).

5. Internet connection

About 50 MB of pip deps if you opt into Sentinel + Overmind during install.

Set up an AI agent CLI

The starter rules and memory are designed for three agents. You only need one to get going. If you're starting from zero, install Gemini CLI — the free tier is the most generous.

Option A: Gemini CLI (recommended — free tier)

1. Install Node.js 20 or newer (Windows installer, default options).

2. Open a fresh PowerShell window and install the CLI globally:

npm install -g @google/gemini-cli

3. Get a free Google API key (no credit card needed):

Go to aistudio.google.com/app/apikey and sign in with any Google account.
Click Create API key → Create API key in new project.
Copy the long key (starts with AIza...). Treat it like a password — never paste it into a public repo or chat.

4. Tell Windows the key is yours so the CLI can find it:

setx GEMINI_API_KEY "paste-your-key-here"

Close and reopen your terminal so the new variable loads.

5. Test it:

gemini "summarise this file" < README.md

If you get a coherent answer, you're done.

Free-tier limits (Google AI Studio): currently 1,500 requests/day and 1M tokens/min on Gemini 2.0 Flash, with no card required. That's far more than a typical student week of meta-analysis work. If you hit a quota wall the CLI will tell you to wait until UTC midnight. Quotas change — check ai.google.dev/gemini-api/docs/rate-limits.

Option B: Claude Code

Paid (Anthropic API or Claude Pro/Max). Best at long-context work. Install:

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

See docs.anthropic.com/en/docs/claude-code.

Option C: OpenAI Codex

Free with a ChatGPT Plus account (uses your subscription quota), or pay-per-token via API key. Install:

npm install -g @openai/codex
codex

On first run it walks you through sign-in. See github.com/openai/codex.

What can I build with this? — example projects

Once the agent + rules are installed, you can build small but real research artifacts in a few hours. Pick one. Each is sized for a single sitting and produces something you can put on your CV.

Project	What you build	Skill stretched
1. Mini meta-analysis (E156 paper)	Pick 3–5 trials on a topic that interests you (e.g. SGLT2 inhibitors in heart failure, antidepressants in mild depression, ivermectin in COVID). Pool effect sizes with DerSimonian–Laird, write a 156-word E156 micro-paper, ship as a single-file HTML dashboard on GitHub Pages.	Asking the agent for the right pooling formula, validating against R `metafor`, learning to write tight scientific prose.
2. Forest-plot tool from scratch	Build a single-file HTML page where the user pastes a CSV of `study, effect, lower, upper` and gets a forest plot + pooled diamond + I². No backend, pure JS + SVG.	SVG, statistical formulas (Q, τ², HKSJ), the discipline of writing tests before code.
3. Risk-of-bias dashboard	RoB 2 traffic-light table for a real Cochrane review of your choice. Read the review, score each domain, render a coloured matrix + summary stacked bar.	Reading critically, structured data entry, accessible HTML (proper labels, ARIA).
4. CT.gov mini-audit	Pull all interventional trials in your country / specialty from the ClinicalTrials.gov v2 API, count completed but no results posted at 2 years. One page, three numbers, one chart.	REST APIs, pagination, dates, honest framing of negative findings.
5. PRISMA flow diagram generator	Input: numbers from each screening stage (records identified, duplicates, screened, full-text, included). Output: PRISMA-2020 SVG diagram you can paste into a paper.	SVG layout, working backwards from a published standard.
6. Living NMA prototype	Pick a 3-arm decision (e.g. ARNI vs ACEi vs ARB in HFrEF). Build a Bucher indirect-comparison engine. Add a "what if a new trial reports HR=X" slider that re-pools live.	Network meta-analysis arithmetic (consistency assumption), interactive UI design.
7. Evidence-update bot	Cron-style script that re-queries CT.gov for new trials matching a saved PICO and emails / commits a JSON diff. Useful for keeping a review "living".	Scheduled jobs, diffing structured data, knowing when to alert vs stay silent.
8. Replication of a published figure	Pick a forest plot from a recent NEJM/Lancet meta-analysis. Re-extract the trial table, re-pool, regenerate the figure. Note any discrepancies.	Reading methods sections precisely, debugging "why don't I get the same number".

Each project should ship as one GitHub repo + one GitHub Pages dashboard + one E156 micro-paper (156 words). The starter rules teach the agent how to keep all three in sync.

Power users

Prefer git? Clone and run directly:

git clone https://github.com/mahmood726-cyber/e156-ecosystem-starter
cd e156-ecosystem-starter
.\install\install.ps1 -Full

CI / unattended:

.\install\install.ps1 -NonInteractive

What if something goes wrong

Python not found → install from python.org, tick Add Python to PATH.
Download blocked → check your firewall isn't blocking github.com.
Install failed mid-way → the installer writes a transcript to %LOCALAPPDATA%\e156\logs\install-<ts>.log. Open an issue with that log attached, or run .\scripts\doctor-report.ps1 to package it.
SmartScreen or Smart App Control blocked the .bat → switch to the PowerShell one-liner (top of page) which avoids the unsigned-binary check entirely. SmartScreen's More info → Run anyway works for it; Smart App Control has no override and the one-liner is the only option there.

Security model — what the SHA gate does and doesn't protect

The SHA gate is for download integrity, not source integrity. Specifically:

What it catches: tampering of install.ps1 / install.sh between the GitHub Pages CDN and your laptop (corrupted download, MitM injection on a hostile network). The installer hashes itself against docs/HASH.txt / docs/HASH-linux.txt fetched from the same origin and refuses to run on mismatch.
The bootstrap entrypoints (bootstrap.ps1, e156-setup.bat, e156-setup.sh) are not SHA-gated. They run before the gate fires; they then fetch the rest of the repo and the SHA-gated install.ps1 validates itself. So a tampered bootstrap script could short-circuit the gate entirely. The bootstrap layer is small and auditable — read the source via the links below before running it on a security-sensitive machine.
What it does not catch: compromise of the GitHub repo itself. A bad actor with push access to mahmood726-cyber/e156-ecosystem-starter can update install.ps1 AND docs/HASH.txt together and the gate will pass. Any curl|bash-style installer has this property.
For high-trust installs (e.g. a department lab with sensitive data), prefer the git-clone path with a tagged release: git clone --branch v0.x.y --depth 1, verify the tag's GPG signature, then run .\install\install.ps1 from the clone. The signed tag is a trust anchor independent of the Pages CDN.
What runs locally: the install touches ~/.claude, ~/.gemini, ~/.codex, and (if you opt in) %USERPROFILE%\code\. It does not require admin rights, does not modify system PATH, and rolls back on failure. The full source is auditable on GitHub.
Sub-installer pinning: the optional Sentinel and Overmind chains pip-install from GitHub. Both are pinned by default (SENTINEL_REF=v0.1.0, OVERMIND_REF=<known-good-SHA>) so a fresh install is reproducible even if upstream main drifts. To opt into bleeding-edge or roll back a release: set $env:SENTINEL_REF / $env:OVERMIND_REF to any branch, tag, or commit SHA before running the chain installer.