The first page stands as written. This one takes each of Justin's points, says whether I agree, and revises the plan where he's right — which is most places. The biggest changes: a GitHub App instead of OAuth, a real answer to "what do the sliders do", private-first resources, an explicit public link, and the commit-graph canvas removed.
Correct, and it fixes the privacy cliff the first page only warned about. A GitHub App with least-privilege read permissions on user-selected repos, delivering webhooks, is the whole integration. No polling, no historical scrape, no repo scope ever.
Plan change: §GitHub App below replaces the "read:user + GraphQL counts" fallback. The town starts on install day; nothing is back-filled.
Fair. The first page said "sliders become the spend" and stopped. The rule is: activity paces, sliders shape. Every activity earns build points; the stage you reach depends only on how many points you've earned; the sliders decide which ladder those points buy from — land, height, life, or landmarks — so two developers with identical activity get visibly different towns.
Plan change: §What the sliders do — four build ladders with costs, a scheduler rule, and four renders of the same town under four allocations.
Right, and it's a better game for it. Core loop is now built only on events that fire on private repos too: push, PR opened / merged, review (when a team exists), issue closed, release/tag, CI check status. Public-only signals (stars, forks, external PRs) become an additive Visitors bonus that never gates a stage. One caveat I'd keep: solo devs who commit straight to main never merge PRs — so a productive day of pushes must still build a house, not just deliver bricks.
Plan change: §Private-first resources — three core resources (Bricks, Blueprints, Morale) earned everywhere, Visitors as bonus; a "day of work" rule for direct-to-main committers.
Unchanged. Every new render on this page is derived from the same hero plate, which is also the proof that the style holds up as a system: same camera, same palette, different towns.
Unchanged. Dormancy is weather: fog rolls in after ~14 quiet days, cranes park, windows dim; the first push back is a sunrise. A festival that lapses just ends — no ruins, no lost stage, no de-rank, ever.
It was a landing-page "paste your username" fake-door idea from before the integration model was settled; with a GitHub App there is no history to draw from, so it doesn't belong in the product. It's out of the plan. What survives from that section is only the metaphor — a commit is a brick — not the ground plan.
Plan change: §What was cut. Consequence: Day 1 has to be charming on its own — the first push after install should visibly build the first cottage in front of you.
Yes: every town has a public URL — committown.io/u/<login> — and that page is the living town, not a screenshot of it. Owner and visitor see the same page; the owner additionally sees the council controls. Images, banners and clips are all just renderings of that URL. Public by default with a private toggle.
Plan change: §Public link — URL scheme, visitor mode, OG image, and the "leave a postcard" visitor action.
Kept and made concrete: a ladder of streak effects (7 / 30 / 90 days) plus cadence effects (a late-night push lights the town; weekend work opens the market). Streaks are additive only and get grace days, so they never become the anxiety machine GitHub removed.
Plan change: §Streaks & festivals, with a lantern-festival render.
Yes. The MVP is: GitHub App, three resources, the five-stage kit, six cheap ambient layers, day/night, fog, the public URL with an OG image, and a static README badge. Nothing else.
Plan change: §MVP scope — v0 / v1 / v2 cut lines.
Moving to install-day-onwards, private-first is right, but it makes the first week the whole product: a new user sees a hamlet, and stays or leaves before it becomes a village. So the MVP must nail the first-hour experience (install → first push → cottage builds live) and the first-week cadence (a house a day at normal activity) more than any later stage. Tune the early ladder generously; the Metropolis can wait.
The user installs the Commit Town app on one or more repos. GitHub sends us webhooks for those repos only. We store counts and timestamps, not code — and by default not commit messages either.
| Permission (read) | Webhook events subscribed | What we keep | Feeds |
|---|---|---|---|
| Metadata (mandatory) | installation, installation_repositories | repo ids + names the user connected | town setup, districts |
| Contents | push, create (tag), release | commit count per push, branch, timestamp; tag/release name | Bricks, Visitors (releases) |
| Pull requests | pull_request (opened, merged, closed), pull_request_review | opened/merged flags, additions+deletions (capped), reviewer ≠ author | Blueprints, Morale |
| Issues | issues (opened, closed) | counts only | Morale (closed), potholes (opened) |
| Checks / Actions | check_suite, workflow_run (default branch) | green/red state per repo | power-plant state, CI smoke |
| Discussions (optional) | discussion, answered | counts | Morale (public repos mostly) |
| — (no permission needed) | star, fork, watch | counts | Visitors bonus (public repos only) |
read:user only) to own a town; the App installation is a separate step so an org admin can connect team repos laterThe same four renders below come from the same island, the same activity, the same number of build points — with the council set four different ways. That is the whole answer to "how do the sliders affect things".
What the visible stats then mean. Population = housing capacity × (0.6 + 0.4 × happiness index) — so Happiness makes the same houses hold more people and puts more of them on the streets. Visitors = tourism landmarks × recent activity, plus the public-repo bonus. Technology sets the skyline. Expansion sets the footprint. Justin's four slider names stay; they now each mean one ladder.
Justin's original sliders were percentages summing to 100%. Keep that on the owner page (it's honest about the trade-off); the coarse 4-step control on the first page is just a compact way to show the same split.
Three core resources every developer earns, whether the repo is public or not. Visitors is a bonus channel — it never gates a stage.
| Event (fires on private repos?) | Resource | Build points | Visible in town |
|---|---|---|---|
| Push — per commit (yes) | Bricks | 1, capped at 20/day, diminishing after 8 | Cart drops bricks; scaffold rises one tier |
| Day of work — any day with ≥3 commits and no PR (yes) | Blueprints | 6 (once per day) | A cottage/house completes — so direct-to-main devs still build |
| PR opened (yes) | Blueprints | 3 | Surveyors stake a plot; crane parks |
| PR merged (yes) | Blueprints | 10 (+ up to 10 by size, capped) | Topping-out — roof lowered, windows light |
| PR review by someone else (yes, if a team exists) | Morale | 3 | Inspector with clipboard; green stamp |
| Issue closed (yes) | Morale | 2 | Road crew fills a pothole |
| Release / tag published (yes) | Blueprints + Visitors | 25 | Fireworks + a named landmark |
| CI red → green on default branch (yes) | Morale | 2 | Smoke clears, lights back on |
| Star / fork received (public only) | Visitors bonus | 5 / 5 | Tourist balloon lands; road toward a sister settlement |
| Streak day (computed) (yes) | multiplier | ×1.1 at 7d, ×1.2 at 30d | Lanterns → festival → biome |
Design consequences. The headline number is Blueprints, not Bricks. A busy senior on a private monorepo who ships four PRs a week earns ~40–80 Blueprints — a house or two a week at Village prices, a tower every few weeks at City prices. A student pushing forty tiny commits a day earns the daily Brick cap and one "day of work" Blueprint — a cottage every few days. Both towns grow; neither is grotesque; empty commits can't buy a skyline.
The living town lives at a public URL. Everything else — OG image, README banner, clips — is a rendering of that page.
Owner and visitor load the same page. The owner sees the council panel and "since you left"; the visitor sees a summary card and a "Get your own town" call to action. Public by default; a private toggle hides the page and the OG image.
og.png is regenerated on every stage change and daily; badge.svg is the README embed (static in MVP, animated later); moment clips are rendered from the same scene at topping-out, release and stage-up, and the share prompt appears then.
"Leave a postcard" is the Strava-kudos equivalent: it drops a tiny visitor into the owner's town for a day and shows up in their "since you left" strip. It gives a reason to visit other people's towns, which is what makes the URL worth clicking.
| Trigger | Effect |
|---|---|
| 7-day streak | Lanterns go up along the main street; ×1.1 build points |
| 30-day streak | Festival: market stalls, string lights, evening fireworks, crowd; ×1.2 |
| 90-day streak | Biome shift for the season (autumn palette, snow, blossom) until the next 90 |
| Push after 22:00 local | Windows light one by one; the night-mode OG image for that day |
| Weekend commits | Market day: stalls in the square, more walkers |
| Release | Fireworks over the tallest building + a plaque with the tag |
| Streak lapses | Lanterns come down quietly. That's all. Grace: 2 free days per month |
| 14 quiet days | Fog rolls in, cranes park, windows dim — nothing breaks |
| First push after fog | Sunrise sweeps the fog off; a small "welcome back" in the Gazette |
Unchanged from page 01: the verdict is still GET-DATA, and the smallest test is still one week — but with the App model the test is "install → first push → cottage builds live → share the URL", not a username paste. Measure D7 return of people who shared, and whether first-week visitors say it looks different from Git City.
Everything else on page 01 — the theses, the style pick, the render approach, the growth strip, the never-punish rule, the share ranking — stands.