Model card: restore full README from GitHub, add commercial license option

README.md

@@ -15,3 +15,155 @@ tags:
 
 > Mirrored from [https://github.com/SNAPKITTYWEST/repoverse](https://github.com/SNAPKITTYWEST/repoverse) at commit `90d5c60`. Part of the **SnapKitty October 2026 main drop**.
 
+# Repoverse: engine-independent core
+
+This is the C# domain core of **SNAPKITTY REPOVERSE** (Master Directive, Part I). It turns GitHub
+repositories into a deterministic world manifest and a chunked voxel world. Open `Repoverse.sln` in Rider.
+
+```
+GitHub / local git ──► CanonicalRepository ──► Classifier ──► WorldManifest ──► WorldGenerator ──► Chunk ──► GreedyMesher
+   (Ingestion/)          (Model/)            (Generation/)   (Generation/)      (Voxels/)                   (Voxels/)
+```
+
+Nothing in `Repoverse.Core` depends on Unreal. The engine consumes the manifest and chunk data. It
+never becomes the source of truth (§5).
+
+## What is built and tested
+
+| Directive § | What exists | Where |
+|---|---|---|
+| 6 Canonical model | GitHub facts, kept separate from derived values; every derived value carries `Provenance` | `Model/` |
+| 25–27 Ingestion | GitHub REST client: `Link` pagination, ETag conditional requests with a disk cache, rate-limit detection, failures isolated per repo. Local-git ingester for offline use and monorepos | `Ingestion/GitHubIngest.cs`, `LocalGitIngest.cs` |
+| 27 Offline | Merges snapshots per repo. An empty or rate-limited refresh never replaces good data; unreached repos are kept and marked stale | `Ingestion/SnapshotStore.cs` |
+| 8 Seeds | FNV-1a and SplitMix64, stable across processes and platforms (`string.GetHashCode` is not) | `Generation/Seed.cs` |
+| 9–10, 80, 82–83 | Rule-based classifier with whole-word keyword scoring (purpose outweighs language), districts, archetypes, JSON overrides, landmarks | `Generation/Classifier.cs`, `Overrides.cs` |
+| 7, 85 Manifest | Deterministic manifest. Placement is sticky: existing buildings keep their plot when repos are added | `Generation/ManifestBuilder.cs` |
+| 78–79, 87–89 Interiors | Room graph built from the directory tree, with ignore rules (`node_modules`, `target`…) and semantic compression down to a room budget. Reachability is validated | `Generation/RoomGraph.cs` |
+| 11–12 Voxels | 16-bit packed voxels, 32³ chunks (64 KiB each). Interactive objects are entities, not voxels | `Voxels/Voxel.cs`, `BuildingRasterizer.cs` |
+| 11, 13 Streaming | Nearest-first async generation on the thread pool, bounded in-flight work, hysteresis unloading, cancellation. Player edits are stored apart from procedural state | `Voxels/ChunkStreamer.cs`, `WorldGenerator.cs` |
+| 14 Meshing | Greedy mesher with cross-chunk face culling and per-material draw groups | `Voxels/GreedyMesher.cs` |
+| 26, 32 Events | Typed events computed by diffing two snapshots (added, archived, release, activity, structure…) | `Simulation/WorldEvents.cs` |
+| 31 Clock | Fixed-step simulation clock, decoupled from frame rate: speed, pause, scheduling, spiral-of-death guard | `Simulation/SimulationClock.cs` |
+| 42–43 Saves | Versioned save of player state and edits, with a v1→v2 migration. Saves from a newer build are refused | `Persistence/SaveGame.cs` |
+| 76–77 URIs | `repoverse://owner/repo/path#L12`, `?room=`, `@x,y,z`; maps back to GitHub URLs | `RepoverseUri.cs` |
+
+There are 72 xUnit tests (`tests/`). They check behaviour, not constructors: determinism, sticky placement, no
+overlapping plots, room reachability found by flood-filling walkable air in the rasterized geometry, greedy
+quads covering exactly the visible faces, streaming memory bounded while travelling, edits surviving
+unload/reload, ETag cache hits, rate limits, partial failures, offline fallback, token redaction, save
+migration, and URI round-trips.
+
+## Run it
+
+Requires the .NET 8 SDK and git.
+
+```bash
+dotnet test
+# Offline: any git checkout works; --subprojects treats each top-level folder as a repo.
+git clone https://github.com/SNAPKITTYWEST/BOBS-Many-Voxel-Worlds.git ../BOBS-Many-Voxel-Worlds
+dotnet run --project src/Repoverse.Cli -- ingest-local ../BOBS-Many-Voxel-Worlds --owner SNAPKITTYWEST --subprojects --out out/snapshot.json
+dotnet run --project src/Repoverse.Cli -- generate --snapshot out/snapshot.json --out out/manifest.json
+dotnet run --project src/Repoverse.Cli -- stats --manifest out/manifest.json
+dotnet run --project src/Repoverse.Cli -- export-mesh --manifest out/manifest.json --out preview/world-mesh.json
+# then serve preview/ (e.g. `python3 -m http.server -d preview`) and open index.html?focus=snapkittywest/quantum-world
+
+# Live GitHub (token read from the environment, never stored):
+GITHUB_TOKEN=... dotnet run --project src/Repoverse.Cli -- ingest-github SNAPKITTYWEST --out out/snapshot.json
+```
+
+On the 15 sub-projects of `BOBS-Many-Voxel-Worlds`: 15 buildings, about 60 chunks generated in 30–40 ms,
+and about 170k visible faces meshed into about 7.2k quads (about 4% of naive).
+
+`preview/index.html` is a Three.js developer view of the exported mesh, used to check the generator by
+eye. It is not the game renderer.
+
+## Unified engine: compute kernels to WebAssembly
+
+`unified-engine/` is a JavaScript compiler that takes CUDA-style `__global__` kernels and turns them into
+WebAssembly, plus a host runtime that runs them. It needs Node 22+ and has no native dependencies.
+
+| Stage | Files |
+|---|---|
+| Lexer, parser → AST | `kernel/compiler/lexer.js`, `parser.js`, `kernel/ast/ast.js` |
+| AST → typed, structured IR (C scoping and conversions, short-circuit `&&`/`\|\|`) | `kernel/ir/lowering.js`, `kernel/ir/ir.js` |
+| IR → wasm binary (no external toolchain) | `wasm/modules/codegen.js`, `encoder.js`, `wasm/abi/abi.js` |
+| Shared memory, typed device buffers, `launch({grid, block})` | `wasm/runtime/runtime.js` |
+
+```bash
+cd unified-engine && npm ci && npm test   # 55 tests, including a particle-physics step
+```
+
+```js
+const runtime = new KernelRuntime();
+const add = await runtime.load(`__global__ void add(const float* A, const float* B, float* C, int N) {
+  int i = blockIdx.x * blockDim.x + threadIdx.x; if (i < N) C[i] = A[i] + B[i]; }`);
+const C = runtime.alloc('f32', n);
+add.launch({ grid: Math.ceil(n / 256), block: 256 }, runtime.upload(a), runtime.upload(b), C, n);
+C.read();
+```
+
+Limits: x dimension only, one kernel per module, no `__device__` functions, and no per-buffer bounds checks.
+The `test:lua`, `build:kernel` and `demo` scripts point at layers that are not written yet.
+
+## UNIFY: 2D engine runtime and demo game
+
+`unify/` is a C++17 2D game engine (renderer, physics, audio, input, animation, ECS, Lua 5.4 gameplay, save
+states, rollback buffer), with its own CUDA-like kernel compiler and WASM interpreter, and a small platformer in
+`unify/game/` that exercises all of it. It was merged here with its history kept (`git subtree`). See
+[`unify/README.md`](unify/README.md).
+
+```bash
+cd unify
+cmake -S . -B build -G Ninja
+cmake --build build
+ctest --test-dir build --output-on-failure   # 58 tests + the definition-of-done playtest
+./build/unify_game                           # SDL2 window if libsdl2-dev is installed, else --headless
+```
+
+This builds on Linux (GCC or Clang) and on Windows with MinGW-w64 GCC. MSVC is not supported. The Unreal backend in
+`unify/backends/unreal` has never been compiled.
+
+`unify/engine/kernel` + `unify/engine/wasm` and `unified-engine/` are two independent implementations of the
+same kernel → WASM idea (C++ with its own interpreter, and JavaScript running on the host's WebAssembly). They don't
+share code yet.
+
+## Not built yet
+
+These need tools this repository's CI and cloud sessions don't have. They are left out rather than stubbed (§2):
+
+- **Unreal / C++**: the engine project, the chunk-mesh upload (`ChunkMesh.Quads` maps directly onto
+  `UProceduralMeshComponent` or a RealtimeMesh), and Lumen/Nanite materials.
+- **Swift control plane** (§33–34) and the **CSS token layer** (§35) for in-engine UI.
+- **CAD import pipeline** (§24).
+- **Dependency extraction**: the `DependsOn` edges are modelled and rendered into the manifest, but not yet
+  parsed from `Cargo.toml`, `package.json` and similar files.
+- Parts II and III of the directive (agents, simulation, 388-repo scale, packaging).
+
+## Known limits
+
+- Classification is keyword and file-extension rules. `.v` counts as both Coq and Verilog. Ties
+  break by category order, and the provenance string shows when that happened. Use `overrides.json` for intent.
+- One floor plan (a corridor spine) for every archetype. Archetype-specific shells are future work.
+- The local ingester's "releases" are git tags, and only for whole-repo ingests.
+
+## SNAPKITTY game and Unreal host
+
+[Play/build guide](docs/SNAPKITTY-GAME.md) · [Unreal setup](unreal/README.md)
+
+The Unify launcher now opens an asset-backed SNAPKITTY menu, a playable Bifrost Runner level, and a read-only repository browser exported from the C# manifest. The same Lua game and artwork are wired into an Unreal host project. See the guides for verified native behavior and the Unreal compilation boundary.
+
+## 3D world bridge (engine validation pending)
+
+The C# sidecar and native Unreal district client are implemented in
+`src/Repoverse.Sidecar`, `src/Repoverse.Core/Bridge`, and the existing Unreal
+module. [Build instructions and exact validation boundary](docs/REPOVERSE-3D.md).
+The service is tested; the Unreal client still requires UBT compilation and a
+real editor playthrough. The older handoff task list remains historical context.
+
+---
+
+### 💼 Commercial License
+
+This repository is published without an open-source license; all rights are reserved. Building a commercial product or service? A **proprietary commercial license** from Snapkitty Collective LLC grants the rights to use, modify and ship this code.
+
+**[→ Get a commercial license](mailto:A.parr@belespritdaccord.uk?subject=Commercial%20license:%20repoverse)** · A.parr@belespritdaccord.uk