Home

ga — GuitarAlchemist

Part of the GuitarAlchemist ecosystem, governed by Demerzel.

Overview

Guitar Alchemist

AI-augmented music theory and guitar learning platform — .NET 10 / C# 14 backend, F# DSL for music theory primitives, React 18 + Vite frontend, Aspire-orchestrated. Part of a four-repo ecosystem (ga + ix Rust ML + Demerzel governance + tars F# theory validator).

Agent-facing canonical docs: CLAUDE.md (~70 lines, breadcrumb-style) and AGENTS.md (full development guidelines).

Live demos

• Chatbot — music theory Q&A with skill-routed responses (chord voicings, modes, scales, voice-leading, circle of fifths, improvisation choices, …) and a live agentic trace.
• Inverse Kinematics — 3D anatomically-modeled left hand on a fretboard, MCP-controllable via window.__gaIK.
• Prime Radiant — 3D governance + solar system visualization with Demerzel AI overlay.
• Component test pages — fretboard, OPTIC-K embedding browser, nature simulations, more.

Development Guide

CLAUDE.md

Guitar Alchemist — .NET 10 / C# 14 + F# DSL + React frontend, Aspire orchestrated.

Note: AGENTS.md is auto-synced from this file by Scripts/sync-agents-md.ps1 (also called from .githooks/pre-commit). Edit CLAUDE.md; never edit AGENTS.md directly.

Build, test, verify

dotnet build AllProjects.slnx -c Debug                    # full build
dotnet test  AllProjects.slnx                             # full suite
pwsh Scripts/start-all.ps1 -Dashboard                     # start all services via Aspire
pwsh Scripts/start-all.ps1 -NoBuild -Dashboard            # daily dev restart (skip build)
pwsh Scripts/run-all-tests.ps1 -BackendOnly -SkipBuild    # backend-only suite (faster)
dotnet test --filter "FullyQualifiedName~<name>"           # single test

Verify before claiming success. dotnet build AllProjects.slnx -c Debug and dotnet test AllProjects.slnx must pass. Frontend: npm run build && npm run lint in ReactComponents/ga-react-components.

Architecture

Strict bottom-up five-layer model:

1. Core — GA.Core, GA.Domain.Core (pure primitives: Note, Interval, Fretboard)
2. Domain — GA.Business.Core, GA.Business.Config, GA.BSP.Core (logic, YAML, BSP)
3. Analysis — GA.Domain.Services (chord/scale analysis, voicing generation and analysis, voice leading, spectral)
4. AI/ML — GA.Business.ML (embeddings, vector search, RAG, OPTIC-K schema)
5. Orchestration — GA.Business.Core.Orchestration, GA.Business.Assets, GA.Business.Intelligence

Rule: AI code in layer 4 (GA.Business.ML). Orchestration in layer 5. Never in lower layers. Full layer map + conventions: docs/architecture/layers.md.

Apps live in Apps/: ga-server/GaApi (ASP.NET + SignalR + GraphQL), GaChatbot, ga-client (React + R3F), GaMusicTheoryLsp (F#), AllProjects.AppHost (Aspire).

Conventions

• C# 14 / .NET 10: <Nullable>enable</Nullable>, file-scoped namespaces with using inside, record for DTOs, primary constructors, [] collection expressions, System.Threading.Lock, zero-warnings policy.
• Railway-Oriented Programming: Services return Result<T,E> / Try<T> / Validation<T> / Option<T> from GA.Core.Functional. throw only at system boundaries.
• F# (GA.Business.DSL, GA.Business.Config): 4-space indent, [<CLIMutable>] on YAML records, PascalCase YAML keys, hardcoded fallback if YAML missing.
• Frontend: React 18, TypeScript strict, MUI v5 (sx prop only), R3F (no state in useFrame), no any.

OPTIC-K

240-dim musical embedding (OPTIC-K-v1.8). Canonical schema: Common/GA.Business.ML/Embeddings/EmbeddingSchema.cs — read TotalDimension and Version constants, do not hardcode. v1.8 (2026-04-19) added a 12-dim ROOT partition at slots 228–239 to carry root pitch class outside STRUCTURE, fixing invariant test #25 (91% of same-pitch-class-set cross-instrument voicings differed only by root). That is same-PC-set invariance (octave/voicing/instrument), not transposition invariance: STRUCTURE also carries a 12-dim pitch-class chroma, so a chord and its transposition have STRUCTURE cosine ≈0.5–0.8 (measured by Tools/GaStructureInvariance; only the ICV + cardinality sub-dims are T-invariant). Transposition-agnostic "same-shape" similarity uses the ICV path (IcvNeighborsSkill / Grothendieck), not the embedding. One-way door: never change dimension without coordinated re-index.

Planning & commits

• Ideas → BACKLOG.md → /feature skill → docs/plans/YYYY-MM-DD-<type>-<name>-plan.md. Archive: docs/archive/.
• Past fixes / learnings: docs/solutions/ (YAML frontmatter: module, tags, problem_type).
• Commits: Conventional (feat:, fix:, etc.). PR includes impact, Fixes #N, key test output, UI captures.
• Pre-commit hook (pwsh Scripts/install-git-hooks.ps1) enforces dotnet format + build.

Full CLAUDE.md