# Machine Setup

## Purpose

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.

## What Is Local-Only

These remain local responsibilities and should not be treated as repository-owned configuration:
- Codex authentication
- personal shell aliases
- personal editor preferences
- secrets
- API keys
- machine-specific paths unless only documented as examples

## What Is Repository-Owned

These should be read from the repository and kept aligned in version control:
- workflow rules
- branch policy
- task format
- agent roles
- setup instructions
- test execution instructions
- docs for humans and agents

## Minimal Bootstrap Flow

Use this sequence on a new machine:

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 auth is working
- `AGENTS.md` is present
- `.codex/config.toml` is present
- `.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`