First phase of /root. Linux as your daily development substrate.

This is where /root begins: not at programming, not at architecture, not at AI infrastructure, but at the machine you’ll write code on for the next five years. Linux is the substrate every later phase assumes. If the shell is unfamiliar, if ps and top are mysteries, if file permissions are a guessing game, everything later is built on shaky ground.

Phase 1 isn’t kernel internals; that’s Arc 3 territory. This is Linux as a developer uses it: shell fluency, the file system as a navigable space, processes as units of work you can inspect and control, permissions as the security model you live inside, and package management as how you install the rest of your toolchain. By phase end you can sit at any Linux box and operate it without notes.

Prerequisites

• A Linux environment available: Ubuntu/Debian on a laptop, a Linux VM on your machine, or a small mini-PC. Cloud Linux (a single small EC2/GCE instance) works for parts but local is preferable.
• Comfort opening a terminal. If cd and ls are genuinely new, spend 2-3 days on a beginner Unix primer before starting.
• You accept: you are not learning a tool called Linux. You are learning what a developer’s daily substrate is, with Linux as the canonical implementation.

Why this phase exists

Most engineers learn Linux by accident: they hit a problem (permission denied, file not found, command not in path), search Stack Overflow, copy-paste a fix, move on. That works for the first three years of a career and stops working forever after. Senior engineers reason about Linux from understanding, not from memorized commands, because they know the system underneath.

This phase installs that understanding at the developer’s altitude: enough to be fluent on the command line, navigate any file system, operate processes, install packages, and reason about permissions, but not enough to write a kernel module (that’s Arc 3). The bar is: a senior engineer at any company would recognize you as “fluent in Linux” within 5 minutes of watching you work.

The pattern-first frame

Every phase follows the same eight steps. See The Master Plan.

PROBLEM       What category of human need exists?
PRINCIPLES    The timeless patterns any solution must implement
TRADE-OFFS    The decisions every implementation makes
TOOLS         Current implementations (time-stamped — they age)
MASTERY       Pick one tool, go to operational depth
COMPARE       Re-implement the same problem in a second tool
OPERATE       Run it for real, take real incidents
CONTRIBUTE    Ship one fix upstream

1. PROBLEM

You’re a developer. You need a machine that runs your code, hosts your tools, and gives you a stable interface to the system. You want a shell to drive the machine, a file system to organize your work, processes you can inspect and control, package management so you don’t compile every dependency from source, and a permission model that prevents you from breaking things accidentally.

That’s the developer’s-OS problem. Linux is the canonical implementation. macOS is another (Darwin kernel + BSD userland). FreeBSD is another. Windows + WSL is a hybrid. Each implements the same primitives differently. The pattern (unix-style shell + file system + process model + permissions + packages) survives the OS choice; tools age.

2. PRINCIPLES

2.1 The shell as a programmable interface

The shell isn’t just a command runner: it’s a small programming language. Pipes compose commands. Variables hold state. Loops iterate. Functions abstract. Once you see it as a language, scripting stops feeling like cargo-culting and starts feeling like coding.

→ Pattern: shell-fluency

Investigate:

• What’s the difference between bash, zsh, fish, dash? Why does it matter?
• Walk through what happens when you press Enter on ls -la | grep "\.py$" | wc -l. How many processes? How does data flow between them?
• Why is “everything is a file” the unifying abstraction in Unix?

2.2 The file system as a namespace

The file system is a single hierarchical tree starting at /. Devices appear as files (/dev/sda1). Process state appears as files (/proc/PID/). Even network sockets are file descriptors. The “everything is a file” principle isn’t a slogan: it’s the mechanism that makes Unix’s tool composition work.

→ Pattern: file-system-as-namespace

Investigate:

• Walk the standard Linux file system hierarchy: /etc, /var, /usr, /home, /opt, /tmp. What goes where, and why?
• What’s the difference between a hard link and a symbolic link?
• How does cat /proc/$$/status work? There’s no disk behind /proc; what generates the bytes?

2.3 Processes as the unit of work

Every running program is a process. Processes have IDs, parents, file descriptors, memory, CPU time. The OS gives you tools (ps, top, htop, kill, nohup, &, jobs, fg, bg) to inspect and control them.

