What Claude Assumes You Already Know

Part I chapter draft. A browsable directory of the invisible substrate — the operating-system and command-line plumbing Claude name-drops without stopping to explain. This chapter is the “browse” front door; the Briefings appendix is the “read the whole thing” depth behind each entry. Working title.

Why this chapter exists

Every other reference in this book answers a question you already know how to ask. The glossary waits for you to look up a word. The Briefings wait for you to follow a link. Both are lookup tools — and lookup only works when you already know there’s something to look up.

This chapter is for the other question, the one you can’t phrase yet: what am I missing that I don’t even know I’m missing?

When Claude tells you it “put the binary in ~/.local/bin so it’s on your PATH,” a working developer hears four familiar ideas and moves on. You hear one sentence with three holes in it. The holes aren’t your fault — this is infrastructure that got standardized decades ago and then went invisible, the way plumbing disappears behind a wall. Nobody explains it because everybody who works with it forgot they ever had to learn it.

So this is a guided tour of that plumbing. Read it straight through once. You will not memorize it, and you’re not meant to — the goal is recognition, so that the next time Claude uses one of these terms, a small light goes on: “I’ve seen this; I know roughly what it is; and I know where to go if I need more.” Each entry is one or two lines — what it is, and why it will eventually matter to you. When you want the full explanation, the arrow (→) points to the Briefing that has it.

The entries are grouped by idea, not alphabetized, on purpose. The grouping is the lesson: these things cluster into a handful of mental models, and once you see the clusters, the individual pieces stop feeling like random incantations.

How to read the entries. Each line pitches, it doesn’t teach. It gives you just enough to decide whether you care right now. If you do, follow the arrow. If you don’t, keep browsing — you’ve still gained the one thing that matters most, which is knowing the thing exists and has a name.

How your computer finds and runs a command

The single richest source of confusion for a new command-line user. When Claude says a command “isn’t on your PATH” or “exited non-zero,” it’s speaking this dialect.

• PATH — the ordered list of folders your shell searches when you type a command name. This one idea explains the majority of “command not found” errors Claude hands you, and why installing a program is not the same as being able to run it: the program can be sitting on your disk and still be invisible because its folder isn’t on the list. → Briefing: PATH
• Exit codes — the single number a command leaves behind to say whether it worked. 0 means success and everything else means a failure — backwards from what you’d guess, and load-bearing for anything automated, because scripts decide what to do next by reading that number, not by understanding the output. → Briefing: Exit codes
• stdout and stderr — every command has two output streams, one for its actual results and one for its complaints. They look identical on your screen but they’re separate pipes, which is why an error can vanish when Claude “captures the output” — it captured the wrong pipe. → Briefing: Standard streams

Where things live: the filesystem

The folder layout on a Unix-style machine (macOS and Linux) isn’t arbitrary. It follows a decades-old map, and Claude navigates by that map constantly.

• The filesystem hierarchy — why there’s a /usr, an /etc, a /var, and what each is for. Claude chooses install locations based on this map; knowing it turns “why did it put the file there?” from a mystery into a decision you can follow. → Briefing: The filesystem hierarchy
• ~/.local and the user-scope mirror — when Claude installs something “just for you” instead of system-wide, it lands here, in a folder structure that deliberately mirrors the system one. There’s a published 20-year-old standard behind the exact paths, not a whim. → Briefing: XDG & ~/.local
• Dotfiles — the reason your home folder is secretly full of files and folders whose names start with a . (like .zshrc or .gitconfig) that you never created and normally can’t see. The leading dot means “hide me”; the contents are configuration. → Briefing: Dotfiles

The shell itself

You type into “the terminal,” but several distinct things are stacked inside that one window, and Claude’s instructions sometimes depend on which one you actually have.

