If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/citybound/citybound shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 3y ago

• 5 active contributors
• AGPL-3.0 licensed
• CI configured
• ⚠ Stale — last commit 3y ago
• ⚠ Single-maintainer risk — top contributor 93% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live citybound/citybound repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/citybound/citybound.

What it runs against: a local clone of citybound/citybound — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in citybound/citybound | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1247 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of citybound/citybound. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/citybound/citybound.git
#   cd citybound
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of citybound/citybound and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "citybound/citybound(\\.git)?\\b" \\
  && ok "origin remote is citybound/citybound" \\
  || miss "origin remote is not citybound/citybound (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "cb_server/main.rs" \\
  && ok "cb_server/main.rs" \\
  || miss "missing critical file: cb_server/main.rs"
test -f "cb_browser_ui/src/lib.rs" \\
  && ok "cb_browser_ui/src/lib.rs" \\
  || miss "missing critical file: cb_browser_ui/src/lib.rs"
test -f "cb_simulation/src/lib.rs" \\
  && ok "cb_simulation/src/lib.rs" \\
  || miss "missing critical file: cb_simulation/src/lib.rs"
test -f "cb_planning/src/lib.rs" \\
  && ok "cb_planning/src/lib.rs" \\
  || miss "missing critical file: cb_planning/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1247 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1217d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/citybound/citybound"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Citybound is an open-source, multiplayer city simulation game written in Rust with a TypeScript/JavaScript browser UI, focusing on microscopic-detail simulation and collaborative urban planning. It simulates traffic flow, zoning, economy, and city infrastructure with emphasis on realism rather than arcade gameplay, using a custom Rust engine that runs a WebSocket-backed server (rouille) and WebAssembly frontend. Monorepo with Rust workspace: root Cargo.toml defines members (cb_simulation, cb_planning, cb_util, cb_time) plus binary cb_server/main.rs; cb_browser_ui/ is excluded and contains separate Cargo.toml for WebAssembly compilation (Web.toml). Frontend lives in cb_browser_ui/src/ with TypeScript (citybound.tsx, Camera.js) and LESS styling, compiled to WASM and served via rouille HTTP server.

City simulation enthusiasts and urban planning game developers who want deep, realistic mechanics rather than casual city-builders; open-source contributors interested in Rust game engines, WebAssembly integration, and collaborative multiplayer simulation systems.

Actively developed but pre-release: versioned at 0.3.0 with CI/CD via GitHub Actions (.github/workflows/build.yml) and AppVeyor. The project has curated design docs (Notion-based), downloadable live builds, and Patreon funding, indicating sustained maintenance. However, the 'work-in-progress' designation and workspace structure suggest core systems are still evolving.