→ Pattern: processes-and-permissions

Investigate:

• What’s the parent-child relationship between processes? Why does every process have a parent?
• What happens when a parent dies before its child? What’s a zombie?
• What signals can you send to a process? What’s the difference between SIGTERM and SIGKILL?

2.4 Users, groups, permissions

Unix permissions are simple: every file has an owner, a group, and a permission triplet (rwxrwxrwx). Every process runs as a user. The intersection determines what’s allowed. Modern Linux extends this with capabilities, ACLs, and SELinux/AppArmor, but the base model is the same.

Investigate:

• Read the output of ls -la. What does every column mean?
• Why does sudo work the way it does? What’s /etc/sudoers?
• What’s setuid, and why is it both useful (/usr/bin/passwd) and dangerous?

2.5 Package management

Modern distros ship with package managers (apt, dnf, pacman, apk, brew). They handle dependency resolution, versioning, install/uninstall, security updates. They’re how you stop building every dependency from source.

Investigate:

• What does apt-get install nginx actually do? Walk through the steps.
• What’s the difference between binary packages and source packages?
• Why are language-specific package managers (pip, cargo, npm) layered on top of system packages?

2.6 The development environment as a discipline

A development environment is the configured state of your machine: shell config, editor, version manager (for Python and Go), credentials, dotfiles, history. Senior engineers version-control this: dotfiles repos, declarative configs (Nix, devbox), or just careful documentation.

Investigate:

• What’s in your ~/.zshrc or ~/.bashrc? Walk through every line.
• Why is nvm/pyenv/asdf/mise useful? What pain does it solve?
• What’s a dotfiles repo, and why do experienced engineers maintain one?

3. TRADE-OFFS

4. TOOLS (as of 2026-06)

Distributions

• Ubuntu 24.04 LTS: friendly default
• Debian 12: stability-first
• Fedora 40: fresher packages
• NixOS: declarative; try at end of phase if curious

Core CLI

• bash or zsh: shell
• ls, cd, pwd, cat, less, grep, find, awk, sed, cut, sort, uniq, wc, head, tail: the core toolkit
• ps, top, htop, kill, nohup, tmux: process management
• apt/dnf/brew: package management
• man, tldr: documentation

Modern alternatives (worth trying)

• ripgrep (rg): faster grep
• fd: faster find
• bat: cat with syntax highlighting
• eza (formerly exa): modern ls
• fzf: fuzzy finder

Reading

• “The Linux Command Line” (Shotts): free online, the canonical intro
• “Effective Shell” (Hewitt): free online, modern shell patterns
• man 7 bash: the bash reference
• Linux Standard Base + Filesystem Hierarchy Standard docs

5. MASTERY: A hardened dev environment

5.1 The deliverable

By phase end, you have:

• A Linux environment you can SSH into and operate
• A dotfiles repo on GitHub with shell config, editor config, git config
• A terminal multiplexer (tmux) configured and used daily
• A version manager for Python and Go installed (mise recommended; pyenv + gvm are alternatives)
• A shell script that bootstraps a fresh Linux machine to your configured dev environment

5.2 Operational depth checklist