• Terminal vs. shell vs. prompt — the window, the program running inside it, and the little $ waiting for input are three different things with three different names. Worth untangling because “open a terminal” and “you’re using zsh” are statements about different layers, and cross-platform advice breaks along exactly these seams. → Briefing: Terminal, shell, prompt
• Environment variables — named values the shell carries around and hands to every program it launches (PATH is secretly one of these). They explain why a setting works in one terminal window and not another, and why they evaporate when you close it unless you wrote them into a dotfile. → Briefing: Environment variables
• Shell config files (.zshrc and friends) — the dotfile your shell reads every time it starts, where “make this setting permanent” actually happens. When Claude says “add this line to your .zshrc,” this is the machinery it’s reaching for. → Briefing: Shell startup files

Identity and permission

Two quiet gatekeepers. When something “works for Claude” but not when you try it, or when GitHub refuses you, the answer is usually one of these.

• File permissions and the executable bit — every file carries flags for who may read, write, or run it. A script can be perfect and still refuse to run because it was never marked runnable — the infamous chmod +x. → Briefing: File permissions
• SSH keys — the passwordless “who are you?” handshake between your machine and services like GitHub. A matched pair of files, one you share and one you never do; grasping the pair explains most “permission denied (publickey)” walls. → Briefing: SSH keys

Versions and packages

Software is assembled from other people’s software, at specific versions, and the notation for “which version” is its own small language.

• Semantic versioning — the meaning encoded in a number like 2.4.1, and why the jump from 1.x to 2.0 is a warning while 2.4 to 2.5 is routine. Claude reasons about upgrade safety from these numbers; so can you, once you can read them. → Briefing: Semantic versioning
• Lockfiles — the auto-generated file (package-lock.json, go.sum, and kin) that pins the exact versions your project actually used, so it builds the same on your machine as on anyone else’s. You never edit it by hand, but you should know why Claude keeps regenerating it. → Briefing: Lockfiles
• Package managers — introduced back in Building Blocks as a category; the Briefings cover the specific ones (Homebrew, npm, pip) as you meet them, including the recurring trap that “installed” and “runnable” are two different states (see PATH, above). → Briefing: Package managers

The big one, handled elsewhere

• Git / version control — the system that records every change to your code and lets you undo, branch, and collaborate. It’s foundational enough that it isn’t a Briefing at all — it earns its own full treatment in Chapter TK, Version Control, because half the later book (tech debt, team adoption, code review) assumes it. Flagged here so the map isn’t missing its largest landmark.

What to do with this chapter later

You just took the tour. Three things follow from that:

1. You don’t need to retain the details. You need the index in your head — the sense that “finding and running commands,” “where files live,” “the shell,” “identity and permission,” and “versions” are the five neighborhoods, and roughly what lives in each.
2. The arrows are your depth control. Any single entry expands into a few-minute Briefing the moment you actually hit that term in the wild. Read them on demand, not now.
3. This is where “call a developer” gets honest. A couple of these (SSH keys, permissions) are where a non-developer’s self-service reasonably ends. The Briefings say so explicitly when they do — the same honesty tag the pathology chapters use.

Draft notes (not for the reader)

• Boundary vs. Ch 1 (Building Blocks): Ch 1 introduces categories (what a shell is, what a package manager is, what an API is). This chapter is the substrate specifics Claude name-drops — PATH, exit codes, ~/.local, SSH keys — the things Ch 1 doesn’t have room for. Keep the seam clean: if a term names a whole category, it’s Ch 1; if it names a specific piece of plumbing you’d meet mid-session, it’s here + a Briefing.
• Boundary vs. Ch 2 (Ecosystem Map): Ecosystem Map tours the named products you choose between (React vs. Vue, Postgres vs. SQLite). This chapter tours the invisible OS layer you don’t choose — it’s just there. Same browse-and-orient function, different layer.
• Entry format is fixed: one to two sentences, what it is + why you’ll care, never a compressed explanation. The explanation lives in exactly one place (the Briefing). If an entry starts teaching, move the teaching to the Briefing and trim the entry back to a pitch.
• Group set is provisional: five neighborhoods feels right for a browsable single sitting; if it grows past ~7 groups or ~4 entries each, it’s turning into a glossary and should be split.
• Confirm the version-control cross-ref once that chapter has a real number/title.

Found something wrong, unclear, or plainly disagreeable? Open an issue