The File System

Status: drafted · Time: 20 min · Audience: new-builder Outcome: Navigate folders, read paths, recognize extensions, and know where you are before running a command.

At the end of this module you can answer the most important beginner question in computing: where am I? You can read a path, move between folders, tell a file from a folder, recognize an extension, and avoid running commands in the wrong place.

The file system is the first context layer. Claude Code can only help well if both of you are talking about the same files.

---

If you’re short on time

• A folder contains files and other folders. A path is the address to one place in that tree.
• Before running any command, run pwd and ls. pwd tells you where you are; ls tells you what is there.
• Extensions matter: .md is Markdown, .js is JavaScript, .json is structured data, .yml or .yaml is configuration.

---

The mental model

Think of your laptop as a building.

Folders are rooms. Files are documents inside rooms. A path is the written direction from the entrance to one room or one document.

home
└── work
    └── hello-razorpay
        ├── README.md
        ├── package.json
        └── src
            └── index.js

In that tree:

• home is a folder.
• work is a folder inside home.
• hello-razorpay is a project folder.
• README.md is a Markdown file.
• src/index.js means “the file named index.js inside the folder named src.”

When someone says “open the repo root,” they mean the top folder of the project, the folder where the important project files usually live.

---

Worked example

Open Terminal and run:

pwd

You will see a path. It may look different on every laptop. That is fine. The output means “this is the folder Terminal is currently standing in.”

Now list what is in that folder:

ls

Move into a work folder if you have one:

cd work
pwd
ls

Move one level up:

cd ..
pwd

Create a practice folder:

mkdir white-belt-practice
cd white-belt-practice
touch notes.md
ls

You just made a folder and a file. Open notes.md in your editor if you have one configured:

code notes.md

If code is not available, do not debug it yet. That belongs in setup. You can still read the file from Terminal:

cat notes.md

It is empty, so cat prints nothing. That is a valid result.

Now clean up the practice folder only if you are certain you are inside it:

pwd
ls

If pwd ends with white-belt-practice, you are in the right place. Leave cleanup for later if you are unsure. White Belt rewards caution.

---

Files you will meet in this playbook

Extension	What it usually is	Beginner instinct
.md	Markdown documentation	Safe to read and usually safe to edit.
.json	Structured configuration or data	Edit carefully; commas matter.
.yml / .yaml	Configuration	Spaces matter; do not casually re-indent.
.js / .ts	JavaScript / TypeScript code	Read with Claude before editing.
.sh	Shell script	Never run blindly; inspect first.
.lock	Dependency lockfile	Usually generated by tools.

You do not need to memorize this table. You need to pause when a file is not obviously a document.

---

Common failure modes

“I ran a command and it said file not found.” You are probably in the wrong folder. Run pwd and ls, then move to the project folder.

“I edited a file but nothing changed.” You may have edited a copy, not the repo file. Ask Claude Code to show the file path it changed, then compare it with pwd.

“There are too many files.” Use the repo README first. Then ask: “Which folders matter for this tiny task?” Do not explore everything manually.

“I cannot tell whether something is a folder or file.” Run ls -la. Folders start with d in the long listing. Your editor also shows folder icons.

“I am scared of deleting something.” Good. Do not use deletion commands in White Belt unless a module explicitly tells you to and you can explain the folder you are in.

---

GREEN / YELLOW / RED self-check

You are GREEN if you can:

• run pwd and explain the path in plain English;
• run ls and identify at least one file and one folder;
• move into a folder and back out using cd folder-name and cd ..;
• identify a Markdown file by extension.

You are YELLOW if:

• you can follow the commands but cannot yet explain the output;
• you got lost in a folder tree and recovered only with help;
• your editor opens but you cannot tell which folder it opened.

You are RED if:

• Terminal will not open;
• basic commands fail in surprising ways;
• you cannot find your working folder after ten minutes.

For YELLOW or RED, stop here and use Appendix B’s environment setup routing before continuing.

---

What you can say after this module

“I can tell where Terminal is standing and which files are in front of me.”

That sentence is enough to unlock Terminal fluency.

---

Previous: White Belt README - Next: W.2 Terminal fluency