Single-author project (Anselm Eickhoff) creates maintainer concentration risk. Build system uses custom logic (rust-embed-flag from author's fork, Web.toml in cb_browser_ui) rather than standard tooling. Large Rust codebase (730KB) with no visible test suite in file list creates regression risk. AGPL-3.0 license restricts commercial use and requires source distribution.

Cannot determine from file list alone (no commit history, open issues, or PRs visible), but the presence of live builds (aeplay.org/citybound-livebuilds), active design docs, and Patreon funding suggests ongoing feature development. Build workflows are current (GitHub Actions setup).

Clone: git clone https://github.com/citybound/citybound.git && cd citybound. Install Rust via rustup. Install Node.js (package-lock.json present). Build: cargo build --release for server, then cd cb_browser_ui && npm install && cargo build --release --target wasm32-unknown-unknown for WebAssembly frontend. See CONTRIBUTING.md for full custom build process.

Daily commands: Build server: cargo build --release --bin citybound produces binary at target/release/citybound. Build UI in cb_browser_ui: npm install && cargo build --release --target wasm32-unknown-unknown then npm run build (exact script depends on package.json not fully shown). Run: ./target/release/citybound launches server; UI served at http://localhost (port inferred from rouille defaults).

• Cargo.toml — Root workspace configuration defining all member crates (cb_simulation, cb_planning, cb_util, cb_time) and the main binary entry point.
• cb_server/main.rs — Primary entry point for the Citybound server binary that orchestrates simulation, planning, and HTTP server initialization.
• cb_browser_ui/src/lib.rs — WASM bridge layer that connects the browser TypeScript UI to the Rust simulation engine via Kay actor system.
• cb_simulation/src/lib.rs — Core simulation engine using the Kay actor framework; defines microscopic simulation of agents, transport, and land use.
• cb_planning/src/lib.rs — City planning subsystem handling road networks, zoning, and construction state management.
• cb_browser_ui/src/citybound.tsx — Main React/TypeScript entry point for the browser UI; orchestrates all UI modes and canvas rendering.
• CONTRIBUTING.md — Documents the custom build process, development setup, and architectural patterns required for all contributors.

• Rouille HTTP Server (cb_server/main.rs) — Serves static assets (HTML, JS, WASM, images); handles game session creation and optional multi-

Add a new Planning UI tab/mode

1. Create a new React component in cb_browser_ui/src/[feature]_browser/, e.g. EconomyBrowser.tsx (cb_browser_ui/src/planning_browser/Planning.tsx)
2. Export Kay FFI binding from Rust via cb_browser_ui/src/[feature]_browser/kay_auto.rs (auto-generated or manual) (cb_browser_ui/src/planning_browser/kay_auto.rs)
3. Register the Rust FFI module in cb_browser_ui/src/[feature]_browser/mod.rs with Kay message handlers (cb_browser_ui/src/planning_browser/mod.rs)
4. Add mode case in cb_browser_ui/src/uiModes.tsx and wire to UI dispatcher (cb_browser_ui/src/uiModes.tsx)
5. Add menu icon and label in cb_browser_ui/src/menu.tsx or cb_browser_ui/src/toolbar.js (cb_browser_ui/src/menu.tsx)

Add a new Simulation actor/system

1. Create a new module directory in cb_simulation/src/[system]/ with mod.rs defining the actor struct and trait impl (cb_simulation/src/lib.rs)
2. Use Kay's #[derive(Actor)] macro and implement message handlers via impl Recipient<MyMessage> for MyActor (cb_simulation/src/lib.rs)
3. Register the actor in the Kay world initialization (typically in cb_simulation/src/lib.rs or the system's mod.rs) (cb_simulation/src/lib.rs)
4. Define simulation update tick dispatch in the time/event system to call your actor's message handler (cb_simulation/src/lib.rs)

Add a new road network planning feature

1. Extend road topology structures in cb_planning/src/construction/mod.rs or a new submodule (cb_planning/src/construction/mod.rs)
2. Add interaction handler in cb_browser_ui/src/planning_browser/transport_planning/RoadInteractables.tsx (cb_browser_ui/src/planning_browser/transport_planning/RoadInteractables.tsx)
3. Implement corresponding Kay message handler in cb_planning/src/construction/kay_auto.rs (cb_planning/src/construction/kay_auto.rs)
4. Update road rendering shaders in cb_browser_ui/src/planning_browser/transport_planning/RoadPlanningLayers.tsx (cb_browser_ui/src/planning_browser/transport_planning/RoadPlanningLayers.tsx)

• Rust + Kay actor system — Enables safe concurrent simulation of thousands of agents without data races; Kay provides message-passing primitives for decoupled actor communication.
• WASM (wasm-bindgen) — Allows high-performance Rust simulation to run in the browser without network latency; JavaScript cannot directly call Rust, so WASM bridging is essential.
• React + TypeScript — Provides type-safe UI framework for managing complex planning interactions and real-time state updates; familiar for web developers contributing UI.
• Three.js — WebGL abstraction for rendering 2.5D city geometry, roads, buildings, and agents with reasonable performance on mid-range hardware.
• Rouille HTTP server — Lightweight Rust web framework for serving assets and managing multi-player game state; minimal dependencies fit indie game philosophy.

• Client-side WASM simulation vs. server-side compute

  • Why: Browser-based WASM allows offline play and responsive local interactions; server can remain stateless or lightly coordinated for multi-player.
  • Consequence: Each player runs full simulation locally; multi-player synchronization may require custom reconciliation logic (not visible in current codebase snapshot).

• Kay actors as primary concurrency model

  • Why: Message-passing semantics avoid shared mutable state; Kay provides auto-generated network serialization for potential multi-player support.
  • Consequence: Learning curve for contributors unfamiliar with actor model; Kay-specific build macros add custom compilation overhead.

• Three.js for rendering instead of custom GPU pipeline

  • Why: Faster iteration on visual features; Three.js abstracts WebGL boilerplate.
  • Consequence: Higher memory footprint than raw WebGL; potential performance ceiling for very large cities.

• TypeScript for UI, Rust for simulation core

  • Why: Separates concerns: UI developers can iterate quickly in TypeScript; simulation engineers focus on algorithmic correctness in Rust.
  • Consequence: Requires discipline to maintain clean WASM boundary; cross-language debugging more complex.

• Server-authoritative multi-player (appears to be peer-to-peer or single-player focused based on codebase structure)
• Mobile/touch-native support (UI is desktop-centric with mouse/keyboard gestures)
• Real-time collaborative editing with conflict resolution (no evident CRDT or OT implementation)
• Procedural terrain generation (appears to use painted/designed landforms)

Web.toml in cb_browser_ui is non-standard Rust config (not Cargo.toml) — requires custom tooling or build script (build.rs present). rust-embed-flag dependency points to author's fork (https://github.com/aeickhoff/rust-embed) rather than upstream, possible divergence. cb_browser_ui excluded from workspace requires separate build step. WASM target wasm32-unknown-unknown must be installed: rustup target add wasm32-unknown-unknown. No visible .env or configuration file; may require hardcoded defaults or discovery.

• Entity-Component System (ECS) — Citybound's cb_simulation module is built on ECS for managing thousands of city entities (vehicles, buildings, citizens); understanding ECS is critical to extending game mechanics
• WebAssembly (WASM) — Entire Rust game engine compiles to WASM (target wasm32-unknown-unknown); required to understand deployment, performance, and browser-engine communication
• Collaborative Planning & Conflict Resolution — Multiplayer focus requires state synchronization and conflict resolution for concurrent edits (e.g., overlapping road placements); informs cb_planning module design
• Microscopic Traffic Simulation — Core game mechanic simulating individual vehicle behavior, routing, and congestion; cb_simulation implements agent-based simulation rather than macroscopic flow models
• WebSocket Multiplayer Protocol — Multiplayer synchronization runs over WebSocket between Rust server (rouille) and WASM client; essential for understanding real-time update flow
• Zoning & Urban Planning Algorithms — cb_planning module encodes city planning rules (residential, commercial, industrial zones); domain knowledge for extending planning features
• AGPL-3.0 License Implications — Project is copyleft; any modifications or networked deployment require source disclosure and same license, affecting hosting and commercial use

• opensimulators/opensim — Large-scale multiplayer simulation engine; architectural parallel for managing physics, entity state, and networked updates across many clients
• felixpalmer/final-form — Not directly related but represents modern form-handling patterns in TypeScript; relevant for any UI improvements to Citybound's planning/zoning interfaces
• linebender/druid — Rust UI toolkit; architectural reference for game UI design if Citybound ever shifts away from browser-based frontend
• amethyst/amethyst — Rust game engine with ECS architecture; design inspiration for Citybound's entity-component system (cb_simulation)
• mapbox/mapbox-gl-js — Web-based map rendering library; potential integration point if Citybound needs vector tile mapping or 3D terrain visualization

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for cb_browser_ui TypeScript/LESS build validation

The repo has .github/workflows/build.yml for Rust, but cb_browser_ui (TypeScript/LESS/WASM) has no automated build checks. With package.json, main.less, and .tsx files present, a new contributor could add a workflow to validate TypeScript compilation, LESS parsing, and WASM build steps (.github/workflows/browser-ui-build.yml). This catches regressions early and documents the browser UI build process.

• [ ] Create .github/workflows/browser-ui-build.yml targeting Node.js LTS
• [ ] Add steps to run npm ci in cb_browser_ui/
• [ ] Add TypeScript type-checking step (tsc --noEmit or equivalent)
• [ ] Add LESS compilation validation against cb_browser_ui/main.less
• [ ] Add WASM build step via cb_browser_ui/build.rs validation
• [ ] Ensure workflow runs on pull_request and push to main branch

Extract shared TypeScript utilities into cb_browser_ui/src/common/ module

The cb_browser_ui/src directory has scattered utilities (browser_utils/Utils.ts) mixed with feature modules (planning_browser/, households_browser/, land_use_browser/). These modules likely share common patterns for menu rendering, state management, and canvas interactions. A new contributor could identify and extract repeated logic into a dedicated cb_browser_ui/src/common/ directory with organized sub-modules, reducing duplication and improving maintainability.

• [ ] Audit existing modules: Planning.tsx, Households.js, LandUse.js for repeated patterns
• [ ] Create cb_browser_ui/src/common/ directory structure
• [ ] Extract menu/UI component patterns into cb_browser_ui/src/common/MenuUtils.ts
• [ ] Extract GestureCanvas.tsx logic into cb_browser_ui/src/common/CanvasBase.ts
• [ ] Create cb_browser_ui/src/common/index.ts to export shared utilities
• [ ] Update import paths in Planning.tsx, Households.js, LandUse.js to use common module

Add integration tests for cb_browser_ui WebAssembly communication with cb_server

The repo has a Rust server (cb_server/main.rs) and WASM-based UI (cb_browser_ui), but no visible tests validating the RPC/message protocol between them. The browser_utils/kay_auto.rs files suggest auto-generated message bindings. A new contributor could write integration tests in cb_browser_ui/tests/ that validate serialization/deserialization of key messages (planning updates, simulation state) sent between server and client.

• [ ] Create cb_browser_ui/tests/ directory structure
• [ ] Write tests validating message serialization for key entities (cities, roads, households)
• [ ] Test WASM message handler invocations against mock server responses
• [ ] Validate that kay_auto.rs-generated bindings correctly round-trip data
• [ ] Document expected message formats in CONTRIBUTING.md with examples
• [ ] Add test execution step to browser-ui-build.yml workflow

• Add unit tests for cb_util/src/ utilities — file structure shows no test visibility, exposing core helper functions to regression. Create a tests/ directory with basic integration tests for frequently-called utility functions.: No test coverage evident in file list; improves reliability before 1.0
• Document WASM build pipeline in CONTRIBUTING.md — add step-by-step guide for cb_browser_ui's Web.toml, rust-embed-flag fork, and copyWasm.js script. Include troubleshooting section for target wasm32-unknown-unknown not found.: Custom build system (Web.toml, custom fork) is non-obvious; documentation gap for new contributors
• Create TypeScript stubs/type definitions for cb_browser_ui's Camera.js (currently plain JavaScript) — add Camera.d.ts with Camera class, render(), and setPosition() signatures to improve IDE support and prevent type errors in citybound.tsx.: Mixed TypeScript/JavaScript in frontend reduces type safety; low-hanging improvement for code quality

• High · Outdated and Vulnerable Dependencies — Cargo.toml - [dependencies] section. The Cargo.toml file specifies several dependencies with known vulnerabilities: rouille 2.1.0 (HTTP server with unmaintained status), clap 2.32.0 (outdated CLI parser), and ctrlc 3.1.3 (older version). These dependencies may contain unpatched security vulnerabilities. The project also uses rust-embed-flag from a GitHub fork, which bypasses normal security review mechanisms. Fix: Update all dependencies to latest stable versions. Replace rouille with actively maintained alternatives like actix-web or axum. Use cargo-audit to identify and patch known vulnerabilities. Avoid using forks of crates from GitHub without thorough security review.
• High · AGPL-3.0 License Compliance Risk — LICENSE.txt, Cargo.toml. The project is licensed under AGPL-3.0, which requires that any modifications to the software and any software that links with it must also be released under AGPL-3.0 and source code must be provided to users. This creates significant compliance complexity, especially for private deployments or commercial use. Users/developers may unknowingly violate the license. Fix: Clearly document AGPL-3.0 obligations in CONTRIBUTING.md and README.md. Consider dual-licensing if proprietary use is desired. Implement REUSE compliance checking in CI/CD. Provide clear guidance on license compatibility with dependencies.
• High · Lack of Input Validation in Web UI — cb_browser_ui/src/planning_browser/*.tsx, cb_browser_ui/src/households_browser/. The TypeScript/React components in cb_browser_ui (Planning.tsx, GestureCanvas.tsx, etc.) handle user input for city simulation planning but there is no visible input sanitization or validation layer. Combined with potential use of dangerouslySetInnerHTML or eval-like patterns in JavaScript, this could enable XSS attacks. Fix: Implement comprehensive input validation for all user-provided data. Use security-focused libraries like DOMPurify for HTML sanitization. Avoid dangerouslySetInnerHTML; use safe DOM APIs instead. Implement Content Security Policy (CSP) headers. Add input bounds checking and type validation.
• Medium · Exposed Debug Configuration Files — .vscode/, .travis.yml, appveyor.yml. .vscode/launch.json, .vscode/settings.json, and .travis.yml, appveyor.yml are version controlled and may contain sensitive configuration information such as API keys, debug flags, or build credentials that could be exploited. Fix: Move sensitive configuration to environment variables or .gitignore. Use .env.example for template configurations. Rotate any exposed credentials immediately. Implement pre-commit hooks to prevent committing sensitive data. Use encrypted secrets in CI/CD pipelines only.
• Medium · Embedded Assets with Potential Integrity Issues — Cargo.toml - features section, cb_browser_ui/assets/. The project includes a feature flag 'embed_assets' and uses rust-embed-flag to embed assets at compile time. If malicious assets are injected or dependencies are compromised, the compiled binary could include malicious content without runtime detection. Fix: Implement file integrity verification for assets using checksums or signatures. Verify the integrity of all asset sources before embedding. Use a secure build environment. Consider runtime validation of critical assets. Document the asset supply chain.
• Medium · Insufficient HTTP Security Headers — cb_server/main.rs, rouille dependency. The rouille-based HTTP server (cb_server/main.rs) is likely not configured with essential security headers (CSP, X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security, etc.). This exposes the web UI to various attacks including clickjacking and content-type sniffing. Fix: Implement comprehensive security headers for all HTTP responses. Use middleware or wrapper functions to enforce CSP, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security (HSTS), and X-XSS-Protection. Consider using a reverse proxy (nginx) for additional security.
• Medium · No Apparent Authentication or Authorization — undefined. As a multiplayer game, the codebase provides no visible authentication mechanism to verify user identity or Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.