ga

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.

Architecture (breadcrumb)

Strict bottom-up five-layer model:

1. Core         — GA.Core, GA.Domain.Core (Note, Interval, Fretboard primitives)
2. Domain       — GA.Business.Core, GA.Business.Config, GA.BSP.Core (logic + YAML)
3. Analysis     — GA.Business.Core.Harmony, GA.Business.Core.Fretboard (voice leading, geometry, spectral)
4. AI / ML      — GA.Business.ML (embeddings, OPTIC-K, RAG, chatbot skills)
5. Orchestration — GA.Business.Core.Orchestration, GA.Business.Assets, GA.Business.Intelligence

Rule: AI code lives in layer 4. Orchestration in layer 5. Never in lower layers. Full layer map: docs/architecture/layers.md.

Key concepts

• OPTIC-K v1.8 — 240-dim musical embedding (124-dim compact form on disk). Schema constants in Common/GA.Business.ML/Embeddings/EmbeddingSchema.cs — read TotalDimension / Version, never hardcode. Changing dimension is a one-way door.
• Voicing-search RAG — chord-voicing lookup over OPTIC-K geometry, powering the chatbot's ChordVoicingsSkill and the typed MusicalQueryEncoder pipeline.
• Grothendieck δ — harmonic-distance metric between voicings, used by GrothendieckDeltaSkill and the fretboard shortest-path solver.

Build, test, verify

dotnet build AllProjects.slnx -c Debug                       # full build
dotnet test  AllProjects.slnx                                # full test suite
pwsh Scripts/start-all.ps1 -Dashboard                        # start everything via Aspire
pwsh Scripts/run-all-tests.ps1 -BackendOnly -SkipBuild       # faster backend-only loop
pwsh Scripts/start-dev.ps1                                   # GaApi on 5232 + Vite on 5176 with auto-restart

For frontend work: npm run build && npm run lint in ReactComponents/ga-react-components.

Local dev stack (default ports)

Service	Port	Purpose
GaApi (.NET)	5232	REST + GraphQL, mounts the chatbot at /chatbot/* via PathBase reverse-proxy
GaChatbot.Api (.NET)	5252	Skill-routed chatbot backend — runs side-by-side with GaApi
Vite (React)	5176	Frontend dev server with HMR
Aspire Dashboard	15001	Service health + traces

See reference_dev_stack_three_services for the three-service split and the cloudflared route configuration for demos.guitaralchemist.com.

AI discipline (Karpathy + Cherny)

Every code-touching turn applies six rules: think before coding · simplicity first · surgical changes · verifiable success criteria · frame problem before solution · instrument one-way doors. Session continuity uses the Cherny pattern: /digest writes state/digests/latest.md at breakpoints; /learnings captures surprises to docs/solutions/; /auto-optimize drives Cherny-style improvement loops per domain (chatbot-qa, embeddings, voicing-analysis).

CI enforces this in .github/workflows/karpathy-cherny-discipline.yml.

Multi-LLM review (load-bearing)

For music-theory / DI / parser / MCP changes, code review fans out to multiple LLMs in parallel: octo:droids:octo-code-reviewer + octo:droids:octo-security-auditor + (when available) octo:droids:octo-performance-engineer. This has caught 9+ real bugs in past chatbot-migration PRs that local tests missed. See docs/methodology/multi-llm-review.md.

Quality cadence

Daily CI workflows snapshot quality signals to state/quality/<domain>/YYYY-MM-DD.json: