the-reals

The Sims simulates a life. This renders yours.

▶ PLAY THE DEMO — 10 seconds, no install

The Reals is a pixel-RPG front-end for real automation stacks. Each character is one of your actual AI agents: the banker reports your real balances, the postman sorted your real email this morning, the mechanic knows your truck’s actual mileage — and the scrolls on the approvals desk are real decisions waiting for a real signature. Everything they say is true.

Why this exists

Agent dashboards are built for developers. But the people whose lives agents run — families, small-business owners — deserve an interface you’d actually want to open. So: a town. Walk up to someone and ask. The village metaphor isn’t decoration; it’s an honest map of the system — one citizen per agent, one building per domain, a notice board for heartbeats, and a desk where the human is still the mayor’s boss.

Under the costume it’s rigorously boring: n8n workflows do all logic, Postgres holds all truth, and the town reads and requests — it never does. Every write is token-gated, PIN-gated where money’s involved, additive-only, and fully audited.

What’s in the town


🏛️ Town Hall	The Mayor reads your real morning briefing — tasks, approvals, agents on duty
🏦 Bank	Penny reports net worth, cash, debt (privacy mode masks the numbers for guests)
📯 Post Office	Pete’s mailbag: this week’s real email triage
🔧 Garage	Gus knows every vehicle, mileage and all
📜 Approvals Desk	Pending decisions as scrolls — approve/reject with your owner PIN
📚 The Repo Keeper	A hidden librarian who minds this very repository. Find her.

Plus: press C for a downloadable postcard of wherever you’re standing, ?visitor=Name links that greet your friends by name, a dog that follows you, and — if enough travelers star this repo — new residents move to town, one per ten stars. (The Keeper keeps count.) There is also an old code known to make the dog situation escalate.

Quick start (60 seconds, no backend)

Open engine/index.html in a browser — that’s the whole install. You’re in Maple Hollow, a fictional demo town on baked-in data (DEMO SNAPSHOT badge). Arrow keys / WASD to move, E to talk (or open the Approvals Desk beside Town Hall), M to leave a message, P to toggle privacy mode, C for a postcard.

Make it real (about an hour)

Database: run backend/sql/001_town_feed.sql against your Postgres/Supabase (edit table names to match your schema).
n8n: import both workflows from backend/n8n/, bind your service_role credential, set a token + owner PIN — full steps in backend/n8n/README.md.
Game: edit the ★SKIN:CONFIG block at the top of engine/index.html — name, owner, your webhook URLs, your token.
Open it. The badge flips to ● LIVE DATA and the townsfolk start telling the truth.

Architecture (the one rule that matters)

your agents (n8n workflows)  →  Postgres/Supabase (source of truth)
                                      ↑ service_role, server-side only
                              n8n Town Interface (3 webhooks)
                          feed (read)  ·  action (request)  ·  approve (PIN-gated)
                                      ↑ shared token, CORS-open
                              engine/index.html (this repo)
                        THE TOWN READS AND REQUESTS. IT NEVER DOES.

The game is a skin. It holds no state, makes no decisions, and can only display the feed or file a request that gated, audited machinery picks up. Full doctrine in docs/architecture.md — and the receipts in docs/PROVENANCE.md: this wasn’t built as a demo, it was extracted from a live system running a real family’s finances, rentals, email, and vehicles across 25+ agents.

Repo map

Path	What
`engine/index.html`	The whole game — single file, zero dependencies
`backend/sql/`	The `town_feed()` snapshot function
`backend/n8n/`	Importable workflows (interface + approvals) + setup guide
`backend/feed.schema.json`	The formal feed contract — never rename or remove existing keys
`examples/`	Alternate `TOWN` configs (home town, business town)
`docs/`	Architecture, skinning, security, specs, runbooks, backlog, provenance
`test/smoke.mjs`	Mandatory headless-browser smoke test — run before claiming any change done
`CLAUDE.md`	Operating manual for AI sessions: hard rules, do-not-touch list, escalation triggers
`brand/`	Brand book, logo, banners, GIFs

Adding a building (the 3-step recipe)

SQL: add one key to town_feed() with the data the new Real needs.
Engine: one entry in buildings, one in npcs, one dialog set — all inside ★SKIN fences (see docs/skinning.md).
Allowlist: if the new Real accepts messages, add its agent_key in n8n.

Status & roadmap

v0.2.1 — Approvals Desk shipped (PIN-gated, verified against a live stack); SKIN fences + upgrade runbook; formal feed contract with a daily sentinel; full AI-collaboration kit (CLAUDE.md, smoke test, pre-scoped backlog, specs).
Next: AI dialogue — ask any Real a question, answered in character from live data (v0.3, specced) · ambient world state — day/night, sirens, sleeping agents (v0.4, specced) · more districts · multi-visitor. See docs/roadmap.md.

The ask

If a town where the mailman actually read your email made you smile: star the repo — someone new moves in every ten stars, and the Keeper announces the count in-game. Building your own town on top? Use this template and found one.

Want one for your business, without building it yourself? The engine is free forever; the standing-it-up — agents, database, a town skinned to your trade, and someone keeping it honest — is a service. Open an issue titled [town-for-hire] and the maintainer will find you.

_{Made with an unreasonable commitment to the bit. 🐕 There is a dog in this README.}

_{you found the dog}

_{His name is Biscuit. He follows you around the town because the pathfinding was easy and the joy was free. He appears at second 3 of the hero GIF, bottom of the night banner, and — if you know the old code — in numbers.}

This site is open source. Improve this page.