HitTheKit is an open-source rhythm game for electronic drum kits. It helps
beginners understand what to hit and when through clear visual cues and short,
rewarding practice sessions instead of requiring traditional music notation.
-The repository contains a playable Unity vertical slice backed by an
-engine-independent, automatically tested hit-matching core.
+The playable Unity vertical slice is backed by an engine-independent,
+automatically tested hit-matching core.
-## Play, learn, and configure
+## What works today
| **Play** | **Learn** | **Configure** |
| --- | --- | --- |
-| Follow a perspective drum highway with timing judgments, score, combo, accuracy, pause and results. | Build coordination through a structured beginner curriculum, study speeds and mastery goals. | Discover and map an electronic kit through guided hits, review and sound-check flows. |
-| Keyboard on desktop; CoreMIDI electronic drums on macOS Apple Silicon. | Twelve playable first-semester lessons plus a visible second-semester roadmap. | Deterministic simulation remains available when no supported MIDI backend is present. |
+| Follow a perspective drum highway with timing judgments, results and three original visual environments. | Build coordination through 12 playable beginner lessons with study speeds and mastery goals. | Discover and map an electronic kit through guided hits, review and sound-check flows. |
+| Keyboard on desktop; CoreMIDI electronic drums on macOS Apple Silicon. | A second semester remains visible as a roadmap rather than simulated assessment. | Deterministic simulation remains available when no supported MIDI backend is present. |
-The same gameplay session supports three original visual environments—Arcade
-Neon, Concert Stage and Precision Grid—without changing the chart, clock or hit
-matching rules.
+The same gameplay session powers Play and Learn. Charts, the DSP song clock,
+hit matching and MIDI input are shared rather than reimplemented per mode.
## Project status
> [!IMPORTANT]
-> HitTheKit is an active pre-release project. Source code is available, but
-> there is no approved public `0.5.0` binary yet. Historical playtest builds are
-> unsupported. The first public package remains gated by signing,
-> notarization, clean-machine testing, hardware validation and legal review.
-> Initial publication is deliberately limited to source code and the project
-> website. Historical Git history, tags, releases and Unity player binaries are
-> not part of the public repository.
+> HitTheKit is an active pre-release project. This public repository distributes
+> source code and the website only. No Unity player binary is currently approved
+> for public distribution. Historical builds and private development history are
+> intentionally excluded.
| Capability | Current status |
| --- | --- |
-| Keyboard gameplay | macOS, Windows, and Linux |
+| Keyboard gameplay | macOS, Windows and Linux |
| Electronic-drum MIDI | macOS Apple Silicon through CoreMIDI |
| Learning path | 12 playable lessons; 12 more planned |
| Included music | Original rights-clean demo only |
| Public binary | Not yet approved for distribution |
-## Start here
+Current limitations and release gates are tracked in
+[SUPPORT.md](SUPPORT.md) and the
+[public-release checklist](docs/release/PUBLIC_RELEASE_CHECKLIST.md).
-- **Players and testers:** read [SUPPORT.md](SUPPORT.md) and the
- [current limitations](#current-limitations).
-- **Developers:** follow the [quick source setup](#quick-source-setup).
-- **Contributors:** read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a
- pull request; substantial external code is temporarily paused pending legal
- review of the contribution model.
-- **Project direction:** see [ROADMAP.md](ROADMAP.md) and
- [GOVERNANCE.md](GOVERNANCE.md).
-- **Support the project:** visit [GitHub Sponsors](https://github.com/sponsors/Codewriter90x)
- or read [FUNDING.md](FUNDING.md) for the funding boundary and current tiers.
+## Build from source
-## Why sponsor HitTheKit?
-
-HitTheKit combines deterministic rhythm-game timing, electronic-drum hardware
-integration, beginner-focused lesson design, and an original rights-clean
-presentation. Keeping that foundation public requires more than feature work:
-it also requires hardware testing, accessibility review, release validation,
-documentation, and original assets.
-
-Sponsorship helps fund:
-
-- reproducible testing across electronic-drum modules, MIDI devices, audio
- interfaces, and clean machines;
-- accessibility, localization, and beginner-friendly learning content;
-- original rights-clean visual and audio assets plus public documentation;
-- release engineering for future macOS distributions after every public gate
- is met; and
-- focused maintenance time for the open-source core and contributor support.
-
-Sponsorship does not buy feature priority, roadmap control, commercial-song
-rights, private GoMyRO access, or a commercial HitTheKit license.
-
-[**Sponsor HitTheKit on GitHub →**](https://github.com/sponsors/Codewriter90x)
-
-Prefer to help without spending money? Test the source build, report a
-sanitized hardware result, improve documentation, or pick a
-[`good first issue`](https://github.com/Codewriter90x/HitTheKit/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
-
-## Quick source setup
-
-Requirements: the .NET SDK selected by [`global.json`](global.json) and, for
-the game client, Unity `6000.5.6f1`.
+Requirements: the .NET SDK selected by [`global.json`](global.json) and Unity
+`6000.5.6f1` for the game client.
```shell
dotnet test HitTheKit.sln
@@ -116,342 +77,85 @@ optional CoreMIDI plug-in before testing a real electronic kit:
./scripts/build-coremidi-plugin-macos-arm64.sh
```
-## Current limitations
-
-- MIDI input is implemented only for macOS CoreMIDI; keyboard input remains
- available on the other desktop targets.
-- Windows and Linux player behavior is implemented but still needs formal
- clean-machine release-candidate validation.
-- Hardware compatibility is evidence-based and not universal; an unverified
- device can be mapped through the guided setup.
-- The bundled catalog contains only the original `Neon Circuit` demo. Players
- must provide their own rights-cleared local content.
-- `0.5.x` is a pre-release line, not a stable or supported commercial product.
-
-See the [public-release checklist](docs/release/PUBLIC_RELEASE_CHECKLIST.md) for
-the exact remaining gates.
-
-Third-party names are used only to describe compatibility. HitTheKit is not
-sponsored, endorsed or certified by Unity Technologies, Apple Inc. or any
-referenced hardware manufacturer. See [NOTICE](NOTICE),
-[TRADEMARKS.md](TRADEMARKS.md) and
-[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
-
-## Engine-independent core
+The generated Unity core DLL and native plug-in are intentionally ignored by
+Git. See the [development guides](docs/README.md#development-and-testing) for
+platform-specific setup, tests and clean-build expectations.
-The timing and hit-matching domain is implemented as a `netstandard2.1` class
-library so it can be tested without Unity while the Unity 6 runtime consumes the
-same deterministic implementation.
+## Architecture at a glance
```text
-src/HitTheKit.Core/ Domain models and hit matcher
-tests/HitTheKit.Core.Tests/ Automated timing tests
-examples/chart.json Minimal engine-independent chart
+src/HitTheKit.Core/ deterministic timing and hit matching
+src/HitTheKit.MidiTool/ offline MIDI inspection tooling
+src/HitTheKit.Unity/ Unity gameplay, learning and device setup
+native/ macOS CoreMIDI C ABI plug-in
+website/ dependency-free public website
+docs/ architecture, design, development and release guides
```
-Run the tests with:
+The core targets `netstandard2.1` and remains independent of Unity. Unity owns
+presentation and composition; native MIDI adapters feed the same normalized
+input boundary used by keyboard and simulated sources. Start with the
+[architecture map](docs/README.md#architecture).
-```shell
-dotnet test HitTheKit.sln
-./scripts/check-nuget-vulnerabilities.sh
-```
+## Documentation
-See [Unity integration](docs/architecture/unity-integration.md) for the active
-boundary between the core and the Unity project.
+The versioned [documentation hub](docs/README.md) is the single source of truth
+for technical documentation. It organizes:
-## Unity bootstrap
+- architecture and domain boundaries;
+- gameplay, learning and device-setup design;
+- MIDI, CoreMIDI and hardware validation;
+- development, tests and packaging;
+- release, legal and governance material.
-The Unity project is located at `src/HitTheKit.Unity` and uses Unity
-`6000.5.6f1`. Batch verification was performed with the Apple Silicon Editor.
-Install that Editor version and a .NET SDK compatible with `global.json`.
+Keeping documentation beside the code makes changes reviewable and prevents a
+separate Wiki from becoming stale.
-Before opening the project, build and synchronize the generated core assembly:
+## Contributing and support
-```shell
-./scripts/sync-core-to-unity.sh
-```
-
-For macOS CoreMIDI gameplay, also build the ABI v2 native plug-in (an older
-generated plug-in is rejected safely):
-
-```shell
-./scripts/build-coremidi-plugin-macos-arm64.sh
-```
-
-On Windows PowerShell, run:
-
-```powershell
-./scripts/sync-core-to-unity.ps1
-```
+- Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+- Use [GitHub Discussions](https://github.com/Codewriter90x/HitTheKit/discussions)
+ for ideas and questions.
+- Report reproducible problems through the
+ [issue templates](https://github.com/Codewriter90x/HitTheKit/issues/new/choose).
+- See [SECURITY.md](SECURITY.md) for private vulnerability reporting.
+- See [SUPPORT.md](SUPPORT.md) for supported environments and diagnostics.
-Then open `src/HitTheKit.Unity` in Unity Hub. The generated
-`Assets/Plugins/HitTheKit.Core/HitTheKit.Core.dll` is intentionally ignored by
-Git. Unity EditMode tests verify the timing settings conversion and call the
-real core matcher through that DLL. `HitTheKit.Core` remains independent of
-Unity. On macOS the gameplay scene can also consume the CoreMIDI runtime through
-the same normalized input boundary as the keyboard; zero or ambiguous devices
-remain a safe keyboard-only state.
-
-## Stage Command main menu
-
-The Unity application opens through an original real-time 3D concert stage:
-the drum kit sits in the foreground, six audience rows face it from beyond the
-riser, and truss lights, video walls, speaker stacks, haze, and subtle movement
-create venue depth behind the UI. The same scene reacts to Arcade Neon,
-Concert Stage, and Precision Grid settings and supports Reduced Motion. Its
-Blender source and procedural generator are versioned alongside the imported
-FBX; the former static artwork remains only as a safe fallback. The menu keeps
-three clear destinations: play the drum highway, enter the guided learning
-path, or configure an electronic drum kit. It is bilingual and keyboard
-navigable, and both Gameplay and Device Setup provide a route back to it. See
-the [menu flow](docs/design/main-menu-stage-command.md) and
-[3D stage design](docs/design/main-menu-3d-stage.md).
-
-The **Impara** destination now presents a school-style curriculum of 24 lessons
-across six modules. Its first semester is already playable: 12 progressive
-lessons move from a 64 BPM kick pulse through backbeat, timekeeping, rudimental
-coordination, fills, and a first sixteenth-note groove. Each lesson exposes a
-learning objective, sticking or groove pattern, suggested practice duration,
-three study speeds, and an end-of-module assessment. Passing requires 80%
-accuracy at full speed; 90% marks mastery. The second semester remains visibly
-planned rather than pretending to assess dynamics, sight-reading, or
-improvisation before those capabilities exist. See the
-[drum-school learning path](docs/design/beginner-learning-path.md).
-
-The **Gioca** destination opens a full-screen setlist before the shared gameplay
-scene. Entries are discovered from `Songs//song.json` folders, with a
-rights-clean bundled demo and a player-owned folder under Unity's persistent
-data path. `Neon Circuit` is immediately playable; `Local Song Example` shows
-the import boundary without naming or shipping third-party music. See the
-[folder-based song library](docs/development/song-library.md).
-
-Standalone builds persist lesson bests, completed-run results, and active
-practice time. The Settings panel reports the accumulated training duration
-and can export or import a versioned JSON backup for moving progress to another
-Mac. Countdown, pause, menus, results, and background time are excluded. See
-the [player-progress persistence contract](docs/architecture/player-progress-persistence.md).
-
-## DSP song-clock prototype
-
-The `GameplayPrototype` scene schedules the original 16-second “Neon Circuit”
-demo accompaniment, generated entirely in memory, and exposes its position on
-Unity's DSP timeline. Run the
-Core synchronization script above, open `src/HitTheKit.Unity` in Unity
-`6000.5.6f1`, open `Assets/HitTheKit/Scenes/GameplayPrototype.unity`, and press
-Play to hear the complete eight-bar demo. The accompaniment intentionally has
-no pre-rendered drum performance: drums are produced by player input, while a
-short muted cue identifies wrong or missed hits. No audio file is stored in the repository.
-
-This validates audio scheduling independently of player input and rendering.
-See
-[`docs/development/dsp-song-clock.md`](docs/development/dsp-song-clock.md) for
-the timing contract and test commands.
-
-## Versioned chart timeline
-
-The same scene loads the tracked `neon-circuit-demo-chart.json` TextAsset, validates
-the version 1 schema, and queries upcoming and elapsed notes against the DSP
-song position. See [`docs/development/chart-timeline.md`](docs/development/chart-timeline.md)
-for schema, timing boundaries, validation rules, and test instructions.
-
-## Selectable gameplay highway
-
-`GameplayPrototype` now turns the chart, DSP clock, and deterministic matcher
-into a complete rhythm-game highway. Eight readable targets cover Hi-Hat,
-Snare, two rack toms, Floor Tom, Crash, Ride, and a separate full-width
-Kick / Grancassa track. The same gameplay is available as Arcade Neon,
-Concert Stage, or Precision Grid. Choose the theme under **Settings** before
-starting a session; gameplay does not bind the `1`–`3` keys to presentation
-changes. All three directions are original HitTheKit art and UI, not copied
-assets from another rhythm game. See the
-[gameplay highway design](docs/design/gameplay-highway-themes.md).
-
-The playable vertical slice now includes a countdown, keyboard and CoreMIDI
-input, judgments, score, combo, accuracy, pause/restart, and a final rank/results
-screen. The generic GM mapping is a runtime fallback only and does not promote
-the HAMPBACK candidate profile.
-
-## Chart-driven pad visuals
-
-The legacy prototype layer still presents three simple 3D pads for Kick, Snare,
-and Hi-Hat beneath the new UI. Their color, emission, and scale are driven exclusively by upcoming
-chart notes: intensity increases as each effective note time approaches and
-returns to inactive as soon as the note is elapsed. The rendering uses a
-shared Built-in Pipeline material with per-renderer `MaterialPropertyBlock`
-values; it does not create material instances every frame.
-
-Run the Core synchronization script, open the scene, and press Play to see the
-generated fixture drive the pads. See
-[`docs/development/pad-visuals.md`](docs/development/pad-visuals.md) for the
-visual timing contract and test coverage.
-
-## Keyboard hit-matching prototype
-
-In Play mode, the keyboard supports the complete visual kit: `F` Kick, `J`
-Snare, `K` Hi-Hat, `G/H` rack toms, `L` Floor Tom, `D` Crash, and `S` Ride. The
-keyboard adapter timestamps each key-down against the DSP-backed song position
-and sends the normalized hit through the existing Core `HitMatcher`. Correctly
-timed hits briefly color the associated pad; unmatched input has a muted red
-flash, while expired notes are resolved as Miss without judgment text.
-
-Gameplay includes score, combo, per-hit early/late diagnostics, separate
-keyboard/MIDI calibration, persistent rebinding, generated pad feedback and
-CoreMIDI input on macOS. An optional persisted metronome follows the effective
-session BPM. After a completed session, the result screen suggests both a
-timing correction and the weakest kit piece to practice. See
-[`docs/development/keyboard-hit-matching.md`](docs/development/keyboard-hit-matching.md)
-for the runtime contract, offset handling, diagnostics, and test instructions.
-
-### Matcher semantics
-
-`HitMatcher.TryMatch` returns `false` when a hit has no eligible note. Wrong-pad
-and out-of-window hits do not resolve any note. `HitGrade.Miss` is emitted only
-when `TryMarkMissed` resolves an expired note.
-
-Timing uses this convention:
+Substantial external code contributions are temporarily paused while the
+project completes legal review of its contribution and licensing model.
-```text
-effectiveNoteTime = chartNoteTime + offsetSeconds
-delta = hitTime - effectiveNoteTime
-```
-
-Before matching, a saved source-specific calibration is applied as
-`calibratedHitTime = rawHitTime - inputOffsetSeconds`; positive values therefore
-compensate input that consistently arrives late. Keyboard and MIDI values are
-stored independently.
-
-A negative delta is early and a positive delta is late. Among unresolved notes
-on the hit pad and inside the hit window, the matcher selects the smallest
-absolute delta; a tie selects the earlier note. If time and pad are also equal,
-the original list order is preserved.
-
-Chart JSON uses stable lower-camel-case pad identifiers: `kick`, `snare`,
-`hiHat`, `tom1`, `tom2`, `floorTom`, `crash`, and `ride`. The Unity loader maps
-these identifiers explicitly; the core does not perform serialization.
-
-## Electronic-drum mapping foundation
-
-The Unity runtime now contains a device-independent foundation for describing
-electronic kits as versioned profiles and mapping raw MIDI-shaped data to
-logical kit pieces and articulations. A generic General MIDI profile provides
-an explicitly provisional starting point, and a pure C# wizard can build a
-separate user configuration for unknown or customized kits.
-
-On macOS, Unity opens CoreMIDI ports through the native HitTheKit plugin and the
-guided configuration screen discovers a device, lets the player choose a kit
-layout, illuminates each requested piece, captures repeated hits and persists
-the resulting mapping. Keyboard-only fallback remains available. Windows and
-Linux MIDI backends are not implemented, and no HAMPBACK model is claimed as
-fully supported; device profiles expand only from verified captures. See
-[`docs/architecture/electronic-drum-profiles.md`](docs/architecture/electronic-drum-profiles.md)
-and [`docs/development/kit-mapping-wizard.md`](docs/development/kit-mapping-wizard.md).
-
-## Player data and project governance
-
-HitTheKit stores preferences, mappings and progress locally and does not
-configure application telemetry. Read [PRIVACY.md](PRIVACY.md),
-[SECURITY.md](SECURITY.md), [CONTRIBUTING.md](CONTRIBUTING.md) and the
-[asset provenance register](docs/legal/ASSET_PROVENANCE.md). Original project
-code is offered under GPL-3.0-only; dependencies and the Unity runtime retain
-their own terms as recorded in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
-
-## Portable MIDI capture
-
-`HitTheKit.MidiCapture` is a self-contained macOS Apple Silicon command-line
-tool for collecting raw electronic-drum MIDI evidence on a lightweight Mac
-without Unity or an installed .NET runtime. It supports device diagnostics,
-live monitoring, resilient capture, guided exploratory steps, summaries,
-SHA-256 verification, deterministic ZIP packaging, and synthetic replay tests.
-
-The tool does not generate a device profile automatically and DryWetMIDI is not
-part of the Unity runtime. See
-[`docs/development/portable-midi-capture.md`](docs/development/portable-midi-capture.md)
-for publishing, MacBook-to-Mac-Studio transfer, privacy, and Gatekeeper notes.
-
-### HAMPBACK exploratory mapping
-
-The first integrity-verified HAMPBACK exploratory capture has been analyzed
-into a non-production candidate profile. It preserves per-step evidence,
-confidence, conflicts, and targeted recapture requirements. It is not
-auto-selected and does not claim definitive HAMPBACK support. Capture #2 is
-required to resolve Ride, choke, and continuous Hi-Hat ambiguities. See the
-[evidence report](docs/hardware/hampback/capture-001-evidence-report.md) and
-[targeted recapture plan](docs/hardware/hampback/capture-002-plan.md).
-
-## Device Setup UI
-
-`DeviceSetupPrototype` provides the UI Toolkit experience for selecting an
-electronic-drum device, choosing a kit structure, running the guided mapping
-wizard, reviewing conflicts, and testing a resulting configuration. On macOS,
-the same interfaces can consume real CoreMIDI discovery and capture; clean
-checkouts and non-macOS development retain deterministic simulation and
-keyboard fallback.
-
-The HAMPBACK exploratory profile is visible only as a Candidate: it remains
-not verified, not production-ready, not auto-selectable, and requires explicit
-confirmation. Real MIDI input is optional, macOS-only, and still under MVP
-validation. See the
-[UI design](docs/design/device-setup-ui.md) and
-[simulation guide](docs/development/device-setup-simulation.md).
-
-## Gameplay environments
-
-The playable highway includes three complete presentation environments:
-Arcade Neon, Concert Stage and Precision Grid. They use distinct stage art,
-perspective, note shapes and target composition while preserving the same
-chart, timing, keyboard/CoreMIDI input and scoring session. Switch between
-them from the main-menu settings; the selected environment is persisted and
-captured by the next gameplay session. See the
-[gameplay environment design](docs/design/gameplay-environments.md).
-
-## macOS CoreMIDI runtime
-
-An arm64 native plug-in provides macOS CoreMIDI discovery and timestamped input
-to guided setup and gameplay. It feeds a bounded queue that Unity polls on its
-main thread through the normalized input boundary. The generated plug-in is
-optional and ignored by Git; clean checkouts keep the deterministic simulated
-backend and keyboard fallback. This does not claim universal electronic-drum
-support. See the [runtime boundary](docs/architecture/macos-coremidi-runtime.md),
-[build guide](docs/development/coremidi-plugin-build.md), and [hardware smoke](docs/development/coremidi-hardware-smoke.md).
-
-## macOS playtest package
-
-An Apple-silicon standalone build can be created without committing generated
-artifacts:
-
-```bash
-./scripts/package-game-macos-arm64.sh 0.1.0
-```
+## Why sponsor HitTheKit?
-The resulting ZIP contains the complete game flow and CoreMIDI plug-in and does
-not require Unity on the destination Mac. See the
-[macOS playtest packaging guide](docs/development/macos-playtest-package.md) for
-validation and Gatekeeper notes.
+Keeping an open electronic-drum game healthy requires hardware testing,
+accessibility and localization work, release validation, documentation and
+original rights-clean assets—not only feature development.
-## Windows x64 playtest package
+Sponsorship helps fund:
-The release Mac can also create a keyboard-only Windows x64 playtest when Unity
-`6000.5.6f1` has Windows Build Support (Mono) installed:
+- testing across drum modules, MIDI devices, audio interfaces and clean machines;
+- beginner-friendly learning content and accessibility improvements;
+- original visual/audio assets and public documentation; and
+- focused maintenance of the open-source core and contributor support.
-```bash
-./scripts/package-game-windows-x64.sh 0.5.0
-```
+Sponsorship does not buy roadmap control, commercial-song rights, private
+product access or a commercial HitTheKit license.
-The package excludes the macOS CoreMIDI plug-in and states that MIDI is not yet
-implemented on Windows. It is currently unsigned and therefore intended for
-controlled testing, not public distribution. See the
-[Windows packaging and validation guide](docs/development/windows-playtest-package.md).
+[**Sponsor HitTheKit on GitHub →**](https://github.com/sponsors/Codewriter90x)
-## Licensing
+Prefer to help without spending money? Test a source build, report a sanitized
+hardware result, improve documentation or pick a
+[`good first issue`](https://github.com/Codewriter90x/HitTheKit/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
-HitTheKit's original source code is currently available under GPL-3.0-only. A
-possible dual-licensing model is being evaluated:
+## Licensing and content boundary
-- **Community:** GNU General Public License version 3 only (GPL-3.0-only).
-- **Commercial:** separate licensing is a future proposal for proprietary and
- closed-source integrations that require terms incompatible with the GPL. It
- is not currently offered or granted.
+Original project code is licensed under
+[GPL-3.0-only](LICENSE). A possible separate commercial-license path is under
+preparation and remains subject to legal review; see [LICENSING.md](LICENSING.md).
-Personal, educational, and commercial use is allowed under the GPL when its
-terms are respected. No separate commercial license is currently available.
-See [`LICENSING.md`](LICENSING.md) for the review status and intended boundary.
+The public repository does not include commercial songs, recordings, charts,
+lyrics or artwork. Third-party names describe compatibility only. HitTheKit is
+not sponsored, endorsed or certified by Unity Technologies, Apple Inc. or any
+referenced hardware manufacturer. See [NOTICE](NOTICE),
+[TRADEMARKS.md](TRADEMARKS.md),
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and
+[asset provenance](docs/legal/ASSET_PROVENANCE.md).
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..81b08fd
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,86 @@
+# HitTheKit documentation
+
+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.
+
+## Start here
+
+- [Root README](../README.md) — project overview and source setup
+- [Contributing](../CONTRIBUTING.md) — contribution workflow and current limits
+- [Support](../SUPPORT.md) — supported environments and diagnostic information
+- [Roadmap](../ROADMAP.md) — current priorities and public milestones
+- [Security](../SECURITY.md) — private vulnerability reporting
+
+## Architecture
+
+- [Unity integration](architecture/unity-integration.md)
+- [Gameplay session model](architecture/gameplay-session-model.md)
+- [Player progress persistence](architecture/player-progress-persistence.md)
+- [Electronic-drum profiles](architecture/electronic-drum-profiles.md)
+- [Device Setup boundaries](architecture/device-setup-boundaries.md)
+- [Capture-to-profile pipeline](architecture/capture-to-profile-pipeline.md)
+- [macOS CoreMIDI runtime](architecture/macos-coremidi-runtime.md)
+
+## Product and interaction design
+
+- [Beginner learning path](design/beginner-learning-path.md)
+- [Gameplay environments](design/gameplay-environments.md)
+- [Gameplay highway themes](design/gameplay-highway-themes.md)
+- [Main-menu flow](design/main-menu-stage-command.md)
+- [Main-menu 3D stage](design/main-menu-3d-stage.md)
+- [Device Setup UI](design/device-setup-ui.md)
+- [Kit configuration flow](design/kit-configuration-flow.md)
+
+## Development and testing
+
+- [DSP song clock](development/dsp-song-clock.md)
+- [Chart timeline](development/chart-timeline.md)
+- [Demo-song vertical slice](development/demo-song-vertical-slice.md)
+- [Keyboard hit matching](development/keyboard-hit-matching.md)
+- [Pad visuals](development/pad-visuals.md)
+- [Song library](development/song-library.md)
+- [Kit-mapping wizard](development/kit-mapping-wizard.md)
+- [Device Setup simulation](development/device-setup-simulation.md)
+- [Portable MIDI capture](development/portable-midi-capture.md)
+- [CoreMIDI plug-in build](development/coremidi-plugin-build.md)
+- [CoreMIDI hardware smoke test](development/coremidi-hardware-smoke.md)
+- [URP migration](development/urp-migration.md)
+
+## Packaging and release
+
+- [Public release checklist](release/PUBLIC_RELEASE_CHECKLIST.md)
+- [Publication runbook](release/PUBLICATION_RUNBOOK.md)
+- [Release process](release/RELEASE_PROCESS.md)
+- [0.5.0 release-notes draft](release/0.5.0-release-notes-draft.md)
+- [macOS playtest package](development/macos-playtest-package.md)
+- [macOS signing and notarization](development/macos-signing-notarization.md)
+- [Windows playtest package](development/windows-playtest-package.md)
+
+## Rights and governance
+
+- [Asset provenance](legal/ASSET_PROVENANCE.md)
+- [Dual-licensing readiness report](legal/dual-licensing-readiness-report.md)
+- [Dual-licensing decision record](governance/dual-licensing-decision.md)
+- [Commercial-license draft](legal/COMMERCIAL-LICENSE-DRAFT.md)
+- [Project governance](../GOVERNANCE.md)
+- [License](../LICENSE)
+- [Licensing overview](../LICENSING.md)
+- [Third-party notices](../THIRD_PARTY_NOTICES.md)
+- [Trademarks](../TRADEMARKS.md)
+
+## Community and launch material
+
+- [Launch kit](launch-kit/README.md)
+- [Community post draft](launch-kit/community-post.md)
+- [LinkedIn post draft](launch-kit/linkedin-post.md)
+- [GitHub Discussions](https://github.com/Codewriter90x/HitTheKit/discussions)
+- [Issue templates](https://github.com/Codewriter90x/HitTheKit/issues/new/choose)
+
+If a guide is missing or inaccurate, open a documentation issue or propose a
+small pull request. Avoid duplicating the same instructions in the root README,
+the website and this hub; link to the canonical guide instead.
diff --git a/tests/scripts/public-readiness-contract-tests.sh b/tests/scripts/public-readiness-contract-tests.sh
index cd3d049..c85d335 100755
--- a/tests/scripts/public-readiness-contract-tests.sh
+++ b/tests/scripts/public-readiness-contract-tests.sh
@@ -30,6 +30,7 @@ for path in \
NOTICE \
PRIVACY.md \
README.md \
+ docs/README.md \
ROADMAP.md \
SECURITY.md \
SUPPORT.md \
diff --git a/tests/scripts/website-localization-contract-tests.sh b/tests/scripts/website-localization-contract-tests.sh
new file mode 100644
index 0000000..5db4fed
--- /dev/null
+++ b/tests/scripts/website-localization-contract-tests.sh
@@ -0,0 +1,63 @@
+#!/bin/sh
+set -eu
+
+REPOSITORY_ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)
+cd "$REPOSITORY_ROOT"
+
+fail() {
+ echo "website localization contract: $*" >&2
+ exit 1
+}
+
+ITALIAN_PAGE=website/index.html
+ENGLISH_PAGE=website/en/index.html
+SCRIPT=website/assets/js/site.js
+SITEMAP=website/sitemap.xml
+
+for path in "$ITALIAN_PAGE" "$ENGLISH_PAGE" "$SCRIPT" "$SITEMAP"; do
+ [ -s "$path" ] || fail "required file is missing or empty: $path"
+done
+
+grep -Fq '' "$ITALIAN_PAGE" ||
+ fail "Italian page must declare the Italian locale"
+grep -Fq '' "$ENGLISH_PAGE" ||
+ fail "English page must declare the English locale"
+
+for page in "$ITALIAN_PAGE" "$ENGLISH_PAGE"; do
+ grep -Fq 'hreflang="it" href="https://codewriter90x.github.io/HitTheKit/"' "$page" ||
+ fail "$page is missing the Italian alternate"
+ grep -Fq 'hreflang="en" href="https://codewriter90x.github.io/HitTheKit/en/"' "$page" ||
+ fail "$page is missing the English alternate"
+ grep -Fq 'hreflang="x-default" href="https://codewriter90x.github.io/HitTheKit/en/"' "$page" ||
+ fail "$page is missing the global default alternate"
+done
+
+grep -Fq 'rel="canonical" href="https://codewriter90x.github.io/HitTheKit/"' "$ITALIAN_PAGE" ||
+ fail "Italian canonical URL is incorrect"
+grep -Fq 'rel="canonical" href="https://codewriter90x.github.io/HitTheKit/en/"' "$ENGLISH_PAGE" ||
+ fail "English canonical URL is incorrect"
+
+grep -Fq 'src="../assets/js/site.js"' "$ENGLISH_PAGE" ||
+ fail "English page does not load the shared script from its locale directory"
+grep -Fq 'href="../assets/css/styles.css"' "$ENGLISH_PAGE" ||
+ fail "English page does not load the shared stylesheet from its locale directory"
+
+grep -Fq 'getBrowserLanguage' "$SCRIPT" ||
+ fail "browser-language detection is missing"
+grep -Fq 'window.location.replace(routeForLanguage("en"))' "$SCRIPT" ||
+ fail "the first-visit English route is missing"
+grep -Fq 'saveLanguage(language)' "$SCRIPT" ||
+ fail "the explicit language preference is not persisted"
+
+ITALIAN_SITEMAP_COUNT=$(grep -Fc 'https://codewriter90x.github.io/HitTheKit/' "$SITEMAP")
+ENGLISH_SITEMAP_COUNT=$(grep -Fc 'https://codewriter90x.github.io/HitTheKit/en/' "$SITEMAP")
+[ "$ITALIAN_SITEMAP_COUNT" -eq 1 ] || fail "sitemap must contain the Italian URL exactly once"
+[ "$ENGLISH_SITEMAP_COUNT" -eq 1 ] || fail "sitemap must contain the English URL exactly once"
+
+README_LINES=$(wc -l < README.md | tr -d '[:space:]')
+[ "$README_LINES" -le 220 ] ||
+ fail "root README should remain a concise entry point (found $README_LINES lines)"
+grep -Fq '[documentation hub](docs/README.md)' README.md ||
+ fail "root README must link to the canonical documentation hub"
+
+echo "WEBSITE_LOCALIZATION_CONTRACTS_OK locales=it,en readme_lines=$README_LINES"
diff --git a/website/README.md b/website/README.md
index a326acc..c07f0a5 100644
--- a/website/README.md
+++ b/website/README.md
@@ -1,7 +1,8 @@
# HitTheKit website
-Static, dependency-free public website for HitTheKit. The production entry point
-is `index.html`; styles and behavior live under `assets/`.
+Static, dependency-free public website for HitTheKit. The Italian production
+entry point is `index.html`; the English entry point is `en/index.html`. Styles
+and behavior are shared under `assets/`.
Run a local preview from the repository root:
@@ -9,7 +10,14 @@ Run a local preview from the repository root:
python3 -m http.server 4173 --directory website
```
-Then open `http://127.0.0.1:4173/`.
+Then open `http://127.0.0.1:4173/` or
+`http://127.0.0.1:4173/en/`.
+
+The root remains the canonical Italian URL. On a first visit, browsers whose
+preferred language is not Italian are redirected to the stable English route.
+The language control remembers an explicit choice. Both pages publish
+canonical and reciprocal `hreflang` metadata, and both URLs are present in the
+sitemap.
Before publishing under a custom domain, update the canonical URL, Open Graph
image URL, `robots.txt`, and `sitemap.xml`.
diff --git a/website/assets/js/site.js b/website/assets/js/site.js
index 27d4a5e..33832e6 100644
--- a/website/assets/js/site.js
+++ b/website/assets/js/site.js
@@ -35,13 +35,27 @@ function getSavedLanguage() {
const value = localStorage.getItem("htk-lang");
if (value === "en" || value === "it") return value;
} catch {
- // Fall through to the browser preference when storage is unavailable.
+ // A private or locked-down browser may make storage unavailable.
}
+ return null;
+}
+
+function getBrowserLanguage() {
const browserLanguage = navigator.languages?.[0] || navigator.language || "";
return browserLanguage.toLowerCase().startsWith("it") ? "it" : "en";
}
+function saveLanguage(language) {
+ try { localStorage.setItem("htk-lang", language); } catch { /* storage can be unavailable */ }
+}
+
+function routeForLanguage(language) {
+ const suffix = `${window.location.search}${window.location.hash}`;
+ if (language === "en") return `en/${suffix}`;
+ return `../${suffix}`;
+}
+
function applyLanguage(language) {
const dictionary = copy[language];
document.documentElement.lang = language;
@@ -61,7 +75,6 @@ function applyLanguage(language) {
? "HitTheKit è il rhythm game open source per batteria elettronica: timing deterministico, lezioni progressive e supporto CoreMIDI su macOS."
: "HitTheKit is the open-source rhythm game for electronic drums: deterministic timing, progressive lessons, and CoreMIDI support on macOS.";
}
- try { localStorage.setItem("htk-lang", language); } catch { /* storage can be unavailable */ }
}
function setMenu(open) {
@@ -75,7 +88,9 @@ function setMenu(open) {
}
languageButton.addEventListener("click", () => {
- applyLanguage(document.documentElement.lang === "it" ? "en" : "it");
+ const language = document.documentElement.lang === "it" ? "en" : "it";
+ saveLanguage(language);
+ window.location.assign(routeForLanguage(language));
});
menuButton.addEventListener("click", () => {
@@ -131,4 +146,13 @@ if ("IntersectionObserver" in window) {
pageSections.forEach((section) => sectionObserver.observe(section));
}
-applyLanguage(getSavedLanguage());
+const pageLanguage = document.documentElement.dataset.locale === "en" ? "en" : "it";
+const preferredLanguage = getSavedLanguage() || getBrowserLanguage();
+
+// The root is the canonical Italian entry point. A first-time non-Italian
+// visitor is sent to the stable English route; direct /en/ visits remain stable.
+if (pageLanguage === "it" && preferredLanguage === "en") {
+ window.location.replace(routeForLanguage("en"));
+} else {
+ applyLanguage(pageLanguage);
+}
diff --git a/website/en/index.html b/website/en/index.html
new file mode 100644
index 0000000..9561b24
--- /dev/null
+++ b/website/en/index.html
@@ -0,0 +1,219 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ HitTheKit — Rhythm game for electronic drums
+
+
+
+
+ Skip to content
+
+
+
The rhythm game built for people who genuinely want to learn: precise timing, progressive lessons, and your electronic drum kit at the center of the experience.
Every hit passes through the same deterministic engine, whether you use a keyboard or a real MIDI kit.
+
+
+ 01
±
Deterministic timing
The hit-matching engine lives in a Unity-independent .NET library, with automated tests covering the judgment windows.
+ 02
●
Real electronic drums
Guided kit configuration, clear visual feedback for the requested piece, and an always-available keyboard fallback.
+ 03
↗
Structured curriculum
Progressive lessons with objectives, practice speeds, and transparent grading—not artificial difficulty.
+
+
+
1Connect or configure
+
2Choose a lesson or song
+
3Play and improve
+
+
+
+
+
+
+
+
+
02 / 07
+
ENVIRONMENTS
Three environments, one game
Change the visual language without changing timing, notes, or scoring.
+
+
+
THEME 01
Arcade Neon
A holographic runway, diamond notes, and a cyan-violet palette.
+
THEME 02
Concert Stage
A live arena viewed from behind a complete electronic kit.
+
THEME 03
Precision Grid
Technical geometry, a flat perspective, and maximum readability.
+
+
+
+
+
+
+
+
+
+
+
GUIDED PATH
+
24 lessons, six modules
+
The first semester is already playable: from a 64 BPM kick pulse to a full sixteenth-note groove. The second stays visible as a syllabus without pretending to grade capabilities the engine does not support yet.
+
12playable lessons
80%passing threshold
90%mastery
+
+
+
01
FundamentalsPlayable · lessons 1–4
READY
+
02
Basic techniquePlayable · lessons 5–8
READY
+
03
CoordinationPlayable · lessons 9–12
READY
+
04
Control and dynamicsPlanned
+
05
Musical stylesPlanned
+
06
Stage musicianPlanned
+
+
+
+
+
+
+
04 / 07
LIBRARY
Rights-clean music, verifiable charts
The repository does not distribute commercial music. It includes only an original demo and the boundary for player-owned content.
+
+
INCLUDED
Neon Circuit
Original demo · 8 bars · no prerecorded drums
▶
+ ＋
YOUR MUSIC
Local Song Example
An import-format example with no third-party content.
+
+
+
+
+
+
+
05 / 07
ROADMAP
Honest about what works today
The public status clearly separates playable features from work still in progress.
+
+ NOW · v0.5.x
Playable vertical slice
Complete keyboard gameplay
CoreMIDI on macOS
12 lessons and original demo
Guided kit configuration
+ NEXT
Broader support
MIDI backends for Windows and Linux
More verified drum-kit profiles
Second curriculum semester
Repeatable public packaging
+ LATER
Community ecosystem
Chart editing and validation
Rights-clean content sharing
More environments and practice modes
Broader hardware support
+
+
+
+
+
+
+
SOURCE PREVIEW
Study it, build it, contribute
The initial publication contains source and website only. No public Unity binary is approved yet; developers and testers can follow the documented build procedure.
The project's original code is distributed under GPL-3.0-only. A separate commercial-license path is being prepared and remains subject to legal review.
La prima pubblicazione contiene soltanto sorgenti e sito. Non è ancora disponibile un binario Unity pubblico approvato; sviluppatori e tester possono seguire la procedura di build documentata.
La prima pubblicazione contiene soltanto sorgenti e sito. Non è ancora disponibile un binario Unity pubblico approvato; sviluppatori e tester possono seguire la procedura di build documentata.
+ 
+ 
+