M1 unbundled + deploy pipeline + M2 PR A (foundation)

[ArchDLayer]

Status (updated as work continues — read this section first)

This PR is being built across multiple sessions/conversations. This section
is the continuity log so a fresh session (or you, on your phone) can pick up
without re-reading the whole chat history. Commit messages also carry
per-commit rationale.

Done and pushed:

1. Unbundled challenge_keeper.py (M1) into the real module layout, rebuilt
   tools/build_single_file.py, verified byte-identical regeneration.
2. Deployment pipeline: systemd unit, cloud-init, GitHub Actions deploy,
   phone click-path README.
3. Fixed a pre-existing bug in M1: models.create_challenge() defaulted
   start_date to date.today(), violating CLAUDE.md's own rule. Now a
   required argument; callers resolve "today" via resolve_local_date().
4. M2 PR A (foundation): /newchallenge guided setup, post+pin the text
   board, Join button → enrollment → DM deep-link → timezone picker
   (quick-pick zones + free-text "Other"). See bot.py, config.py,
   strings.py, challenge_setup.py, handlers/.

Decisions made along the way, and why:

• Freeze tokens: skipped. The plan flags that reset_progress (one
  missed day wipes all 100 days) likely causes dropout around week six.
  Decided to surface longest_streak prominently instead of implementing
  freeze tokens — reset_progress stays fully strict, freezes_left stays
  unused (models.enrol() still defaults it to 0).
• Grace window: kept at 3 hours (the existing default, unchanged).
• PR size: fewer, larger PRs rather than one per plan step. M2 is split
  into four: A (this one, foundation) → B (core loop: check-in,
  repeat-tap handling, full board / my stats buttons — the plan's own M2
  "done when" checkpoint) → C (image board: avatars, Pillow rendering)
  → D (refresh job).
• Testing: unit tests only for now. This sandbox's network policy blocks
  both api.telegram.org and PyPI installs, so python-telegram-bot can't
  be installed or imported here. Everything not touching telegram is
  tested directly (98 tests passing: the original 76 + challenge_setup.py
  validation + a call-sequence integration test mirroring what the handlers
  do). The bot.py/handlers/ Telegram wiring itself is unverified by
  execution — first real test happens once this is running somewhere with
  real network access (the VPS, or a Termux stopgap).
• Quick-pick timezones: Europe/Vilnius, Warsaw, London, Lisbon, Athens,
  Madrid — matches the zones already used in the M1 demo data.

Telegram-side state (as of the session that built PR A): a throwaway dev
bot (@Challange2536_bot) exists with privacy mode enabled, added as admin
to a throwaway group ("Challange group"). Its token was shared directly in
that chat session, not stored anywhere — if it's needed again and lost,
regenerate via BotFather → /mybots → the bot → API Token. This is all
throwaway/dev-only; the real bot and group get created separately later.

Not started: PR B onward. M2's Telegram-facing wiring has not been
tested against live Telegram at all yet.

---

Original summary (M1 unbundle + deploy pipeline)

challenge_keeper.py was a single-file transport bundle for M1 (data layer
and streak engine). This PR expands it into the real project, per
HANDOFF.md, and builds the deployment pipeline ahead of there being a bot
to deploy.

Unbundled:

• streaks.py, db.py, models.py, views.py, render_text.py,
  tools/demo.py, tests/*, migrations/001_init.sql — extracted
  programmatically from the bundle, not retyped
• tools/build_single_file.py reconstructed — this is what generated the
  bundle originally. Running it regenerates challenge_keeper.py
  byte-for-byte identical to the file you uploaded. challenge_keeper.py is
  a build artifact now — edit the modules and rerun the build script, per
  CLAUDE.md.
• requirements.txt, .env.example, .gitignore, README.md, CLAUDE.md

Deployment pipeline (deploy/, .github/workflows/deploy.yml):

• deploy/challengebot.service — systemd unit, non-root user, Restart=always
• deploy/cloud-init.yaml — first-boot setup targeting Oracle Cloud ARM free
  tier (Ubuntu/aarch64), with Hetzner fallback notes
• .github/workflows/deploy.yml — on push to main: SSH in, git reset --hard
  to the new commit, reinstall requirements only if requirements.txt
  changed, restart the service
• deploy/README.md — the phone click-path: generating the two SSH keypairs
  involved, which GitHub secrets to add and where, what to paste into the
  cloud provider's instance-creation form, how to confirm it worked

Until bot.py exists, challengebot.service crash-loops harmlessly under
Restart=always. Now that PR A adds bot.py, that's no longer true once
this merges and deploys — worth re-checking service status after that.

What you need to do by hand

1. Review this PR (still growing — check back before merging, or ask for it
   to be merged now and continue on a follow-up PR/branch).
2. Create the real VPS when ready — deploy/README.md has the click-path.
3. Add the three GitHub Actions secrets (VPS_HOST, VPS_USER,
   VPS_SSH_KEY).
4. When ready to test for real: either wait for the VPS, or use Termux as a
   stopgap (flagged in the plan) to run the bot directly on your phone.

One open decision, flagged not resolved (from the original M1 PR)

The freeze-token question — resolved above: skipped in favor of
surfacing longest_streak.