Learn to work with Claude Code.

Part 00

Start here — how to use this guide

This guide turns you into an operator: someone who can sit down with Claude Code and get real work done for Paper St and its clients. You will not be writing code by hand. You'll be directing an AI that writes the code, the copy, the research — and that can touch tools like Gmail, the CRM, and the website. Your job is to brief it well and check its work hard.

The color key — read this once

The whole guide is colour-coded so you can scan it fast. Five box types, and you'll see them everywhere:

You'll also see term chips for vocabulary, monospace code for things you type, and the inverted highlight for the single sharpest idea on a page.

Part 0

Why you're here — the one big idea

What Paper St is, in one breath

Paper St builds the money-making "machine" inside a business, in the owner's name, and the owner keeps it forever. A client has a website, a CRM, ads, spreadsheets, a sales process — usually a tangle that leaks money. Joseph audits the tangle, then uses Claude Code to map it, wire it into one clean system, and improve it over time. The founder's line says it plainly:

The mission underneath that: the system that grows your business should be yours, not rented from someone who can take it back. Paper St doesn't sell "AI." Joseph's own framing is the north star for how you'll work:

What Joseph actually does all day

Strip away the buzzwords and a working day is some mix of these:

• Audit a business — find where leads, money, and data are leaking.
• Map the system — draw how the parts should connect (capture → qualify → sell → measure → learn).
• Build & remake — websites, landing pages, lead forms, dashboards, small tools.
• Wire data — make "which marketing actually made us money?" answerable.
• Research — sourced, honest, math-first (never opinion dressed up as fact).
• Communicate & deliver — emails, reports for the client's CEO, clean handoffs.
• Keep the paper trail — every decision and finding written down so the next session continues seamlessly.

Claude Code is the tool he does almost all of this with. That's why this guide starts there. Once you can drive Claude Code, you can help with every single item on that list.

The reframe that changes everything

Think of Claude Code as an extremely fast, extremely literal junior builder who has read everything but has never met your client. It will do exactly what you ask, very well — which means the quality of the result depends on the quality of your brief and the rigour of your check. Three operator jobs follow from that:

1. Brief well — say the goal, the constraints, and what "done" looks like.
2. Verify hard — never trust "it works" without seeing the proof yourself.
3. Hold the line on safety — never let anything reach a client or the public until it's been blessed.

Part 1

The words first — your vocabulary

Group A — the machine you're sitting at

Terminal a.k.a. command line, console

A plain text window where you type commands instead of clicking buttons. Why: it's how powerful tools (including Claude Code) are run. Looks intimidating, is just a text box.

CLI

"Command-Line Interface" — any program you run by typing into the terminal. Why: Claude Code is a CLI. So is the deploy tool you'll use.

Shell / Bash

The program inside the terminal that reads your commands. Bash is the most common one. Why: when we say "run this in bash," we mean type it in the terminal.

Linux

A free operating system that most servers and developer tools run on. Why: Claude Code and its tools are happiest on Linux.

WSL2 Windows only

"Windows Subsystem for Linux" — runs a real Linux inside Windows. Why: it lets a Windows laptop run the Linux tools without a second computer. This is exactly how Joseph's machine is set up.

Group B — Claude & Claude Code

Claude

The AI model itself (made by Anthropic). The "brain." Why: it's what reads, reasons, writes, and decides.

Claude Code

The CLI app that lets Claude actually do things on your computer — read/write files, run commands, edit a website, send a draft email. Why: a chat window can only talk; Claude Code can act. That's the whole difference.

Prompt

What you type to Claude — your instruction or question. Why: the prompt is your brief. Better prompt, better result.

Session

One continuous conversation with Claude Code, from when you start it to when you close it. Why: work is organised per session; you "open" and "close" them with rituals you'll learn in Part 5.

Context

Everything Claude can "see" right now — your messages, files it has read, results it got back. Why: Claude only knows what's in its context. If it didn't read a file, it doesn't know what's in it.

Model

A specific version of Claude (e.g. Opus, Sonnet, Haiku). Bigger = smarter + slower; smaller = faster + cheaper. Why: you match the model to the job.

Agent / Subagent

A helper Claude that the main Claude spins up to do one focused task (e.g. "go search these 200 files"). Several can run at once. Why: they let big jobs run in parallel — but there's a hard cap (see Part 5) because too many crash the machine.

MCP

