# Norm Mode Glossary — Technical Terms for Lawyers

This glossary defines common programming and terminal terms you might encounter while using Norm Mode.

---

## Environment & Setup

### Virtual Environment
**What it is:** An isolated workspace for Python projects

**Why it matters:** Keeps project dependencies separate from your system Python. Like having separate filing cabinets for different cases — changes in one don't affect others.

**Example:** When you create a virtual environment with `python3 -m venv venv`, you're creating a folder called `venv` that acts as an isolated Python installation.

---

### Environment Variable
**What it is:** A setting that programs can read to configure their behavior

**Why it matters:** Used to store configuration like API keys or file paths without hardcoding them into your code.

**Example:** `NORM_MODE_PROMPTS="/path/to/prompts"` tells the norm-claude CLI where to find prompt files.

---

### PATH
**What it is:** A list of directories where your computer looks for executable programs

**Why it matters:** Adding a script to your PATH lets you run it from any directory by just typing its name.

**Example:** If `norm-claude` is in your PATH, you can type `norm-claude` anywhere instead of `/usr/local/bin/norm-claude`.

---

## Package Management

### pip
**What it is:** Python's package installer (think: App Store for Python libraries)

**Why it matters:** Used to install third-party Python libraries your code depends on.

**Example:** `pip install pandas` downloads and installs the pandas library for data analysis.

**Risk level:** High — installs code from the internet

---

### npm
**What it is:** Node.js package manager (like pip, but for JavaScript)

**Why it matters:** Used to install JavaScript libraries and tools.

**Example:** `npm install express` installs the Express web framework.

**Risk level:** High — installs code from the internet

---

### brew (Homebrew)
**What it is:** macOS package manager for installing software

**Why it matters:** Easy way to install command-line tools and applications on Mac.

**Example:** `brew install python3` installs Python 3 on your Mac.

**Risk level:** High — installs software system-wide

---

### requirements.txt
**What it is:** A file listing all Python packages your project needs

**Why it matters:** Documents dependencies so others (or you later) can recreate the same environment.

**Example:**
```
pandas==2.1.0
requests==2.31.0
```

---

### package.json
**What it is:** A file listing all Node.js packages your project needs (JavaScript equivalent of requirements.txt)

**Why it matters:** Describes your project and its dependencies.

---

## Version Control (Git)

### Git
**What it is:** A version control system that tracks changes to files over time

**Why it matters:** Like Track Changes in Word, but for code. Lets you see history, undo changes, and collaborate.

**Risk levels:**
- Low: Viewing history (`git log`, `git status`)
- Medium: Creating commits, switching branches
- High: Rewriting history (`git reset`, `git rebase`)

---

### Repository (Repo)
**What it is:** A folder tracked by git, containing your project files and their history

**Why it matters:** The project "home base" where all versions are stored.

**Example:** `~/Documents/my-project/` can be a git repository.

---

### Commit
**What it is:** A snapshot of your project at a specific point in time

**Why it matters:** Like saving a "version" of your document. You can always go back to this point later.

**Example:** After editing 3 files, you run `git commit` to save a snapshot with a description like "Fixed bug in contract parser".

---

### Branch
**What it is:** A separate line of development in git

**Why it matters:** Like working on a draft copy without affecting the main document. You can experiment safely.

**Example:** Create a branch called `feature-new-search` to add a new feature without affecting the working `main` branch.

---

### Push
**What it is:** Uploading your local git commits to a remote server (like GitHub)

**Why it matters:** Backs up your work and shares it with others.

**Risk level:** Medium — sends your code to the internet (make sure no secrets are included)

---

### Pull
**What it is:** Downloading changes from a remote git repository to your local machine

**Why it matters:** Gets updates others have made.

**Risk level:** Low-Medium — brings in changes (could cause conflicts)

---

## Files & Directories

### Directory
**What it is:** A folder

**Why it matters:** Same as "folder" in Finder/Explorer. Programmers often say "directory" instead.

**Example:** `~/Documents/norm-mode/` is a directory path.

---

### Path (File Path)
**What it is:** The location of a file or folder on your computer

**Why it matters:** Tells programs where to find files.

**Types:**
- **Absolute path:** Full path from root, e.g., `/Users/yourname/Documents/file.txt`
- **Relative path:** Path from current location, e.g., `../other-folder/file.txt`

---

### Hidden File
**What it is:** A file whose name starts with a dot (`.`)

**Why it matters:** Not shown in Finder by default. Often used for configuration files.

**Examples:**
- `.env` (environment variables)
- `.gitignore` (tells git which files to ignore)
- `.zshrc` (shell configuration)

**How to view:** In Finder, press `Cmd + Shift + .` (dot)

---

### Script
**What it is:** A file containing code that performs a task when run

**Why it matters:** Automates repetitive work.

**Example:** `analyze_contracts.py` is a Python script that processes contract PDFs.

**Risk level:** Medium — executes code (could modify files or make network requests)

---

## Terminal & Shell

### Terminal
**What it is:** A text-based interface for interacting with your computer

**Why it matters:** Where you run commands instead of clicking buttons.

**Also called:** Command line, shell, console

---

### Shell
**What it is:** The program that interprets commands you type in the terminal

**Common shells:**
- **bash** (older default on Mac/Linux)
- **zsh** (current default on Mac)
- **cmd/PowerShell** (Windows)

