{
  "schemaVersion": 1,
  "disclaimer": "Educational only. Not a shell parser or safety verdict.",
  "commands": [
    {
      "slug": "pwd",
      "title": "Find your bearings",
      "description": "Print the current working directory. Relative paths in later commands start here.",
      "risk": "Read-oriented",
      "example": "pwd",
      "caution": "The path can reveal a username or private project name. Shell built-ins and external versions can differ.",
      "check": "Check where you are before any command that changes files.",
      "sources": [
        {
          "title": "GNU Coreutils reference",
          "url": "https://www.gnu.org/software/coreutils/manual/coreutils.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "ls",
      "title": "See what is here",
      "description": "List files and directories. The -a flag includes hidden entries; -l adds details.",
      "risk": "Read-oriented",
      "example": "ls -la",
      "caution": "Filenames and permissions may be private. Output formatting is not a reliable interface for scripts.",
      "check": "Inspect the directory and use explicit paths for later actions.",
      "sources": [
        {
          "title": "GNU Coreutils reference",
          "url": "https://www.gnu.org/software/coreutils/manual/coreutils.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "cd",
      "title": "Move through folders",
      "description": "Change the working directory of the current shell. cd .. moves to the parent directory.",
      "risk": "Shell state",
      "example": "cd ./project",
      "caution": "A failed cd does not stop a later command separated by a semicolon. The working directory determines relative targets.",
      "check": "Use cd ./project && pwd to continue only when the directory change succeeds.",
      "sources": [
        {
          "title": "Bash reference",
          "url": "https://www.gnu.org/software/bash/manual/bash.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "cat",
      "title": "Read a small file",
      "description": "Write file contents to standard output. Multiple filenames are read in order.",
      "risk": "Read-oriented",
      "example": "cat README.md",
      "caution": "Contents may include secrets. A large or binary file can overwhelm a terminal. Redirection around cat can still overwrite files.",
      "check": "Check the filename and avoid printing credential files.",
      "sources": [
        {
          "title": "GNU Coreutils reference",
          "url": "https://www.gnu.org/software/coreutils/manual/coreutils.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "head",
      "title": "Peek at the beginning",
      "description": "Print the first lines of a file. -n 20 asks for twenty lines.",
      "risk": "Read-oriented",
      "example": "head -n 20 README.md",
      "caution": "A preview can still expose secrets. It does not prove the remainder of a file is harmless.",
      "check": "Use a small preview when you only need the beginning.",
      "sources": [
        {
          "title": "GNU Coreutils reference",
          "url": "https://www.gnu.org/software/coreutils/manual/coreutils.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "tail",
      "title": "Watch the end",
      "description": "Print the last lines. -f keeps watching as a file grows.",
      "risk": "Read-oriented",
      "example": "tail -n 20 app.log",
      "caution": "Logs may contain personal data or tokens. Following a file keeps a process running until interrupted.",
      "check": "Check what the log contains before sharing output.",
      "sources": [
        {
          "title": "GNU Coreutils reference",
          "url": "https://www.gnu.org/software/coreutils/manual/coreutils.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "grep",
      "title": "Find matching lines",
      "description": "Search text for a pattern and print matching lines. -n includes line numbers.",
      "risk": "Read-oriented",
      "example": "grep -n \"error\" app.log",
      "caution": "Patterns have their own syntax. A nonzero exit status can mean no matches, not a broken command. Recursive searches may expose private content.",
      "check": "Quote patterns and scope the files you search.",
      "sources": [
        {
          "title": "grep reference",
          "url": "https://www.gnu.org/software/grep/manual/grep.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "find",
      "title": "Locate files precisely",
      "description": "Walk a directory tree and select entries using tests such as -name.",
      "risk": "Context-sensitive",
      "example": "find ./src -name \"*.js\"",
      "caution": "find can also execute commands with -exec or delete files with -delete. Order and quoting matter.",
      "check": "Review the matching paths before introducing any action.",
      "sources": [
        {
          "title": "find reference",
          "url": "https://www.gnu.org/software/findutils/manual/html_mono/find.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "mkdir",
      "title": "Make a new directory",
      "description": "Create a directory. -p creates missing parent directories as needed.",
      "risk": "Changes files",
      "example": "mkdir ./drafts",
      "caution": "Creates filesystem entries and may fail because of permissions or existing files. -p does not prove the chosen location is correct.",
      "check": "Confirm the parent directory and intended name.",
      "sources": [
        {
          "title": "GNU Coreutils reference",
          "url": "https://www.gnu.org/software/coreutils/manual/coreutils.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "cp",
      "title": "Copy with care",
      "description": "Copy a file to a destination. Recursive options copy directory trees.",
      "risk": "Changes files",
      "example": "cp ./notes.txt ./notes-backup.txt",
      "caution": "An existing destination may be overwritten. Symlinks, permissions and recursive behavior vary by options and platform.",
      "check": "Check the destination; consider an interactive prompt with -i where supported.",
      "sources": [
        {
          "title": "GNU Coreutils reference",
          "url": "https://www.gnu.org/software/coreutils/manual/coreutils.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "mv",
      "title": "Move or rename",
      "description": "Move a file or rename it within a directory.",
      "risk": "Changes files",
      "example": "mv ./draft.txt ./final.txt",
      "caution": "An existing destination can be replaced. Moving across filesystems may involve copying and removing the original.",
      "check": "Check both paths and whether the destination already exists.",
      "sources": [
        {
          "title": "GNU Coreutils reference",
          "url": "https://www.gnu.org/software/coreutils/manual/coreutils.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "rm",
      "title": "Remove files",
      "description": "Remove named filesystem entries. -r descends into directories; -f suppresses some prompts and errors.",
      "risk": "Destructive",
      "example": "rm ./scratch.txt",
      "caution": "Usually bypasses the desktop Trash. Wildcards and unexpected variables can greatly expand the target; -rf is not a safety check.",
      "check": "Confirm the exact expanded targets and a usable backup before removal.",
      "sources": [
        {
          "title": "GNU Coreutils reference",
          "url": "https://www.gnu.org/software/coreutils/manual/coreutils.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "chmod",
      "title": "Change permissions",
      "description": "Change who can read, write or execute a file.",
      "risk": "Permissions",
      "example": "chmod u+x ./script.sh",
      "caution": "Executable permission does not make a script trustworthy. Broad or recursive permissions can expose sensitive data or weaken security.",
      "check": "Read the script first and grant the smallest necessary permission.",
      "sources": [
        {
          "title": "GNU Coreutils reference",
          "url": "https://www.gnu.org/software/coreutils/manual/coreutils.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "sudo",
      "title": "Use elevated authority",
      "description": "Run a permitted command as another user, commonly root, according to local policy.",
      "risk": "Elevated access",
      "example": "sudo -l",
      "caution": "Greater privileges amplify mistakes. It is not a fix for an unexplained permission error, and local policy can vary.",
      "check": "Ask why elevation is needed and what exact resources it affects.",
      "sources": [
        {
          "title": "sudo manual",
          "url": "https://www.sudo.ws/docs/man/sudo.man/"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "git",
      "title": "Understand repository changes",
      "description": "Track and inspect versioned work. git status summarizes the working tree and staging area.",
      "risk": "Context-sensitive",
      "example": "git status --short",
      "caution": "status is observational, but reset --hard, clean and restore can discard work; push sends data to a remote. A repository may contain configured hooks and helpers.",
      "check": "Inspect status and diff, then distinguish local changes from remote publication.",
      "sources": [
        {
          "title": "git reference",
          "url": "https://git-scm.com/docs"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "curl",
      "title": "Talk to a URL",
      "description": "Transfer data to or from a server. -I asks for response headers instead of the response body.",
      "risk": "Network",
      "example": "curl -I https://example.com",
      "caution": "Requests disclose network information to the destination. Flags can upload files, include credentials or write output locally. Piping a download into a shell executes remote code.",
      "check": "Check the hostname, method, payload and output destination.",
      "sources": [
        {
          "title": "curl reference",
          "url": "https://curl.se/docs/manpage.html"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "npm",
      "title": "Manage JavaScript packages",
      "description": "Install dependencies and run scripts defined by a JavaScript project.",
      "risk": "Executes code",
      "example": "npm install",
      "caution": "Installations can run package lifecycle scripts and change package or lock files. A familiar package name does not verify its publisher or contents.",
      "check": "Review package.json, the lockfile, registry and lifecycle behavior before installing.",
      "sources": [
        {
          "title": "npm reference",
          "url": "https://docs.npmjs.com/cli/v11/commands/npm-install"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    },
    {
      "slug": "ssh",
      "title": "Connect to another machine",
      "description": "Open an encrypted connection to a remote host, often for an interactive shell.",
      "risk": "Remote access",
      "example": "ssh user@host.example",
      "caution": "Commands run on the remote machine. Host-key warnings matter; forwarding and authentication options change access and exposure.",
      "check": "Confirm the hostname, identity and host key before connecting.",
      "sources": [
        {
          "title": "ssh reference",
          "url": "https://man.openbsd.org/ssh"
        }
      ],
      "updated": "2026-11-07",
      "platform": "Examples target common Unix-like shells. GNU, BSD/macOS and shell built-ins may differ."
    }
  ],
  "guides": [
    {
      "slug": "read-a-command",
      "title": "Read a command before you run it",
      "level": "Start here",
      "minutes": 5,
      "description": "A calm, repeatable way to turn a wall of terminal text into a decision.",
      "sections": [
        [
          "Start with the program",
          "In grep -n \"error\" app.log, grep is the program, -n is an option, \"error\" is the search pattern and app.log is the input. Quotes group characters and control how the shell interprets them."
        ],
        [
          "Find the target",
          "Ask which files, directory, server or account this touches. Relative paths depend on the current working directory. A command copied from an agent can be correct for a different directory and wrong for yours."
        ],
        [
          "Read the whole line",
          "The shell processes operators, expansions and redirections. A familiar first word is not enough: cat notes.txt > backup.txt can replace backup.txt."
        ],
        [
          "Ask the agent for evidence",
          "Ask: What will change? Which exact paths or remote destinations are involved? What permissions does this need? How do we undo it? Can we inspect the targets first? A confident explanation is not a verification."
        ]
      ],
      "updated": "2026-11-07",
      "sources": [
        {
          "title": "GNU Bash manual",
          "url": "https://www.gnu.org/software/bash/manual/bash.html"
        },
        {
          "title": "POSIX shell command language",
          "url": "https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html"
        }
      ]
    },
    {
      "slug": "pipes-and-redirection",
      "title": "Pipes are plumbing, not magic",
      "level": "Build confidence",
      "minutes": 6,
      "description": "Follow data through pipes, files, and error streams without losing the plot.",
      "sections": [
        [
          "Three streams",
          "Processes commonly read standard input (0), write ordinary output to standard output (1) and write diagnostics to standard error (2). A pipe connects stdout to the next process’s stdin."
        ],
        [
          "Trace a pipeline",
          "cat app.log | grep \"error\" | head -n 5 reads a file, filters matching lines and shows the first five. You could avoid cat with grep \"error\" app.log | head -n 5. Neither example writes a file, but log contents may be sensitive."
        ],
        [
          "A file is not a pipe",
          "> writes to a file and normally truncates it. >> appends. Never assume a command failed before the shell opened its redirected output file. Avoid reading and redirecting into the same file."
        ],
        [
          "Know the exit status",
          "In Bash, a pipeline normally reports the status of its final command. With pipefail enabled, a nonzero status from an earlier stage can affect the result. Shell settings and programs differ; inspect the whole pipeline."
        ]
      ],
      "updated": "2026-11-07",
      "sources": [
        {
          "title": "GNU Bash manual",
          "url": "https://www.gnu.org/software/bash/manual/bash.html"
        },
        {
          "title": "POSIX shell command language",
          "url": "https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html"
        }
      ]
    },
    {
      "slug": "risk-is-context",
      "title": "“Safe” depends on the situation",
      "level": "Start here",
      "minutes": 4,
      "description": "Learn the questions that matter more than a green badge.",
      "sections": [
        [
          "Read-only is not private",
          "Printing a token, searching a private directory or sending a request to a server may expose information even without changing local files. Read-oriented is a description, not a guarantee."
        ],
        [
          "Scope changes consequences",
          "Removing one scratch file and recursively removing a project use the same program. Wildcards, variables, symlinks, permissions and the current directory determine the actual scope."
        ],
        [
          "Preview, then verify",
          "List the intended paths before making changes. Confirm backups for destructive operations. Dry-run flags help only when the exact tool and operation support them; they are not universal."
        ],
        [
          "Pause at boundaries",
          "Take extra care when commands delete data, use sudo, execute downloads, install packages, change permissions or transmit files. Ask for a smaller, observable step when the intent is unclear."
        ]
      ],
      "updated": "2026-11-07",
      "sources": [
        {
          "title": "GNU Bash manual",
          "url": "https://www.gnu.org/software/bash/manual/bash.html"
        },
        {
          "title": "POSIX shell command language",
          "url": "https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html"
        }
      ]
    },
    {
      "slug": "agent-terminal-checklist",
      "title": "A better conversation with your agent",
      "level": "Build confidence",
      "minutes": 5,
      "description": "Keep the speed of an agent without giving up understanding or control.",
      "sections": [
        [
          "Ask for a plan in plain language",
          "Before a consequential command, ask the agent to identify the purpose, exact targets and expected changes. Ask it to separate inspection from mutation and local work from publication."
        ],
        [
          "Keep secrets out of transcripts",
          "Do not paste API keys, passwords, access tokens or private file contents into an explainer. Replace secrets with placeholders. Terminal output and command histories can preserve sensitive values."
        ],
        [
          "Verify the outcome",
          "A zero exit code alone does not prove the intended result. Check changed files, tests, destination records or remote state. Distinguish attempted, completed and verified actions."
        ],
        [
          "Make approval specific",
          "An approval to inspect is not approval to delete, publish or install. Name the exact action and scope. If the destination, cost, permissions or affected data changes, reconsider the decision."
        ]
      ],
      "updated": "2026-11-07",
      "sources": [
        {
          "title": "GNU Bash manual",
          "url": "https://www.gnu.org/software/bash/manual/bash.html"
        },
        {
          "title": "POSIX shell command language",
          "url": "https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html"
        }
      ]
    },
    {
      "slug": "shell-power-tools",
      "title": "Small syntax, big consequences",
      "level": "Go deeper",
      "minutes": 8,
      "description": "Understand quoting, exit codes, expansion and the edges of simple explanations.",
      "sections": [
        [
          "Quote deliberately",
          "Single quotes in common POSIX-like shells preserve literal characters. Double quotes still allow parameter expansion and command substitution. Unquoted values can split into words and expand patterns. Shell dialects differ."
        ],
        [
          "Beware hidden execution",
          "$(...) and backticks execute nested commands. Aliases, shell functions, wrappers and PATH can change which program runs. This site does not resolve your machine’s shell configuration."
        ],
        [
          "Sequence with intent",
          "a && b means b runs when a succeeds. a ; b runs b regardless of a’s status. a || b runs b on failure. Mixing these is not a general substitute for an explicit if statement."
        ],
        [
          "Use the manual for your version",
          "Check the locally installed tool’s help and manual. GNU/Linux examples can differ from BSD/macOS commands. Flags can evolve; verify the version, environment and target before running unfamiliar syntax."
        ]
      ],
      "updated": "2026-11-07",
      "sources": [
        {
          "title": "GNU Bash manual",
          "url": "https://www.gnu.org/software/bash/manual/bash.html"
        },
        {
          "title": "POSIX shell command language",
          "url": "https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html"
        }
      ]
    }
  ],
  "operators": [
    {
      "symbol": "|",
      "title": "Pass output along",
      "description": "Connect standard output of the left command to standard input of the right. Standard error is separate unless redirected. A pipeline can still contain destructive commands."
    },
    {
      "symbol": "&&",
      "title": "Continue on success",
      "description": "Run the right command only if the left command exits with status zero. Zero means success by that program’s convention, not that the action was safe."
    },
    {
      "symbol": "||",
      "title": "Continue on failure",
      "description": "Run the right command when the left exits nonzero. A nonzero status can have a special meaning, such as grep finding no matches."
    },
    {
      "symbol": ";",
      "title": "Run the next command",
      "description": "Separate commands without requiring the previous command to succeed."
    },
    {
      "symbol": ">",
      "title": "Replace an output file",
      "description": "Redirect standard output to a file. The shell can create or truncate the file before the command runs."
    },
    {
      "symbol": ">>",
      "title": "Append to an output file",
      "description": "Redirect standard output to the end of a file, creating it if needed. This still changes the file."
    },
    {
      "symbol": "2>",
      "title": "Redirect errors",
      "description": "Redirect file descriptor 2, standard error, to a file. That file can be created or truncated."
    },
    {
      "symbol": "$()",
      "title": "Substitute command output",
      "description": "Run the command inside parentheses and substitute its output. Quoting and word splitting affect what happens next."
    },
    {
      "symbol": "*",
      "title": "Expand a pattern",
      "description": "The shell can expand an unquoted wildcard into matching filenames before the program starts. Behavior for no matches varies by shell settings."
    }
  ]
}