"Model Context Protocol" — the standard plug that lets Claude Code talk to outside services (Gmail, the CRM, the website host, calendars). Why: MCP is the reason you can say "draft this email" or "read this CRM record" and Claude can actually do it.

Group C — the code & version world

Repo repository

A folder of files that's tracked over time. Why: every project lives in a repo so every change is recorded and reversible.

Git

The system that records every change to a repo — a time machine + undo button + history log. Why: if something breaks, you can see exactly what changed and roll back.

Commit

A saved snapshot of your changes, with a short note describing them. Why: commits are the save points. Clear notes = a readable history.

Push

Uploading your commits to the shared online copy (e.g. GitHub). Why: until you push, your work only exists on your laptop.

Branch · main · trunk

A branch is a parallel line of work. main (the "trunk") is the official line. Why: the Paper St brain repo is "trunk-only" — you work on main and push at the end. Client websites use side branches so nothing risky touches the live site.

Worktree

A second copy of a repo checked out to a different branch at the same time. Why: lets two streams of work run without colliding. You'll rarely need this early on.

Group D — the Paper St system

The brain repo

Paper St's single knowledge base: rules, playbooks, client records, the log, session notes. (Folder name: paperst-os.) Why: it's the company's memory. It is not a website — it never gets "deployed."

Playbook

A written, vetted procedure for a recurring task (build a site, run a security check, deploy safely). Why: playbooks are the standard operating procedure, not suggestions. You read the relevant one before you start.

Gate

A mechanical quality checkpoint that blocks shipping until the work passes. Why: gates are never "I think it's fine." They're checks that fail loudly on a real defect, so bad work can't slip out. The eye-gate is the human-look version: a person blesses how it actually looks before it ships.

Memory

Per-project notes Claude Code keeps between sessions — rules, lessons, live status. Why: so Claude doesn't relearn the project every time. An index file points to detail files.

The LEDGER

The one file where the status of every live thread + a log of every session lives. Why: you read it first each session to know where things stand.

Build-to-HOLD

Do all the safe, reversible work (build it, test it, stage it) but stop short of the irreversible step (send, merge, deploy) until Joseph says go. Why: it's the core safety posture — finish everything that can't hurt anyone, hold the one thing that can.

Deploy

Publishing a website or change to the live internet. Why: the highest-consequence action you can take. It's real, public, and immediate. Treated with the most care of anything in this guide.

Preview

A live-but-unlisted copy at a temporary URL, for checking before the real thing goes public. Why: it lets you see the real page live without touching the client's actual site.

Part 2

The mental model — how the pieces fit

Before installing anything, picture the whole flow. Here's what actually happens when you work, drawn the way Paper St draws systems — as a console map:

   YOU              CLAUDE CODE                THE WORLD                    SHIP
 (operator)         (the doer)            (what it can touch)

 [ BRIEF ] ───▶ [ CLAUDE reads,  ] ──▶ [ files · git · website ]
                [ reasons, acts  ]     [ Gmail · CRM · analytics ]
                       │               [ calendars · the web     ]
                       ▼                          │
                [ shows its work ] ◀──────────────┘
                       │
                       ▼
 [ VERIFY ] ◀── [ you check the proof ]
     │
     ▼  (passes the gates?)
 [ HOLD ] ──────▶ Joseph blesses ──────▶ ┃ LIVE ┃

Read it left to right: you brief → Claude does the work and touches real tools → it shows you the result → you verify → if it passes the gates it goes to HOLD → Joseph gives the final go → it goes live. Everything in this guide is teaching you to run one lap of that loop well.

The terminal, for someone who's never used one

Open the terminal and you'll see something like a blinking cursor after a bit of text (the "prompt"). You type a command, press Enter, it runs, it prints a result. That's the entire idea. Three commands you'll use constantly:

# where am I right now?
pwd

# what files are in this folder?
ls

# go into a folder named "paperst-os"
cd paperst-os

WSL2 — Linux living inside Windows

Developer tools assume Linux. Rather than buy a Linux computer, Windows can run a real Linux inside itself — that's WSL2. You open it like an app; inside, you're in Linux. Your Windows files are still reachable (under a /mnt/c/ path), and your Linux project files live in the Linux home folder.

Why a CLI and not a chat website

You may have used Claude in a browser. That's great for talking. Claude Code is different: it can open and change the actual files on your computer, run real commands, and reach real tools. That power is the whole point — and it's also why the safety rules in Part 5 exist.

Part 3

Install it — step by step

wsl --install