---

### Command
**What it is:** An instruction you type into the terminal

**Why it matters:** How you tell the computer to do things via text.

**Example:** `ls -la` (command to list files in detail)

---

### Flag / Option
**What it is:** Additional parameters that modify how a command works (usually start with `-` or `--`)

**Example:** In `ls -la`, `-l` and `-a` are flags that mean "long format" and "show all (including hidden)"

---

## Programming Concepts

### Library / Package
**What it is:** Reusable code written by someone else that you can import into your project

**Why it matters:** Saves time by not reinventing the wheel.

**Example:** `pandas` is a library for working with data tables (like Excel, but in Python)

---

### Dependency
**What it is:** A library or package your code relies on

**Why it matters:** Your code won't run without its dependencies installed.

**Example:** If your script imports pandas, pandas is a dependency.

---

### Import / Include
**What it is:** Bringing code from a library into your script so you can use it

**Example:**
```python
import pandas as pd
```
This imports the pandas library and gives it the shorthand name `pd`.

---

### Function
**What it is:** A reusable block of code that performs a specific task

**Why it matters:** Like a mini-program within your program.

**Example:**
```python
def greet(name):
    return f"Hello, {name}!"
```
This function takes a name and returns a greeting.

---

### Variable
**What it is:** A named container that stores a value

**Example:**
```python
contract_count = 42
```
`contract_count` is a variable storing the number 42.

---

### API (Application Programming Interface)
**What it is:** A way for programs to talk to each other

**Why it matters:** Lets your code interact with external services (like OpenAI's API to use GPT models).

**Example:** `openai.ChatCompletion.create()` sends a request to OpenAI's API to generate text.

---

### JSON
**What it is:** A text format for storing structured data (like a simplified version of XML)

**Why it matters:** Commonly used for configuration files and exchanging data between programs.

**Example:**
```json
{
  "name": "Contract Analyzer",
  "version": "1.0",
  "dependencies": ["pandas", "openai"]
}
```

---

### YAML
**What it is:** Another text format for structured data (more human-readable than JSON)

**Why it matters:** Often used for configuration files.

**Example:**
```yaml
name: Contract Analyzer
version: 1.0
dependencies:
  - pandas
  - openai
```

---

## Errors & Debugging

### Error / Exception
**What it is:** When something goes wrong and the program stops

**Why it matters:** Errors are normal! They tell you what to fix.

**Common types:**
- **SyntaxError:** Code has a typo or grammar mistake
- **ImportError:** Can't find a library
- **FileNotFoundError:** Can't find a file
- **ValueError:** Wrong type of value (e.g., trying to convert "abc" to a number)

---

### Stack Trace (Traceback)
**What it is:** The error message showing where the error occurred and the path that led to it

**Why it matters:** Tells you which file and line number caused the problem.

**Example:**
```
Traceback (most recent call last):
  File "analyze.py", line 15, in <module>
    result = int("abc")
ValueError: invalid literal for int() with base 10: 'abc'
```
This says: error on line 15 of analyze.py, trying to convert "abc" to an integer.

---

### Debug / Debugging
**What it is:** The process of finding and fixing errors

**Why it matters:** Normal part of development. Everyone debugs, even experts.

**Common tools:**
- Print statements (showing variable values)
- Debuggers (step through code line by line)
- Reading error messages carefully

---

## Configuration Files

### .env
**What it is:** A file storing environment variables (often secrets like API keys)

**Why it matters:** Keeps sensitive data out of your code.

**Risk level:** High — contains secrets; should NEVER be committed to git

**Example:**
```
OPENAI_API_KEY=sk-abc123...
DATABASE_URL=postgresql://...
```

---

### config.yaml / config.json
**What it is:** A file storing application settings

**Why it matters:** Lets you change behavior without modifying code.

**Risk level:** Medium-High — controls app behavior

---

### .gitignore
**What it is:** A file telling git which files to ignore (not track)

**Why it matters:** Prevents sensitive or unnecessary files from being committed.

**Example:**
```
.env
*.log
__pycache__/
```

---

## Testing

### Test
**What it is:** Code that checks if other code works correctly

**Why it matters:** Catches bugs before they affect users.

**Risk level:** Low — tests don't modify production data

---

### Unit Test
**What it is:** A test that checks a single function or small piece of code

**Example:** Test that `greet("Alice")` returns `"Hello, Alice!"`

---

## Advanced Terms

### Localhost
**What it is:** Your own computer when acting as a server

**Why it matters:** Used when testing web apps locally before deploying.

**Example:** `http://localhost:8000` is a website running on your computer.

---

### Port
**What it is:** A number identifying a specific service on a computer

**Why it matters:** Lets multiple services run on one computer without interfering.

**Example:** Web servers often use port 80 (HTTP) or 443 (HTTPS).

---

### Database
**What it is:** An organized collection of data

**Why it matters:** Stores information your program needs (users, contracts, etc.).

**Common types:**
- **SQLite:** Simple file-based database
- **PostgreSQL / MySQL:** Full-featured server databases

---

### Migration
**What it is:** A scripted change to a database structure (like adding a new table)

**Why it matters:** Tracks how your database schema evolves over time.

**Risk level:** High — can modify or delete data if not careful

---

## Need More?

If you encounter a term not listed here, type `/explain [term]` in your Norm Mode session, or just ask Claude to define it!