[ ] Walk through every file in $HOME for one of your processes (yourself); know what each represents
[ ] Read `man 1 bash`: at least skim the SHELL GRAMMAR section
[ ] Write a shell function that takes arguments, has local variables, and returns a value
[ ] Compose a 4-stage pipeline using pipes (e.g., logs → grep → awk → sort | uniq -c | sort -rn | head)
[ ] Use `find ... -exec` to do something useful (rename, hash, archive)
[ ] Set up SSH keys correctly: ed25519 keys, agent forwarding, ~/.ssh/config with host aliases
[ ] Configure a tmux session with multiple windows + panes; survive a disconnect via tmux attach
[ ] Set up your dotfiles repo + bootstrap script; verify by setting up a fresh VM from it
[ ] Use `ps aux | grep` and `pgrep` to find a running process; kill it with the right signal
[ ] Set up a cron job that emails you on completion (or via a webhook)
[ ] Read 3 entries from `/proc/$$/` (your shell's process directory) and explain what they contain
[ ] Inspect a directory's permissions with `stat`; change them with `chmod` and `chown` and reason about the consequences

5.3 chronicle starts here

chronicle/runbooks/linux-dev-environment/ gets its first 3-5 entries this phase:

• “Set up a fresh Linux dev environment”
• “SSH key management + ssh-agent troubleshooting”
• “Recover from a corrupted .zshrc or .bashrc”
• “Diagnose ‘command not found’ (PATH issues)”

Each runbook follows meta/runbook-template.md. The discipline of writing runbooks for your own development environment is what trains the muscle for writing them for production systems later.

6. COMPARE: macOS or FreeBSD

Spend one week on a different Unix:

• macOS: different default shell (zsh historically, now defaulting), different package manager (brew), different file system (APFS, case-insensitive by default). Most of the muscle transfers; the gaps are interesting.
• FreeBSD 14: Linux’s older Unix cousin. ports instead of apt, pf instead of iptables, slightly different ps flags. The pattern is identical; the syntax differs.

Write a 400-word reflection in chronicle/: what’s the same? what’s different? what’s the underlying principle?

7. OPERATE

• 3-5 runbooks in chronicle/runbooks/linux-dev-environment/
• 1+ ADR (e.g., “Why zsh over bash for the dev environment,” or “Why mise over pyenv+gvm”)
• Weekly log every Sunday: by phase end you should have 5-7 entries

8. CONTRIBUTE

Approachable targets:

• man-pages project: typos, examples, clarifications
• tldr (the simplified man-pages project): add or improve an entry
• A dotfiles project on GitHub: submit a small improvement
• Your favorite CLI tool’s docs: fix one thing

This phase is the warm-up for upstream contribution. You’ll attempt your first merged PR in a later phase.

What ships from this phase

• Hardened dev environment: dotfiles repo public on GitHub, bootstrap script working
• chronicle seeded with its first runbooks (private repo)
• Linux fluency at the developer’s altitude: operational, not academic

No OSS project ships this phase. That starts Phase 2.

Learning loop cadence

Week 1     PROBLEM + PRINCIPLES 2.1-2.2 (shell + file system)
           Start dotfiles repo

Week 2     PRINCIPLES 2.3-2.4 (processes + permissions)
           First operational depth checks

Week 3-4   PRINCIPLES 2.5-2.6 (packages + dev environment)
           Bootstrap script working; tmux + version manager configured

Week 5     MASTERY: full operational checklist
           chronicle runbooks

Week 6     COMPARE: macOS or FreeBSD reflection
           OPERATE + CONTRIBUTE attempt
           Exit Test

Validation criteria

[ ] Dotfiles repo public on GitHub
[ ] Bootstrap script works on a fresh VM
[ ] tmux + version manager + ssh config operational
[ ] All 12 operational depth checks passed
[ ] macOS/FreeBSD compare reflection written (400 words)
[ ] 3-5 runbooks in chronicle
[ ] 1+ ADR
[ ] 5-7 weekly log entries
[ ] Pattern entries deepened STUB → OUTLINE:
    - shell-fluency
    - file-system-as-namespace
    - processes-and-permissions
[ ] Exit Test passed

Exit Test

Time: 2.5 hours.

Part 1: Build (60 min)

Given a fresh Linux VM, run your bootstrap script. After 30 minutes, the environment should be fully usable: shell configured, version managers installed, Python and Go available, tmux running, your editor configured.

Part 2: Diagnose (60 min)

A scenario from the Phase 1 catalog (e.g., “this process is using 100% CPU; identify what it is, why, and stop it gracefully”; or “this user can’t cd into a directory they should have access to; diagnose the permission issue end-to-end”).

Part 3: Articulate (30 min)

~600 words: “Walk through what happens when I type ls -la /etc/passwd | wc -l and press Enter. From the shell’s parsing to the resulting bytes on screen. Cover process creation, pipes, file system access, and the rendering layer.”

Anti-patterns

Patterns touched this phase

• shell-fluency: first OUTLINE
• file-system-as-namespace: first OUTLINE
• processes-and-permissions: first OUTLINE

→ Next: Phase 2: Programming Foundations I, Python