Thirteen sections. Read them in order the first time — each one assumes the one before it. After that, use the sidebar and the search box like an index.

0.1 What's in the box

0.2 The three symbols

0.3 One thing before you start

You cannot break the computer by typing. Almost every mistake in this manual is recoverable in under a minute once you know where the undo lever is — and we'll show you where it is, section by section. The exceptions get the WATCH OUT flag. There are four in the whole manual.

The other thing: you are not learning to be a programmer. You're learning to be the person who runs the shop — who knows what each machine does, what good work looks like, and when to stop the line. The AI is the set of hands. You're the diagnosis.

0.4 The build-along

Reading doesn't stick. Doing does. So this manual has a project threaded through it — eight small steps, one every couple of sections, each using exactly what you just read. By Section 10 you'll have built shop-planner: a real tool that reads the week's work orders and the team roster and lays out the load — who works on what, in which bay, each day — flagging anything blocked on parts. And once it works, re-planning when reality moves becomes a one-line request to your AI. If you don't run a shop, do it anyway with this data; the moves are identical for whatever you swap in later.

1.1 Everything is a file in a folder

There is no magic storage. Every photo, invoice, program and setting on your machine is a file, and every file sits in a folder (also called a directory — same thing, different decade). Folders sit inside other folders — that's nesting, and each step inwards is one level. That's it. That's the whole system.

You already know how to walk through it, because that's all Finder and File Explorer are — a pair of glasses over that structure. Every double-click takes you down one level, and the address bar quietly writes down where you went. That written-down trail is the file's address, and it's what you'll be handing to other tools from here on.

~/                                ← "home". Everything of yours lives under here.
├── Desktop/
├── Documents/
├── Downloads/                    ← a landing strip, not a garage. Empty it weekly.
├── Pictures/
└── code/                       ← MAKE THIS ONE. All your projects go here. 
    ├── pm-board/
    │   ├── README.md             ← what this project is, in plain English
    │   ├── .git/                 ← hidden. Git's logbook (§ 09). Never touch by hand.
    │   └── src/
    │       └── main.py
    └── shop-hours/

1.2 A path is an address

When you tell the terminal or an AI agent "work on this file", you give it a pathThe full address of a file, written as folder names separated by slashes. — the full address, read left to right, biggest container first: like reading a mailing address from the country down to the house number.

Absolute vs relative. Two ways to write the same address:

• Absolute — starts at the top and spells out everything: /Users/dan/code/pm-board/README.md
• Relative — starts from wherever you're currently standing: src/main.py means "the src folder right here, then main.py"
• .. — two dots means "up one level"

Terminal commands and AI agents both understand either; absolute is safer when you're unsure.

1.3 Turn on the two things they hide from you

Out of the box, both operating systems hide information you now need. Fix that once and forget about it.

File extensions. The .pdf, .py, .txt at the end of a filename is the label that tells you — and the computer — what kind of file it is. It matters for two reasons. First, the work ahead: a project folder is full of files that look identical as icons (notes.md, notes.py, .env) and differ only by extension, so with extensions hidden you're editing blind. Second, safety: with extensions hidden, a program named invoice.pdf.exe shows up as "invoice.pdf" — you think you're opening a document, you're actually running someone's program. That one trick is behind a huge share of malware infections, and showing extensions defuses it completely.

• macOS: Finder → Settings → Advanced → tick "Show all filename extensions".
• Windows: File Explorer → View → Show → tick "File name extensions".

Hidden files. Anything starting with a dot (.git, .env, .gitignore) is hidden by default. These are config and bookkeeping files — you'll be dealing with them constantly.

• macOS: in any Finder window press ⌘ Shift .
• Windows: File Explorer → View → Show → "Hidden items".

1.4 Build your workbench

One folder, in your home directory, called code. Every project you build with AI lives in there as its own subfolder. Not on the Desktop. Not in Downloads. Not scattered across three cloud drives.

Why it matters: when you point an agent at a folder, it can see everything inside it and nothing outside it. A clean, single-purpose folder is the difference between "fix the bug in this script" and the agent rummaging through your tax returns.

That dark block is the first of many in this manual. It's the terminal — the typing window from the primer above — and the $ or > at the start of each line is just the computer saying "your turn"; you don't type it. Section 07 is the proper introduction, and nothing here breaks if you skip ahead to it now.

You can also just right-click in your home folder and choose New Folder. Identical result — mkdir is only faster once you're already in there.

1.5 What the AI needs from you

2.1 How to name a file

Three rules. They look fussy until the first time you type a filename into a terminal.

1. No spaces. Use a hyphen. The terminal treats a space as "next argument", so shop hours.csv reads as two separate things and everything breaks. shop-hours.csv never does.
2. Lowercase. Some systems think Report.pdf and report.pdf are the same file, some don't. Pick lowercase and the question never comes up.
3. Dates as YYYY-MM-DD. 2026-03-14-compressor-log.csv. Sorts itself chronologically, forever, in every program.

Rule of thumb: if you'd have to put quotes around it in the terminal, rename it.

2.2 What "the cloud" actually is

The cloud is a rented computer in a building somewhere, with a very good internet connection. That's the whole mystery. When a file is "in the cloud", there's a copy of it on that machine, and usually a copy on yours too, and a program keeping the two identical.

The important distinction, and the one that bites people:

2.3 The 3-2-1 rule

The industry standard, and it's simple enough to remember at 2am when a drive dies.

For your code projects specifically, GitHub (Section 09) is your offsite copy, and it's free. Turn on Time Machine or File History for everything else and you're done thinking about this. One catch on Windows: File History hides in the old Control Panel — search Start for "File History" — and it wants an external drive plugged in before it'll run.

2.4 Formats you'll meet