docs/deployment.md

# Deployment runbook

How the GAIA Solver is deployed and kept in sync across the HF Space
(primary) and the GitHub mirror.

## Topology

- **Primary:** Hugging Face Space — `origin` →
  `https://huggingface.co/spaces/ovo456/Final_Assignment_Template`
- **Mirror:** GitHub — same `main` branch (see "Add the GitHub mirror"
  below). Exists for visibility and history preservation.

The Space reads the committed `answer_bundle.json` and submits it at runtime
(ADR-0001 hybrid execution); the GitHub mirror carries the same history.

## Environment variables & Space secrets

The full env-var table lives in [`README.md`](../README.md). The only
**Space secrets** needed are:

| Secret | Required? | Purpose |
|---|---|---|
| `DEEPSEEK_API_KEY` | Required for live solves | Lets the Space solve unbundled Tasks (text/web-only). |
| `OPENAI_API_KEY` or `OPENROUTER_API_KEY` | Optional | Hosted audio-transcription fallback. |

Set them in the Space: **Settings → Variables and secrets → New variable**.

## GitHub mirror (one-time setup)

The GitHub mirror does not exist yet — create it before you can push:

1. Create an **empty** repository on GitHub (e.g.
   `https://github.com/ovo456/Final_Assignment_Template`). Do **not**
   initialize it with a README/license — that would create a conflicting root
   commit and force a merge.
2. Add it as a mirror remote:

   ```bash
   git remote add github https://github.com/<owner>/<repo>.git
   ```

3. Push the same `main` to both remotes:

   ```bash
   git push origin main    # HF Space (primary)
   git push github main    # GitHub mirror
   ```

> Pushing to GitHub requires auth: an SSH key registered with your GitHub
> account, or a PAT saved in your credential helper (`osxkeychain` on macOS).
> If `git push github main` prompts for credentials, run `gh auth login`, or
> add your public key at https://github.com/settings/keys.

## Dev loop (regenerate the Answer bundle)

```bash
cp .env.example .env          # fill in DEEPSEEK_API_KEY, GAIA_API_URL, ...
pip install -r requirements.txt
python text.py                # solves + writes answer_bundle.json and gaia_results.csv
git add answer_bundle.json
git commit -m "Regenerate Answer bundle"
git push origin main          # the Space picks up the new bundle
```

## Notes

- `files/` (pre-downloaded Attachments) and `.env` are gitignored — never
  force-add them.
- Agent-internal tooling (`.agents/`, `.scratch/`, `skills-lock.json`,
  `SESSION_HANDOFF.md`) is gitignored and kept out of the shared repo.
- The results-view prototype lives on branch `prototype/results-view` (out of
  `main`).