docs: define machine setup guidance

docs/MACHINE_SETUP.md

@@ -1,37 +1,81 @@
 # Machine Setup
 
-## Goal
+## Purpose
 
-Bring a new machine to a usable Codex development state with minimal local-only setup.
+This document describes the minimum setup needed to continue repository work from a different machine. It is intended as a quick-start handoff for working with HoopScout v2 phase 0 using Codex and repository-defined agent workflows.
 
-## Local-only prerequisites
+## What Is Local-Only
 
-Not stored in the repo:
+These remain local responsibilities and should not be treated as repository-owned configuration:
 - Codex authentication
-- personal shell setup
+- personal shell aliases
-- secrets/API keys
+- personal editor preferences
-- local editor preferences
+- secrets
+- API keys
+- machine-specific paths unless only documented as examples
 
-## Repository bootstrap
+## What Is Repository-Owned
 
-1. Clone the repository
+These should be read from the repository and kept aligned in version control:
-2. Checkout `develop`
+- workflow rules
-3. Read:
+- branch policy
-   - AGENTS.md
+- task format
-   - docs/WORKFLOW.md
+- agent roles
-   - docs/TASK_TEMPLATE.md
+- setup instructions
-4. Ensure Codex can see:
+- test execution instructions
-   - AGENTS.md
+- docs for humans and agents
-   - .codex/config.toml
-   - .codex/agents/*
-   - .agents/skills/*
 
-## Validation checklist
+## Minimal Bootstrap Flow
 
-A machine is considered ready when:
+Use this sequence on a new machine:
-- repo is cloned
+
+1. Clone the repository.
+2. Checkout `develop`.
+3. Authenticate Codex locally.
+4. Read:
+   - `AGENTS.md`
+   - `docs/WORKFLOW.md`
+   - `docs/MACHINE_SETUP.md`
+   - `docs/TASK_TEMPLATE.md`
+5. Create a task branch from `develop`.
+
+## Validation Checklist
+
+A machine is ready for repository work when:
+- repository is cloned
 - correct branch is checked out
-- Codex authentication is working
+- Codex auth is working
-- AGENTS.md is present at repo root
+- `AGENTS.md` is present
-- .codex/config.toml is present
+- `.codex/config.toml` is present
-- task branches can be created from develop
+- `.codex/agents/` is present
+- docs are present
+- `make doctor` works
+
+## Local Checks
+
+Run `make doctor` to verify the repository bootstrap and local working assumptions.
+
+## Troubleshooting
+
+### Wrong Branch Checked Out
+
+Return to `develop`, update local state if needed, and create the correct task branch from there.
+
+### Codex Not Authenticated
+
+Complete Codex authentication locally on the machine before continuing. Authentication is not stored in the repository.
+
+### Missing Repository Files
+
+Confirm the repository was cloned correctly and that required tracked files such as `AGENTS.md`, `.codex/config.toml`, and the `docs/` files are present.
+
+### Local Assumptions Do Not Match Repository Instructions
+
+Follow the repository instructions rather than local habits. If the repository guidance is incomplete or outdated, update the tracked docs instead of relying on undocumented local behavior.
+
+## Related Files
+
+- `AGENTS.md`
+- `docs/WORKFLOW.md`
+- `docs/TASK_TEMPLATE.md`
+- `.codex/config.toml`