# Local project initial push hygiene

Use when turning an already-existing local prototype into a remote-backed GitHub repository.

## Durable workflow

1. Inspect current local state before committing:
   - `git status --short --branch --ignored`
   - `git config --local --list --show-origin`
   - `git remote -v`
   - top-level file inventory and size check
2. Confirm ignored runtime artefacts are really ignored before staging:
   - secrets: `.env`, token files
   - generated/runtime data: `input/`, `output/`, local DBs, media, cache dirs
   - Python artefacts: `.venv/`, `venv/`, `__pycache__/`, `*.py[cod]`
3. Make the project reproducible before the first commit:
   - add `README.md` with setup, run, verification, and prerequisites
   - add `.env.example` with placeholders only
   - add dependency manifest (`requirements.txt`, `pyproject.toml`, etc.)
4. Remove machine-specific hardcoded paths before committing. Prefer paths relative to the project root / source file, e.g. `Path(__file__).resolve().parent` for Python prototypes.
5. Externalize hardcoded local service/model names into environment variables where practical, while preserving safe defaults in docs/examples.
6. Verify before commit:
   - syntax/lint smoke appropriate to the project, e.g. `python3 -m py_compile ...`
   - staged secret scan; report only behavioral results, never token values
7. Commit and push:
   - if the remote default is `main`, rename local branch before pushing: `git branch -M main`
   - configure `origin` only after verifying the intended repo
   - push with a one-shot credential helper reading the token from `~/.hermes/secrets/...` when `gh` is unavailable
8. Verify the exact branch, not just remote `HEAD`:
   - compare `git rev-parse HEAD` with `git ls-remote origin refs/heads/<branch>`
9. Final report should separate:
   - code committed/pushed and verified
   - local ignored artefacts left out intentionally
   - runtime dependencies or models still missing from the active environment

## Pitfalls

- Do not commit sample media, generated documents, local DBs, or `.env` just because they are useful for manual testing.
- Do not treat successful syntax checks as an end-to-end runtime test; explicitly state when dependencies, GPU, Ollama models, or external services are still required.
- Do not save command output containing credentials, token hashes, or raw `.env` values.