Codewriter90x · Codewriter90x · Aug 19, 2026 · Aug 19, 2026
@@ -36,6 +36,8 @@ jobs:
         run: bash tests/scripts/public-readiness-contract-tests.sh
       - name: Validate website localization contracts
         run: bash tests/scripts/website-localization-contract-tests.sh
+      - name: Validate public Wiki contracts
+        run: bash tests/scripts/wiki-contract-tests.sh
       - name: Validate asset provenance hashes
         run: bash tests/scripts/asset-provenance-contract-tests.sh
       - name: Validate bundled song manifests

@@ -19,6 +19,7 @@
   <a href="https://codewriter90x.github.io/HitTheKit/en/">Website</a> ·
   <a href="#what-works-today">Experience</a> ·
   <a href="#build-from-source">Build from source</a> ·
+  <a href="https://github.com/Codewriter90x/HitTheKit/wiki">Wiki</a> ·
   <a href="docs/README.md">Documentation</a> ·
   <a href="ROADMAP.md">Roadmap</a> ·
   <a href="https://github.com/sponsors/Codewriter90x">Sponsor</a>
@@ -99,17 +100,21 @@ input boundary used by keyboard and simulated sources. Start with the
 
 ## Documentation
 
-The versioned [documentation hub](docs/README.md) is the single source of truth
-for technical documentation. It organizes:
+The [public Wiki](https://github.com/Codewriter90x/HitTheKit/wiki) is the
+beginner-friendly handbook for building, configuring and using HitTheKit. Its
+pages are generated from versioned sources under `docs/wiki/`.
+
+The versioned [documentation hub](docs/README.md) remains the source of truth
+for deeper technical documentation. It organizes:
 
 - architecture and domain boundaries;
 - gameplay, learning and device-setup design;
 - MIDI, CoreMIDI and hardware validation;
 - development, tests and packaging;
 - release, legal and governance material.
 
-Keeping documentation beside the code makes changes reviewable and prevents a
-separate Wiki from becoming stale.
+Keeping both documentation layers beside the code makes changes reviewable and
+prevents the rendered Wiki from becoming stale.
 
 ## Contributing and support
 

@@ -4,9 +4,11 @@ This directory is the canonical technical-documentation hub for HitTheKit.
 Documentation is versioned with the code so architectural and behavioral
 changes can be reviewed in the same pull request that introduces them.
 
-The GitHub Wiki is intentionally not used. Keeping one source of truth avoids
-stale copies, preserves history, supports local reading and makes broken links
-testable in CI.
+The [GitHub Wiki](https://github.com/Codewriter90x/HitTheKit/wiki) is the public,
+beginner-friendly handbook. Its pages are generated from the versioned sources
+in [`docs/wiki`](wiki/README.md). This hub remains canonical for deeper
+architecture and development material. That separation keeps the Wiki useful
+without creating an unreviewed second source of truth.
 
 ## Start here
 
@@ -15,6 +17,7 @@ testable in CI.
 - [Support](../SUPPORT.md) — supported environments and diagnostic information
 - [Roadmap](../ROADMAP.md) — current priorities and public milestones
 - [Security](../SECURITY.md) — private vulnerability reporting
+- [Public Wiki sources](wiki/README.md) — reviewed user-facing handbook
 
 ## Architecture
 

@@ -0,0 +1,51 @@
+# Build from Source
+
+## Validate the engine-independent projects
+
+```sh
+dotnet restore HitTheKit.sln
+dotnet test HitTheKit.sln --no-restore --configuration Release
+./scripts/check-nuget-vulnerabilities.sh
+```
+
+## Synchronize the Unity core
+
+```sh
+./scripts/sync-core-to-unity.sh
+```
+
+On Windows PowerShell:
+
+```powershell
+./scripts/sync-core-to-unity.ps1
+```
+
+The generated `HitTheKit.Core.dll` is intentionally ignored by Git. Run the
+sync command after a clean checkout and whenever the core changes.
+
+## Optional macOS CoreMIDI plug-in
+
+On Apple Silicon macOS:
+
+```sh
+./scripts/build-coremidi-plugin-macos-arm64.sh
+```
+
+The generated native plug-in is also ignored by Git. A missing or incompatible
+plug-in must fail safely to keyboard/simulated input.
+
+## Open Unity
+
+Use Unity `6000.5.6f1` and open `src/HitTheKit.Unity`. Run EditMode and PlayMode
+tests from the Unity Test Runner before submitting a change.
+
+## Canonical technical guides
+
+- [Unity integration](https://github.com/Codewriter90x/HitTheKit/blob/main/docs/architecture/unity-integration.md)
+- [CoreMIDI plug-in build](https://github.com/Codewriter90x/HitTheKit/blob/main/docs/development/coremidi-plugin-build.md)
+- [macOS packaging](https://github.com/Codewriter90x/HitTheKit/blob/main/docs/development/macos-playtest-package.md)
+- [Windows packaging](https://github.com/Codewriter90x/HitTheKit/blob/main/docs/development/windows-playtest-package.md)
+- [Release process](https://github.com/Codewriter90x/HitTheKit/blob/main/docs/release/RELEASE_PROCESS.md)
+
+Public player binaries are not currently approved. Building locally does not
+change that distribution boundary.
@@ -0,0 +1,37 @@
+# FAQ and Support
+
+## Do I need an electronic drum kit?
+
+No. Keyboard input is available on all current desktop source targets. A MIDI
+kit makes the experience closer to the physical instrument.
+
+## Does MIDI work on every operating system?
+
+Not yet. The production backend currently uses CoreMIDI on Apple Silicon macOS.
+Windows and Linux support keyboard gameplay but not production MIDI input.
+
+## Are commercial songs included?
+
+No. The repository contains original rights-clean material only. Player-owned
+authorized content remains local; see [[Local Songs]].
+
+## Can I download a ready-to-run build?
+
+No approved public Unity binary is currently distributed. The project is
+source-only while signing, clean-machine validation, hardware evidence and legal
+release gates remain open.
+
+## Where should I ask for help?
+
+- General question or idea: [GitHub Discussions](https://github.com/Codewriter90x/HitTheKit/discussions)
+- Reproducible bug: [issue forms](https://github.com/Codewriter90x/HitTheKit/issues/new/choose)
+- Hardware compatibility: use the hardware compatibility issue form
+- Security vulnerability: follow [SECURITY.md](https://github.com/Codewriter90x/HitTheKit/blob/main/SECURITY.md)
+
+Support is best-effort. There is no guaranteed response time, universal
+hardware promise or paid support contract. Read the canonical
+[support policy](https://github.com/Codewriter90x/HitTheKit/blob/main/SUPPORT.md)
+before attaching diagnostics.
+
+You can support continued open-source work through
+[GitHub Sponsors](https://github.com/sponsors/Codewriter90x).
@@ -0,0 +1,37 @@
+# Features
+
+## Play
+
+- perspective drum highway driven by the DSP song clock;
+- deterministic hit matching with early, late, good and perfect feedback;
+- keyboard input on desktop and CoreMIDI input on macOS Apple Silicon;
+- score, combo, accuracy, pause and results where supported by the active mode;
+- Arcade Neon, Concert Stage and Precision Grid visual environments.
+
+## Learn
+
+- 24-lesson curriculum across six modules;
+- 12 playable first-semester lessons;
+- study speeds and transparent pass/mastery thresholds;
+- original generated accompaniment without commercial recordings;
+- saved progress and active practice-time tracking in standalone builds.
+
+## Configure
+
+- device discovery through a normalized backend;
+- guided kit layout and mapping flow;
+- conflict/review states rather than silent guesses;
+- sound-check feedback;
+- deterministic simulated fallback when real MIDI is unavailable.
+
+## Music boundary
+
+The repository includes the original `Neon Circuit` demonstration only. It does
+not distribute commercial recordings, charts, lyrics or artwork. Player-owned,
+rights-cleared content remains local; see [[Local Songs]].
+
+## Not implemented everywhere
+
+MIDI production support currently targets macOS CoreMIDI. Windows and Linux
+source builds support keyboard gameplay but do not yet provide production MIDI
+backends. See [[Platforms and Limitations]].
@@ -0,0 +1,39 @@
+# Getting Started
+
+HitTheKit is currently a source-only pre-release. You need Unity to run the game
+from this public repository.
+
+## Requirements
+
+- Git
+- the .NET SDK selected by `global.json`
+- Unity `6000.5.6f1`
+- Unity Hub
+- macOS Apple Silicon only when testing the CoreMIDI plug-in
+
+## First run
+
+```sh
+git clone https://github.com/Codewriter90x/HitTheKit.git
+cd HitTheKit
+dotnet test HitTheKit.sln
+./scripts/sync-core-to-unity.sh
+```
+
+Open `src/HitTheKit.Unity` in Unity Hub with Unity `6000.5.6f1`, then open the
+project's main scene and enter Play Mode.
+
+Keyboard input is the safest first test and does not require MIDI hardware. On
+macOS Apple Silicon, follow [[MIDI and Device Setup]] before connecting a real
+kit.
+
+## What to try first
+
+1. Open the main menu.
+2. Choose **Play** and launch the original `Neon Circuit` demo.
+3. Try one of the 12 available lessons under **Learn**.
+4. Open **Configure** only when you are ready to map a MIDI kit.
+
+For platform-specific limitations, read [[Platforms and Limitations]]. For
+complete commands and generated-file boundaries, continue with
+[[Build from Source]].
@@ -0,0 +1,40 @@
+# HitTheKit Wiki
+
+![HitTheKit electronic drum kit on a neon concert stage](https://raw.githubusercontent.com/Codewriter90x/HitTheKit/main/website/assets/images/hitthekit-readme-hero.jpg)
+
+HitTheKit is an open-source rhythm game for learning electronic drums. It pairs
+a perspective note highway with progressive lessons, deterministic timing and
+guided kit configuration.
+
+> **Pre-release status:** the public project currently distributes source code
+> and the website only. No Unity player binary is approved for public
+> distribution yet.
+
+## Choose your path
+
+- **I want to understand the project:** [[Features]]
+- **I want to run it locally:** [[Getting Started]]
+- **I want the complete build steps:** [[Build from Source]]
+- **I want to configure an electronic drum kit:** [[MIDI and Device Setup]]
+- **I want to understand lessons and gameplay:** [[Learning and Gameplay]]
+- **I want to add my own authorized music:** [[Local Songs]]
+- **Something is not working:** [[Troubleshooting]]
+- **I have a general question:** [[FAQ and Support]]
+
+## Current headline capabilities
+
+| Area | Status |
+| --- | --- |
+| Keyboard gameplay | macOS, Windows and Linux source builds |
+| Electronic-drum MIDI | macOS Apple Silicon through CoreMIDI |
+| Learning path | 12 playable lessons; 12 more planned |
+| Included music | Original rights-clean demo only |
+| Public binaries | Not currently distributed |
+
+For architecture and contributor documentation, use the
+[technical documentation hub](https://github.com/Codewriter90x/HitTheKit/blob/main/docs/README.md).
+
+[Website](https://codewriter90x.github.io/HitTheKit/en/) ·
+[Source](https://github.com/Codewriter90x/HitTheKit) ·
+[Discussions](https://github.com/Codewriter90x/HitTheKit/discussions) ·
+[Sponsor](https://github.com/sponsors/Codewriter90x)
@@ -0,0 +1,37 @@
+# Learning and Gameplay
+
+Play and Learn use the same gameplay session, chart timeline, DSP clock, hit
+matcher and normalized input boundary. A lesson is not a second mock gameplay
+system.
+
+## Beginner curriculum
+
+The syllabus contains 24 lessons in six modules:
+
+| Module | Lessons | Current status |
+| --- | --- | --- |
+| Fundamentals | 1–4 | Playable |
+| Basic technique | 5–8 | Playable |
+| Coordination | 9–12 | Playable |
+| Control and dynamics | 13–16 | Planned |
+| Musical styles | 17–20 | Planned |
+| Stage musician | 21–24 | Planned |
+
+The playable path progresses from a kick pulse through backbeat, eighth-note
+timekeeping, rudiments, fills and a first sixteenth-note groove.
+
+## Study loop
+
+1. Read the objective and pattern.
+2. Prepare during the musical count-in.
+3. Study at a reduced speed when available.
+4. Perform at full speed.
+5. Review accuracy and timing feedback.
+6. Repeat or continue after the pass threshold.
+
+An 80% result at full speed passes a playable lesson; 90% marks mastery. Future
+lessons remain visibly planned whenever the engine cannot grade their defining
+skill honestly.
+
+For the complete curriculum rationale, see the
+[beginner learning path](https://github.com/Codewriter90x/HitTheKit/blob/main/docs/design/beginner-learning-path.md).
@@ -0,0 +1,43 @@
+# Local Songs
+
+HitTheKit does not bundle commercial music. You may use local content only when
+you own it or are otherwise authorized to use it.
+
+## Local folder
+
+The game discovers player-owned entries under:
+
+```text
+~/Documents/HTKSongs/
+```
+
+The directory is created automatically during discovery. Each direct child is
+one song and must contain a `song.json` manifest:
+
+```text
+HTKSongs/
+  my-song/
+    song.json
+    my-audio.ogg
+    my-chart.json
+```
+
+Paths in the manifest must remain relative to the song directory. Audio supports
+`.ogg` and `.wav`; charts use the existing versioned JSON schema. A playable
+binding needs authorized audio, a valid chart and timing metadata verified
+against that exact audio variant.
+
+## Metadata-only entries
+
+An entry with missing audio or unavailable charts may be visible in the catalog,
+but it must not launch, invent timing or fall back to another song. Unknown BPM,
+duration or difficulty stays unknown.
+
+## Content safety
+
+Do not commit or upload commercial audio, transcriptions, lyrics, artwork or
+download links to the public repository. Local paths and personal data must also
+remain outside tracked manifests.
+
+The full schema and precedence rules are documented in the
+[Song Library guide](https://github.com/Codewriter90x/HitTheKit/blob/main/docs/development/song-library.md).
@@ -0,0 +1,42 @@
+# MIDI and Device Setup
+
+## Current support
+
+Real electronic-drum input is implemented through CoreMIDI on Apple Silicon
+macOS. Keyboard and deterministic simulation remain available when the native
+plug-in or a compatible device is absent.
+
+## Prepare the plug-in
+
+```sh
+./scripts/build-coremidi-plugin-macos-arm64.sh
+./scripts/sync-core-to-unity.sh
+```
+
+Open the Unity project, enter **Configure**, refresh devices and select the
+intended endpoint explicitly.
+
+## Guided mapping
+
+1. Choose the active kit structure.
+2. Follow the requested instrument/pad prompt.
+3. Strike the requested surface consistently.
+4. Review ambiguous candidates or conflicts.
+5. Confirm required elements before finalizing.
+6. Use sound check to verify the resulting logical kit.
+
+The system must not silently promote uncertain input to a confirmed mapping.
+Unknown devices can be configured, but that does not make them officially
+verified profiles.
+
+## When a device is missing
+
+- confirm the module is powered and connected before refreshing;
+- close other software that may hold the MIDI endpoint;
+- verify the native plug-in was built for arm64;
+- test keyboard input to separate gameplay problems from MIDI problems;
+- include sanitized device/module information in a hardware report.
+
+Never upload credentials, personal paths, commercial audio or unsanitized MIDI
+captures. See [[Troubleshooting]] and the
+[hardware smoke guide](https://github.com/Codewriter90x/HitTheKit/blob/main/docs/development/coremidi-hardware-smoke.md).