<!--
File: docs/workspace-setup.md
Purpose: How to recreate this workspace from scratch on a new machine.
Fill in: tweak repo URL / service list once the workspace is project-specific.
See: docs/workspace-structure.md → "IDE and Agent Configuration", "scripts/ — Bootstrap and Utility Scripts"
-->

# Workspace Setup

Bootstrapping splits into two layers:

- **Global (once per machine)** — agent runtimes, their home-directory
  config, and credentials in the OS keychain. Shared across *every*
  workspace on the machine; never lives in the repo.
- **Workspace-local (once per clone)** — files inside this repo. Tracked
  files come with the clone; the `*.example` / `*.local` files are copied
  and tailored per user.

Do the global layer first; the workspace layer depends on it (e.g. the
`gh` login).

## Global — once per machine

Authoritative list: `docs/workspace-structure.md` → "User-Level Files
(Outside the Workspace)". These all live under your home directory and are
**never** checked in.

| Item | Where | Used for | Verify |
|---|---|---|---|
| Agent CLIs | `claude`, `codex`, `opencode`, `gemini` on `PATH` | The agent runtimes themselves | `claude --version` |
| `gh` CLI + login | `~/.config/gh/`, system keychain | GitHub auth + all GitHub operations (required) | `gh auth status` |
| `yt-dlp` | executable on `PATH` | YouTube transcript MCP server | `yt-dlp --version` |
| Codex MCP registration | `~/.codex/config.toml` | Optional per-task servers for Codex (see docs/mcp-setup.md) | `codex` MCP list |
| Gemini MCP registration | `~/.gemini/settings.json` | Optional per-task servers for Gemini (see docs/mcp-setup.md) | restart Gemini, check tools |
| MCP wrapper scripts (if used) | `~/.mcp-scripts/` or `scripts/mcp/` | Launch scripts referenced by MCP config | run the script |
| Service credentials | OS keychain (`security …`), `~/.pgpass`, `~/.aws/`, … | Tokens/passwords for external services | per-service verify cmd in `docs/service-access.md` |

Optional agent toolchain (status line, superpowers plugin, Matt Pocock
skills, graphify) is set up at this global layer too — see
`docs/recommended-tooling.md` for install steps and the per-repo bits.

To install/verify these machine tools, run `scripts/check-dependencies.sh` and
follow `docs/runbooks/dependencies.md`; for service auth, run
`scripts/check-service-access.sh` and follow `docs/runbooks/authentication.md`.

Notes:
- **Credentials never leave the keychain.** `docs/service-access.md` lists
  the retrieve/verify command per service; `.env` holds only non-secret
  identifiers.
- Per-runtime MCP config details (exact TOML/JSON, remote vs. Docker server,
  workspace-local YouTube server) are in `docs/mcp-setup.md` — that doc is
  the source of truth for the Codex/Gemini home-directory snippets above.
- Agent *memory* and *personal preferences* belong in the runtime's own
  store (e.g. `~/.claude/projects/<id>/memory/`), **not** in this repo.

## Workspace-local — once per clone

Authoritative list: `docs/workspace-structure.md` → "Gitignored vs. Checked
In". Tracked files arrive with the clone; you create the local/secret ones.

```bash
# 1. Clone
git clone <clone-url> <workspace-dir> && cd <workspace-dir>

# 2. Bootstrap: dep preflight + entrypoint symlinks + repos/README.md + the
#    per-user config copies (.env, .mcp.json, .claude/settings.local.json).
./scripts/setup.sh            # add --clone-repos for a multi-repo workspace

# 3. Dependencies — check, then install anything missing per the runbook.
#    (After setup.sh, so the Copilot-trust advisory sees the trustedFolders
#    seed it creates.)
./scripts/check-dependencies.sh                   # → docs/runbooks/dependencies.md

# 4. Authentication — check, then follow the runbook for anything missing.
./scripts/check-service-access.sh                 # → docs/runbooks/authentication.md

# 5. Verify structure
./scripts/check-workspace-structure.sh
```

Each `check-*.sh` reports what's missing; an AI agent (or you) then follows the
matching **runbook** in `docs/runbooks/` to fix it for this OS — see
`docs/runbooks/README.md`. The checks are verify-only; they never log you in or
install anything.

What each local file is for:

| File | Tracked? | Action on a fresh clone |
|---|---|---|
| `CONTEXT.md` + `CLAUDE.md`/`AGENTS.md`/`GEMINI.md` symlinks | yes | nothing — read it |
| `opencode.json`, `.gemini/settings.json` | yes | nothing — OpenCode/Gemini pick them up |
| `.env.example` → `.env` | example tracked | copy, set identifiers (no secrets) |
| `.mcp.json.example` → `.mcp.json` | example tracked | copy for Claude Code |
| `.claude/settings.json.example` → `.claude/settings.local.json` | example tracked | copy, tailor permissions |
| `scripts/mcp/youtube-transcript.sh` | yes | optional YouTube MCP server; needs `yt-dlp` |
| `repos/*`, `references/*` | no (clones) | populated by `setup.sh --clone-repos` |
| `.service-access.local.json` | no | generated by `check-service-access.sh` |

> `scripts/setup.sh` is idempotent — re-run it any time to repair missing
> symlinks or config copies. This also fixes the case where the
> `CLAUDE.md`/`AGENTS.md`/`GEMINI.md`/`repos/README.md` symlinks were
> **flattened into plain files** (Windows clones without `core.symlinks`, or
> some copy-based "Use this template" flows): delete the flattened files and
> re-run `setup.sh`, or `git config core.symlinks true` before cloning.

## Quick verification

```bash
gh auth status                                    # global: GitHub auth
claude mcp list                                   # local:  core MCP (graphify) visible to Claude Code
scripts/mcp/youtube-transcript.sh                 # local:  starts the YouTube MCP server
./scripts/check-workspace-structure.sh            # local:  symlinks resolve, dirs present
```