feat(ai): add glossary-grounded action capabilities to Glossary Copilot

[paollacq]

Summary

This PR evolves Glossary Copilot from glossary-grounded Q&A into a glossary-grounded developer action layer. It adds four action modes on top of the existing glossary context engine: Code Explain, Debug Assistant, Code Generation, and Build / Learning Planner. Instead of using a generic chat flow, each mode dynamically assembles context from glossary relationships, mental models, builder paths, confusable concepts, and next-step terms before calling Gemini. The result is a more practical Solana development assistant built directly into Glossary OS.

What This PR Adds

• dedicated Copilot workspace at /[locale]/copilot
• inline Copilot access from term pages
• getMultiTermContext(terms) for action-oriented context composition
• Gemini-backed structured outputs for four modes:
  • Explain
  • Debug
  • Generate
  • Plan
• clickable glossary terms in answers
• linked next-step concepts in the output
• localized UI for en, pt, es

Feature 1: Code Explain

Input:

• Solana / Anchor / Rust code

Output:

• step-by-step explanation
• glossary concept mapping
• what the code does
• potential issues
• next concepts to learn

Implemented using:

• pattern-based concept detection
• glossary context expansion
• structured Gemini response

Real test used:

• Anchor PDA vault #[derive(Accounts)] example

Feature 2: Debug Assistant

Input:

• error message
• failing code
• or both

Output:

• problem
• why it happens
• glossary concepts involved
• fix
• improved code when possible

Implemented using:

• failure pattern matching
• glossary concept mapping
• context-grounded prompt

Real test used:

• Anchor seeds constraint PDA failure

Feature 3: Code Generation

Input:

• natural language request

Output:

• starter code
• explanation
• concept mapping
• implementation notes

Implemented using:

• intent extraction from request text
• glossary-driven concept selection
• structured generation prompt
• safer placeholders like REPLACE_WITH_YOUR_PROGRAM_ID

Real test used:

• “Create a PDA with Anchor for a user vault”

Feature 4: Build / Learning Planner

Input:

• developer goal in natural language

Output:

• goal breakdown
• concepts needed
• step-by-step plan
• implementation approach
• recommended next terms

Implemented using:

• domain detection for paths like Anchor, Runtime, DeFi, Agents
• builder path terms
• glossary use cases
• multi-term context assembly

Real test used:

• “I want to build a Solana DeFi app with swaps and liquidity”

Why This Is Useful

This makes the glossary directly actionable.

Instead of stopping at:

• term lookup
• static definitions
• concept browsing

the product now helps users:

• understand code
• debug failures
• generate starter implementations
• plan what to build and what to learn next

That is much closer to a real Solana builder workflow.

Why This Is Different

This is not:

• a generic chatbot
• a shallow LLM wrapper
• free-form prompt completion without knowledge constraints

This is:

• glossary-grounded
• context-first
• structured-output driven
• term-aware
• action-oriented

The system builds context from:

• current term
• aliases
• related terms
• confusable terms
• next-step terms
• mental models
• builder paths
• concept graph branches

For action modes, it expands into multi-term context so the LLM reasons across a small concept cluster instead of a single definition.

Routes

• /en/term/[slug] -> inline Copilot
• /pt/term/[slug] -> inline Copilot
• /es/term/[slug] -> inline Copilot
• /en/copilot -> Copilot workspace
• /pt/copilot -> Copilot workspace
• /es/copilot -> Copilot workspace

Gemini Setup

Create apps/glossary-os/.env.local:

GEMINI_API_KEY=your_api_key_here
GEMINI_MODEL=gemini-2.5-flash

Local Run

From the repository root:

npm install
npm run dev:web

Validation

npm run typecheck:web
npm run build --workspace @stbr/glossary-os