# grab the installer from the official NVM project
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# close and reopen the terminal, then install Node 22
nvm install 22
nvm use 22

# Option A — the one-line installer (what Joseph's machine uses)
curl -fsSL https://claude.ai/install.sh | bash

# Option B — via Node's package manager (npm)
npm install -g @anthropic-ai/claude-code

claude

npm install -g wrangler
wrangler login

# ~/.config/systemd/user/claude.slice
MemoryHigh=6G      # soft cap: slows down past here
MemoryMax=7500M    # hard wall
MemorySwapMax=1G

claude() {
  systemd-run --user --scope --slice=claude.slice -q -- \
    "$HOME/.local/bin/claude" "$@"
}

Verify everything installed

Run these. Each should print a version or a path, not "command not found":

which claude && claude --version     # e.g. 2.1.186 (Claude Code)
which node   && node --version       # e.g. v22.22.0
which wrangler && wrangler --version  # e.g. 4.92.0

Part 4

Set it up — config, memory & tools

Installed isn't the same as configured. This part is the difference between "Claude Code runs" and "Claude Code knows how Paper St works and can touch the right tools."

The ~/.claude folder — Claude's home base

When you install Claude Code it creates a hidden folder, ~/.claude (the ~ means "your home folder"). The pieces that matter:

Two kinds of CLAUDE.md — the most useful thing to understand

There are two rule files and knowing the difference saves a lot of confusion:

• Global (~/.claude/CLAUDE.md): rules for you, everywhere — e.g. "be terse," "honest math first," "max 4 helper agents."
• Project (a CLAUDE.md file inside a repo): rules for that project — e.g. "this repo is trunk-only, push at session end."

The memory system — why Claude doesn't forget

A fresh AI starts every conversation blank. That would mean re-explaining the whole project daily. Memory fixes that. It works as an index plus detail files:

• MEMORY.md is the index file that lives inside the memory folder — one line per memory, with a link. It's loaded every session.
• Each memory is its own small file with the actual detail (a rule, a lesson, a client fact).
• It's kept tidy and small on purpose, and synced so it survives across sessions.

MCP — how Claude touches Gmail, the CRM, the website

MCP is the plug-in system that connects Claude Code to outside services. You set a service up once; after that, Claude can use it by name. On Joseph's machine these are wired up:

You connect a service either through the Claude app's integrations screen or with a small config file (.mcp.json) in a project. You don't need to memorise how — just know that "MCP" is the answer to "how can Claude send an email or read the CRM?"

Part 5

Your first session — the actual workflow

This is the part you'll live in every day. A session has a start ritual, the work, and an end ritual. Follow the rhythm and you'll never lose your place.

Starting a session

# go into the project folder, then start Claude
cd ~/paperst-os
claude

Then, before asking for anything, have Claude (or yourself) read the lay of the land:

1. Read TODO.md — the single backlog: what needs doing.
2. Read LEDGER.md — where every live thread stands + the session log.
3. Open the relevant playbook for the task you're about to do.

How to brief Claude well

A good brief has three parts. Compare:

And let Claude push back. Joseph wants the AI (and you) to behave like an advisor, not a yes-machine — to challenge a weak plan, flag a risk, and ask the question that changes the approach. If something seems off, say so.

Watching it work

Claude will narrate what it's doing and ask permission before risky actions (editing files, running commands). You'll see it read files, make edits, run commands, and report back. You can interrupt any time. For bigger jobs you can ask it to plan first and show the plan before doing anything.

The gates & build-to-HOLD

Nothing client-facing ships on "looks fine to me." It passes gates — mechanical checks (does the content match? does it work on a phone? is it accessible?). And one gate is not mechanical:

Once it passes, you build-to-HOLD: stage it, preview it, get it fully ready — and stop before the irreversible step. Joseph gives the final go.

The hard safety rules — memorise these

Ending a session

1. Commit your work with a clear note (stage the specific files you changed — never blindly "add everything").
2. Push so it's saved to the shared copy.
3. Write a short handoff — what you did, what's next, any decision waiting on Joseph — so the next session starts informed.
4. Update memory with any lesson worth keeping.

Your first real ship — do it now

"Make a folder called hello-site with one index.html
that says 'Hello from [your name]' as a big heading,
then deploy it with wrangler pages deploy and give me the URL."

Part 6

How real work flows — a real engagement

The messy starting point

A real client — a long-established insurance brokerage — came to Paper St with a tangle that's typical:

• They couldn't answer "which marketing actually made us money?" — the tracking data was blank or garbled on most sales.
• Their online quote tool was slow, and sometimes the checkout silently broke — customers ready to buy got stuck.
• Their operations lived in well over a hundred disconnected spreadsheets, with the same information re-typed across half a dozen systems.

A beginner's instinct is to "fix the website." That would miss most of the problem. Here's what Paper St did instead.

The move: decompose into tracks

Rather than one giant project, the work was split into parallel tracks, each with a clear owner-question, the right tool, and its own living source-of-truth document:

 ONE MESSY ENGAGEMENT
        │
        ├─▶ [ ATTRIBUTION ]  which marketing made sales?   → CRM + analytics
        ├─▶ [ SPEED      ]  why is checkout slow/broken?   → client code (read)
        ├─▶ [ SITE REMAKE]  rebuild the funnel pages       → preview URLs
        ├─▶ [ CRM WIRING ]  make the data answerable       → CRM
        └─▶ [ OPS UNIFY  ]  link the scattered boards      → ops board (read)

   every track ──▶ a living doc ──▶ findings (sourced) ──▶ ┃ HOLD ┃

One tool per track — the right reach for the job

This is MCP in action. Each track touched a different real system, all through Claude Code:

The discipline that kept it safe

• Read-only on everything the client owns. No live changes were made; findings and fixes were prepared and held.
• All comms routed through one person. The client's tech lead was the single point of contact — you don't scatter messages across a client's team.
• Verify the value to the wire. A code fix that looks correct can be dead in practice if a later step quietly drops the value. So every fix was traced all the way to where the data actually lands, then confirmed in live data.
• No dollar promises. No "this will make you $X" until it could be honestly measured after going live.
• Everything to HOLD. Rebuilt pages, code fixes, reports, notes — all finished and ready, none applied. The client decides when to flip the switch.

Part 7

The Paper St way — the non-negotiables

Tools are learnable in a week. This part is the harder, more valuable thing: how Paper St thinks. Get these and you'll make calls Joseph would make even when he's not in the room.

1. Transparency first, sales second — always

Every problem gets solved with honest math — real hours, real costs, a named margin — before any persuasive framing goes on top. Source every number. When you're unsure, say you're unsure ("estimated at," "this would likely," "depending on X"). Never state a guess as a fact.

2. Advisor-CEO posture

You're not a robot operator. Challenge weak scope. Surface a risk nobody named. Show the thing early. Say when it's not good enough. When you take a call, state it, defend it with reasoning, offer a fallback, and ask the question that unblocks the next step.

3. Proof standard

Decide what "passing" means before you build (so you can't move the goalposts later), and verify it independently after (a fresh check, not the builder grading their own homework).

4. Build-to-HOLD

Do everything that's safe and reversible — thoroughly, without stopping to ask permission for each small step. Hold back only the few irreversible things: sends, merges, deploys, and decisions that are Joseph's to make.

5. First-principles channel check

Before diving into a task, step back: What's the actual end goal? Why are we doing this particular step? Is there an easier, faster, higher-leverage path? A playbook is a means, not the goal. If a better route is sitting in plain sight, say so before you spend a day on the slow one.

Part 8

Get going — practice, cheat sheet & when you're stuck

The practice ladder

Don't try to do everything at once. Climb these in order — each builds the muscle for the next:

1. Just talk. Start a session, ask Claude to explain this very guide back to you, and to define any term you're unsure of. Get comfortable with the back-and-forth.
2. Read the lay of the land. Have Claude read the TODO and LEDGER and summarise, in plain English, what's currently in flight.
3. Build & ship a toy. Do the "Hello" page from Part 5 and put it live on a preview URL. Then take it down.
4. Remake something small with a brief. Pick a simple page, write the three-part brief (goal / constraints / done), and have Claude build it to a preview. Eyeball it on a phone.
5. Do a real task to HOLD. Take one real TODO item, do it fully, stop at the irreversible step, and write the handoff. Bring it to Joseph as "done and held, ready for your go."

One-screen cheat sheet

When you're stuck

• Ask Claude first. "I don't understand X — explain it like I'm new." It's a patient teacher. Genuinely.
• Look before asking a human. Search the repo / the LEDGER / the playbooks. The answer is often already written down.
• When you do ask Joseph, ask sharp. Bring 2–4 questions that would actually change the plan — not "is this okay?" but "I see two paths, A trades speed for X, B trades cost for Y — which do you want?" An empty question list beats a padded one.