docs(onboarding): add guides for Cursor and Claude Code tools (#3874)

Author: ComputelessComputer

apps/web/content/handbook/onboarding/0.getting-started.mdx

@@ -15,11 +15,36 @@ When you join, you'll get access to:
 - **Infisical** — Ask a team member for an invite. We use [Infisical](https://infisical.com) to manage environment variables and secrets for development.
 - **Hyprnote admin** — Sign in at `https://hyprnote.com/admin` with your authorized email for content management.
 
-### Dev Environment
+### Tools Setup
 
-We recommend [Cursor](https://cursor.com) if you don't have a specific IDE preference. Other tools we use: Zed, GitButler, Claude Code.
+Everyone at Hyprnote works from the same repo and ships through the same workflow. Whether you're an engineer, designer, or marketer — you'll need most of these tools. Each links to a setup guide that explains what it is, why we use it, and how to install it.
 
-[Cursor Visual Editor walkthrough](https://www.youtube.com/watch?v=XOtHjA8THCw)
+**Foundations (Everyone)**
+
+- [ ] [Homebrew](/handbook/onboarding/homebrew) — Mac package manager. You'll use this to install almost everything else.
+- [ ] [Warp](/handbook/onboarding/warp) — Our recommended terminal. This is where you run commands.
+- [ ] [Node.js & pnpm](/handbook/onboarding/node-and-pnpm) — JavaScript runtime and package manager. Required even if you never write code.
+- [ ] [GitButler](/handbook/onboarding/gitbutler) — Our git client. Visual interface instead of raw git commands.
+
+**Development Tools (Engineers + Technical Roles)**
+
+- [ ] [Cursor](/handbook/onboarding/cursor) — AI-powered code editor. Our primary IDE recommendation.
+- [ ] [Claude Code](/handbook/onboarding/claude-code) — AI coding assistant that runs in your terminal.
+- [ ] [Rust](https://rustup.rs) — Install via rustup. Required for building the desktop app.
+- [ ] [Taskfile](https://taskfile.dev/installation) — Task runner we use for dev commands.
+- [ ] [Docker](https://www.docker.com/products/docker-desktop/) — Required for local Supabase.
+
+**Content Tools (Marketers + Content)**
+
+- [ ] Cursor or any text editor — for editing MDX files
+- [ ] Git basics via GitButler — for pushing content changes
+- [ ] Admin access at `https://hyprnote.com/admin` — for media uploads and blog management
+
+Verify the basics are installed:
+
+```bash
+node --version && pnpm --version && git --version
+```
 
 ### Developer Documentation
 
@@ -30,8 +55,9 @@ We have dedicated [developer documentation](/docs/developers/setup) covering set
 - [ ] GitHub org access confirmed
 - [ ] Slack joined, introduced yourself
 - [ ] Infisical access confirmed
+- [ ] Tools installed (work through the list above)
 - [ ] Read the [developer documentation](/docs/developers/setup)
-- [ ] Dev environment set up (IDE installed, repo cloned, builds locally)
+- [ ] Dev environment set up (repo cloned, builds locally)
 - [ ] Read this handbook — seriously, all of it
 - [ ] Downloaded a [staging build](/handbook/onboarding/staging-builds) and opened Hyprnote
 

apps/web/content/handbook/onboarding/3.tooling-checklist.mdx

@@ -0,0 +1,19 @@
+---
+title: "Tool Setup Guides"
+section: "Onboarding"
+summary: "Step-by-step setup guides for every tool we use — written for all roles."
+---
+
+Each guide below explains what the tool is, why we use it, and how to install it. See the [Getting Started](/handbook/onboarding/getting-started) page for the full checklist.
+
+## Foundations
+
+- [Homebrew](/handbook/onboarding/homebrew) — Mac package manager
+- [Warp](/handbook/onboarding/warp) — Terminal
+- [Node.js & pnpm](/handbook/onboarding/node-and-pnpm) — JavaScript runtime and package manager
+- [GitButler](/handbook/onboarding/gitbutler) — Git client
+
+## Development
+
+- [Cursor](/handbook/onboarding/cursor) — Code editor
+- [Claude Code](/handbook/onboarding/claude-code) — AI coding assistant

apps/web/content/handbook/onboarding/4.homebrew.mdx

@@ -0,0 +1,46 @@
+---
+title: "Homebrew"
+section: "Onboarding"
+summary: "Install Homebrew — the Mac package manager that everything else depends on."
+---
+
+## What It Is
+
+[Homebrew](https://brew.sh) is a package manager for macOS. Think of it as an app store that runs in your terminal — you type a command, and it installs software for you. Almost every other tool in our stack is installed through Homebrew.
+
+## Install
+
+Open your terminal (press `Cmd + Space`, type "Terminal", hit Enter) and paste this:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+Follow the prompts. It will ask for your Mac password — that's normal.
+
+**Important:** After installation finishes, Homebrew will print a "Next steps" message with two commands to add Homebrew to your PATH. Run both of them. If you skip this, `brew` commands won't work.
+
+## Verify
+
+Close and reopen your terminal, then run:
+
+```bash
+brew --version
+```
+
+You should see something like `Homebrew 4.x.x`. If you get "command not found", you missed the PATH step above — scroll back in your terminal and run those two commands.
+
+## Basics
+
+```bash
+brew install <package>     # Install something
+brew update                # Update Homebrew itself
+brew upgrade               # Upgrade all installed packages
+brew list                  # See what's installed
+```
+
+You'll use `brew install` frequently during the rest of this setup.
+
+## Back to Checklist
+
+[Return to Tooling Checklist](/handbook/onboarding/tooling-checklist)

apps/web/content/handbook/onboarding/5.cursor.mdx

@@ -0,0 +1,67 @@
+---
+title: "Cursor"
+section: "Onboarding"
+summary: "Set up Cursor — our recommended AI-powered code editor."
+---
+
+## What It Is
+
+[Cursor](https://cursor.com) is a code editor built on VS Code with deep AI integration. It can autocomplete, refactor, explain code, and generate entire features from natural language prompts. We use it as our primary IDE.
+
+Even if you're not an engineer, Cursor is useful for editing MDX content files, browsing the codebase, and making small changes.
+
+## Prerequisites
+
+- [Homebrew](/handbook/onboarding/homebrew) installed
+- [Node.js & pnpm](/handbook/onboarding/node-and-pnpm) installed (for working with the codebase)
+
+## Install
+
+```bash
+brew install --cask cursor
+```
+
+Or download directly from [cursor.com](https://cursor.com).
+
+## First Launch
+
+1. Open Cursor
+2. Sign in with your account (free tier works, Pro is better)
+3. When prompted to import VS Code settings, do it if you have existing VS Code config — otherwise skip
+4. Open the Hyprnote repo: `File > Open Folder` and select your `hyprnote` directory
+
+## Key Features to Know
+
+**Cmd + K** — AI edit. Select code, press `Cmd + K`, describe what you want changed. Useful for quick edits without understanding the full syntax.
+
+**Cmd + L** — AI chat. Ask questions about the codebase, get explanations, generate code.
+
+**Tab completion** — Cursor predicts your next edit as you type. Press Tab to accept.
+
+**Composer** (`Cmd + Shift + I`) — Multi-file AI editing. Describe a feature or change and Cursor will make edits across multiple files.
+
+## Recommended Setup
+
+Install the recommended extensions when Cursor prompts you. The repo includes a `.vscode/extensions.json` with our standard set.
+
+## Walkthrough
+
+Watch the [Cursor Visual Editor walkthrough](https://www.youtube.com/watch?v=XOtHjA8THCw) for a quick intro to the main features.
+
+## For Non-Engineers
+
+You don't need to understand code to use Cursor productively:
+
+- **Edit MDX files** — Blog posts, docs, and handbook pages are all MDX (Markdown with some extras). Open them in Cursor, edit the text, save.
+- **Search the codebase** — `Cmd + Shift + F` to search all files. Useful for finding where specific text appears.
+- **Use AI to help** — `Cmd + L` and ask "explain this file" or "what does this component do" in plain English.
+
+## Troubleshooting
+
+**"Cursor can't connect to the network when indexing"** — Ensure you have a stable internet connection and restart Cursor.
+
+**Extensions not loading** — Run `Cmd + Shift + P` > "Developer: Reload Window".
+
+## Back to Checklist
+
+[Return to Tooling Checklist](/handbook/onboarding/tooling-checklist)

apps/web/content/handbook/onboarding/6.gitbutler.mdx

@@ -0,0 +1,64 @@
+---
+title: "GitButler"
+section: "Onboarding"
+summary: "Set up GitButler — the visual git client we use for branching and commits."
+---
+
+## What It Is
+
+[GitButler](https://gitbutler.com) is a git client that makes branching, committing, and pushing visual and intuitive. Instead of memorizing git commands, you drag changes into branches, write commit messages, and push — all from a GUI.
+
+We use GitButler for daily git workflow. You don't need to learn raw git commands to contribute at Hyprnote.
+
+## Why Not Just Use Git in the Terminal?
+
+You can, and some people do. But GitButler is better for most workflows because:
+
+- You can see all your changes at a glance
+- You can organize changes into multiple branches simultaneously (virtual branches)
+- Committing and pushing is one click, not three commands
+- It handles merge conflicts visually
+
+## Install
+
+Download from [gitbutler.com](https://gitbutler.com) or install via Homebrew:
+
+```bash
+brew install --cask gitbutler
+```
+
+## First Launch
+
+1. Open GitButler
+2. Sign in with your GitHub account
+3. Add the Hyprnote repo: click "Add Repository" and select your `hyprnote` folder
+4. GitButler will detect the existing git state and show your workspace
+
+## Key Concepts
+
+**Virtual Branches** — GitButler lets you have multiple branches active at the same time. Changes in your working directory can be dragged between branches. This is different from traditional git where you switch between branches.
+
+**Workspace** — Your current set of active virtual branches. Everything you see in GitButler is your workspace.
+
+**Commit and Push** — Select files or hunks, write a commit message, click commit. Then push to get it to GitHub.
+
+## Daily Workflow
+
+1. Open GitButler to see what files you've changed
+2. Drag changes into the right branch (or create a new one)
+3. Write a commit message and commit
+4. Push when ready for review
+
+## For Non-Engineers
+
+If you're editing content (blog posts, docs, handbook):
+
+1. Make your edits in Cursor
+2. Open GitButler — your changed files will appear
+3. Write a short description of what you changed (e.g., "Updated blog post about product launch")
+4. Click commit, then push
+5. GitButler will create a PR on GitHub automatically if configured, or you can create one from GitHub
+
+## Back to Checklist
+
+[Return to Tooling Checklist](/handbook/onboarding/tooling-checklist)

apps/web/content/handbook/onboarding/7.claude-code.mdx

@@ -0,0 +1,63 @@
+---
+title: "Claude Code"
+section: "Onboarding"
+summary: "Set up Claude Code — the AI coding assistant that runs in your terminal."
+---
+
+## What It Is
+
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is an AI assistant that lives in your terminal. You describe what you want in plain English, and it reads files, writes code, runs commands, and makes changes across your project. Think of it as a very capable teammate you can pair-program with.
+
+We use Claude Code for everything from writing features to debugging to content edits.
+
+## Prerequisites
+
+- [Homebrew](/handbook/onboarding/homebrew) installed
+- [Node.js & pnpm](/handbook/onboarding/node-and-pnpm) installed
+- A terminal ([Warp](/handbook/onboarding/warp) recommended)
+
+## Install
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+## First Launch
+
+1. Open your terminal
+2. Navigate to the Hyprnote repo: `cd ~/Dev/hyprnote` (or wherever you cloned it)
+3. Run: `claude`
+4. On first launch, it will ask you to authenticate with your Anthropic account
+
+## How It Works
+
+Once inside a Claude Code session:
+
+- **Describe what you want** — "Fix the typo in the homepage header" or "Add a new blog post template"
+- **It reads your codebase** — Claude Code understands the project structure and can find relevant files
+- **It makes changes** — You review each change before it's applied
+- **It runs commands** — It can run tests, builds, and other commands with your permission
+
+## Useful Commands
+
+```
+/help          — See available commands
+/clear         — Clear conversation history
+```
+
+Type your request in natural language. Be specific about what you want — "change the button color to blue" works better than "make it look better".
+
+## For Non-Engineers
+
+Claude Code is powerful even if you don't write code:
+
+- **Edit content** — "Update the blog post title to 'Building in Public'"
+- **Find things** — "Where is the pricing page defined?"
+- **Understand code** — "Explain what this file does"
+- **Make changes** — "Add a new section to the handbook about onboarding"
+
+You review every change before it's applied, so you can't accidentally break anything.
+
+## Back to Checklist
+
+[Return to Tooling Checklist](/handbook/onboarding/tooling-checklist)

apps/web/content/handbook/onboarding/8.warp.mdx

@@ -0,0 +1,72 @@
+---
+title: "Warp"
+section: "Onboarding"
+summary: "Set up Warp — a modern terminal that makes command-line work less intimidating."
+---
+
+## What It Is
+
+[Warp](https://www.warp.dev) is a modern terminal application. If you've never used a terminal before, think of it as a text-based interface to your computer — you type commands instead of clicking buttons. Warp makes this less intimidating with features like autocomplete, AI command search, and a clean interface.
+
+## Why a Terminal?
+
+Even non-engineers need a terminal at Hyprnote. You'll use it to:
+
+- Install tools (via Homebrew)
+- Run the website locally to preview content changes
+- Use Claude Code for AI-assisted editing
+- Push code/content changes
+
+Warp makes all of this easier than the default Mac terminal.
+
+## Install
+
+```bash
+brew install --cask warp
+```
+
+Or download from [warp.dev](https://www.warp.dev).
+
+If you don't have Homebrew yet, install Warp from the website first, then use Warp to [install Homebrew](/handbook/onboarding/homebrew).
+
+## First Launch
+
+1. Open Warp
+2. Sign in (free account)
+3. It will ask to be your default terminal — say yes
+
+## Key Features
+
+**AI Command Search** — Press `Ctrl + ~` (or click the AI icon) and describe what you want to do in plain English. Warp will suggest the right command.
+
+**Autocomplete** — Start typing a command and Warp suggests completions. Press Tab to accept.
+
+**Blocks** — Each command and its output is grouped into a "block". You can copy, share, or bookmark individual blocks.
+
+**Workflows** — Save frequently used commands as reusable workflows.
+
+## Essential Commands
+
+If you're new to the terminal, here are the commands you'll use most:
+
+```bash
+cd <folder>       # Go to a folder (e.g., cd ~/Dev/hyprnote)
+ls                # List files in the current folder
+pwd               # Show where you are
+```
+
+You don't need to memorize much beyond this. Use Warp's AI search for everything else, or use Claude Code which handles commands for you.
+
+## macOS Permissions
+
+Warp needs some system permissions to work with Hyprnote in development:
+
+1. Go to **System Settings > Privacy & Security**
+2. Grant Warp access to **Microphone** (for testing audio features)
+3. Grant Warp access to **Accessibility** (for system-level features)
+
+See the [developer setup docs](/docs/developers/setup) for more details on permissions.
+
+## Back to Checklist
+
+[Return to Tooling Checklist](/handbook/onboarding/tooling-checklist)