Almonds Stable Core — initial implementation

[kicka5h]

Summary

Implements the complete Almonds Stable Core: all snippet commands, stash management, remote stash support, configuration system, packaging, CI/CD, tests, and documentation.

Closes #1, Closes #2, Closes #3, Closes #4, Closes #5, Closes #6, Closes #7, Closes #8

Changes

• Snippet commands — snack list [category], snack search, snack unpack [--flat] [--force], snack pack [--force] with overwrite prompts and clear error messages
• Stash management — snack stash create, snack stash list, snack stash move; named stashes written to ~/.snackstashrc in INI format; legacy stash=<path> format still read
• Remote stash — snack stash add-remote owner/repo [--subdir] [--force]; downloads GitHub tarball via stdlib urllib/tarfile, copies .py files preserving directory structure
• Configuration — SnackConfig class with priority order: SNACK_STASH env var → active named stash → error; every misconfiguration produces an actionable message
• Version flag — snack --version reads from package metadata; pyproject.toml is the single source of truth
• Packaging — pyproject.toml with correct entry point (snack = "snacks.main:app"), installs cleanly via pipx and pip
• CI — ci.yml runs pytest on push/PR to main across Python 3.10, 3.11, 3.12
• Publish — publish.yml triggers on v* tags: test → build → publish to PyPI (OIDC trusted publishing) → create GitHub Release with artifacts
• Tests — 33 tests across test_commands.py and test_stash_commands.py; config path monkeypatched, add-remote uses mocked tarball, no real network calls or writes to ~
• Documentation — full README and 7-page wiki covering installation, configuration, all commands, snippet best practices, error reference, and contributing guide

Test plan

• Existing tests pass (pytest tests/ -v) — 33 passed
• New tests added for all new behaviour (stash management, add-remote, version flag)
• Tested manually with a real stash

Notes for reviewer

add-remote uses only stdlib — no new runtime dependencies beyond Typer. The config file format changed from the original sectionless stash=<path> to INI-style [stash.<name>] sections, but the old format is still read transparently so existing installs won't break.

PyPI publish requires a one-time trusted publisher setup on pypi.org before the first tag push (repo Settings → Environments → pypi).