test(copilot): add dedicated test suite for Glossary OS Copilot

.gitignore

@@ -3,6 +3,7 @@ node_modules/
 
 # Build output
 dist/
+.next/
 
 # Environment variables
 .env
@@ -34,3 +35,9 @@ Thumbs.db
 # Logs
 *.log
 npm-debug.log*
+.vercel
+
+# Generated data expansion reports
+data/expansion/last-report.json
+data/expansion/fixture-report.json
+.env*.local

CONTRIBUTING.md

@@ -55,6 +55,34 @@ npm test        # Run test suite
 npm run build   # Verify build
 npm run lint    # Type check
 npm run validate # Check for duplicates and dangling refs
+npm run expand:data # Generate candidate/freshness report
+```
+
+## Data Expansion Workflow
+
+If you want to automate discovery of new terms or review terms that may need fresher definitions:
+
+1. Edit `data/expansion/sources.json`
+2. Add the Solana docs, repos, or blogs you want to watch
+3. Run:
+
+```bash
+npm run expand:data
+```
+
+4. Review `data/expansion/last-report.json`
+5. Turn good candidates into normal glossary PRs under `data/terms/*.json`
+
+The report contains:
+
+- `candidates`: phrases not already present in the glossary
+- `reviewCandidates`: existing terms that appear repeatedly in watched sources
+- `fetchFailures`: sources that could not be fetched
+
+For a no-network smoke test:
+
+```bash
+npm run expand:data:fixture
 ```
 
 ## PR Requirements

README.md

@@ -2,10 +2,47 @@
 
 [![npm version](https://img.shields.io/npm/v/@stbr/solana-glossary)](https://www.npmjs.com/package/@stbr/solana-glossary)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-![Terms](https://img.shields.io/badge/terms-1001-brightgreen)
+![Terms](https://img.shields.io/badge/terms-1004-brightgreen)
 ![Categories](https://img.shields.io/badge/categories-14-blue)
 
-**The most comprehensive Solana glossary ever built — 1001 terms, 14 categories, full cross-references, and i18n support. Packaged as an SDK.**
+**The most comprehensive Solana glossary ever built — 1004 terms, 14 categories, full cross-references, and i18n support. Packaged as an SDK.**
+
+## Apps Built on Top
+
+- [Glossary OS](./apps/glossary-os/README.md): a multilingual premium frontend for exploring the glossary as a hostable product.
+- Glossary OS also includes onboarding quizzes, builder paths, concept graphs, and AI-ready context handoff.
+
+## Data Expansion Tooling
+
+The repository also includes a lightweight expansion pipeline for discovering candidate terms and flagging existing entries for freshness review.
+
+What it does:
+
+- scans a manifest of watched Solana docs, repos, and blogs
+- extracts candidate phrases that are not already in the glossary
+- flags existing terms that appear repeatedly in watched sources
+- writes a JSON report that can be reviewed before opening a data PR
+
+Run the real manifest:
+
+```bash
+npm run expand:data
+```
+
+Run the local fixture:
+
+```bash
+npm run expand:data:fixture
+```
+
+Outputs:
+
+- `data/expansion/last-report.json`
+- `data/expansion/fixture-report.json`
+
+Source manifest:
+
+- `data/expansion/sources.json`
 
 ---
 
@@ -15,12 +52,13 @@ The original Solana Glossary was one of the most loved resources in the ecosyste
 
 Over time, it got absorbed into generic "Terminology" docs and lost its identity.
 
-**Superteam Brazil is bringing it back** — expanded from ~200 terms to 1001, structured as a proper npm package, and designed to actually ship value:
+**Superteam Brazil is bringing it back** — expanded from ~200 terms to 1004, structured as a proper npm package, and designed to actually ship value:
 
-- **Onboarding** — New devs get instant context on 1001 Solana concepts
+- **Onboarding** — New devs get instant context on 1004 Solana concepts
 - **Go deeper** — Seasoned devs explore cross-referenced technical relationships between terms
 - **Vibe coders** — AI-assisted builders can understand what's behind the abstractions
 - **Save tokens** — Feed glossary context to LLMs instead of burning tokens re-explaining Solana concepts every prompt
+- **Keep growing** — Data expansion tooling can surface new candidate terms and freshness reviews before a data PR lands
 
 ---
 
@@ -59,7 +97,7 @@ const results = searchTerms("account");
 const defiTerms = getTermsByCategory("defi");
 
 // Access everything
-console.log(`${allTerms.length} terms loaded`); // 1001
+console.log(`${allTerms.length} terms loaded`); // 1004
 ```
 
 ---
@@ -100,7 +138,7 @@ Returns all 14 category identifiers.
 
 ### `allTerms: GlossaryTerm[]`
 
-The complete array of all 1001 terms. Useful for building custom indexes or feeding to LLMs.
+The complete array of all 1004 terms. Useful for building custom indexes or feeding to LLMs.
 
 ---
 
@@ -109,13 +147,13 @@ The complete array of all 1001 terms. Useful for building custom indexes or feed
 | Category | Terms | Description |
 |----------|-------|-------------|
 | `core-protocol` | 86 | Consensus, PoH, validators, slots, epochs |
-| `programming-model` | 69 | Accounts, instructions, programs, PDAs |
+| `programming-model` | 70 | Accounts, instructions, programs, PDAs |
 | `token-ecosystem` | 59 | SPL tokens, Token-2022, metadata, NFTs |
 | `defi` | 135 | AMMs, liquidity pools, lending protocols |
 | `zk-compression` | 34 | ZK proofs, compressed accounts, Light Protocol |
-| `infrastructure` | 44 | RPC, validators, staking, snapshots |
+| `infrastructure` | 45 | RPC, validators, staking, snapshots |
 | `security` | 48 | Attack vectors, audit practices, reentrancy |
-| `dev-tools` | 64 | Anchor, Solana CLI, explorers, testing |
+| `dev-tools` | 65 | Anchor, Solana CLI, explorers, testing |
 | `network` | 58 | Mainnet, devnet, testnet, cluster config |
 | `blockchain-general` | 84 | Shared blockchain concepts |
 | `web3` | 80 | Wallets, dApps, signing, key management |
@@ -219,6 +257,7 @@ npm test        # Run tests
 npm run build   # Build package
 npm run lint    # Type check
 npm run validate # Check data integrity
+npm run expand:data # Generate candidate/freshness report
 ```
 
 ---

apps/.gitignore

@@ -0,0 +1 @@
+.vercel

apps/glossary-os/.env.example

@@ -0,0 +1,2 @@
+GEMINI_API_KEY=
+GEMINI_MODEL=gemini-2.5-flash

apps/glossary-os/.gitignore

@@ -0,0 +1,2 @@
+.vercel
+.env*.local

apps/glossary-os/PR.md

@@ -0,0 +1,79 @@
+# Glossary Copilot Test Suite
+
+## Suggested Title
+
+`test(copilot): add dedicated test suite for Glossary OS`
+
+## Suggested Base Branch
+
+- base: `feat/glossary-copilot`
+- compare: `feat/glossary-copilot-tests`
+
+## Summary
+
+This PR adds a dedicated automated test suite for Glossary Copilot inside `apps/glossary-os`. The suite makes Copilot quality visible and reviewable by covering its helper modules, API validation, and grounded answer flow with mocked Gemini responses. It currently runs **65 passing tests across 13 test files**. The goal is to make the existing Copilot implementation defensible without turning this PR into a broader feature rewrite.
+
+## What This PR Adds
+
+- a dedicated Vitest setup for `apps/glossary-os`
+- fixtures for Solana / Anchor code samples and common runtime errors
+- unit coverage for:
+  - concept detection
+  - domain classification
+  - error patterns
+  - response parsing
+  - prompt building
+  - glossary utilities
+- integration coverage for Copilot answer generation
+- contract coverage for `/api/copilot`
+
+## Test Result
+
+```text
+Test Files  13 passed (13)
+Tests       65 passed (65)
+```
+
+## What The Suite Covers
+
+- `src/lib/copilot.ts`
+- `src/lib/copilot/concept-detector.ts`
+- `src/lib/copilot/domain-classifier.ts`
+- `src/lib/copilot/error-patterns.ts`
+- `src/lib/copilot/prompt-builder.ts`
+- `src/lib/copilot/response-parser.ts`
+- `src/lib/glossary.ts`
+- `src/app/api/copilot/route.ts`
+
+## Screenshots
+
+### Local Test Run
+
+![Local Tests](./screenshots/screenshot_testes.png)
+
+### Copilot Workspace
+
+![Glossary Copilot Workspace](./screenshots/glossary-os-copilot-workspace.png)
+
+### Debug Flow
+
+![Glossary Copilot Debug](./screenshots/glossary-os-copilot-debug.png)
+
+### Generate Flow
+
+![Glossary Copilot Generate](./screenshots/glossary-os-copilot-generate.png)
+
+### Plan Flow
+
+![Glossary Copilot Plan](./screenshots/glossary-os-copilot-plan.png)
+
+## Validation
+
+```bash
+npm run test --workspace @stbr/glossary-os
+npm run typecheck:web
+```
+
+## Why This Matters
+
+Glossary Copilot is not just static UI. It depends on glossary context assembly, prompt shaping, API validation, and structured output handling. This PR makes those layers testable and repeatable. That gives reviewers and judges a concrete way to verify behavior instead of relying only on screenshots or manual demos.

apps/glossary-os/README.md

@@ -0,0 +1,128 @@
+## What This Iteration Adds
+
+**Making Glossary Copilot verifiable**.
+
+The app now includes a dedicated Vitest suite that covers the Copilot stack across:
+
+- **unit tests**
+  - concept detection
+  - domain classification
+  - error pattern matching
+  - response parsing
+  - prompt building
+  - context building
+  - glossary shared utilities
+- **integration tests**
+  - explain flow
+  - debug flow
+  - generate flow
+  - plan flow
+- **contract tests**
+  - `/api/copilot` input validation
+  - structured Copilot output handling
+
+Current test result:
+
+- **13 test files**
+- **65 passing tests**
+
+## Why The Test Suite Matters
+
+Glossary Copilot is not a static UI layer. It depends on:
+
+- glossary context assembly
+- code and text concept detection
+- mode-specific prompt construction
+- structured JSON parsing
+- API input validation
+- Gemini integration boundaries
+
+Without dedicated tests, regressions in those layers are easy to miss. This suite makes Copilot quality visible to maintainers, reviewers, and hackathon judges.
+
+## What The Suite Verifies
+
+The suite validates the current Copilot contract in this branch:
+
+- request validation in `/api/copilot`
+- grounded glossary context assembly for the current term
+- code-aware and question-aware context expansion
+- structured parsing helpers used by the Copilot stack
+- end-to-end Gemini request/response handling at the `fetch` boundary
+
+This keeps the PR scoped to **verification of the existing Copilot implementation**, instead of turning the test PR into a larger product refactor.
+
+## Copilot Flows Covered By The Suite
+
+The current test suite validates the Copilot logic behind these flows.
+
+### Tests
+
+![Local Tests](./screenshots/screenshot_testes.png)
+
+
+## Test Layout
+
+The suite lives in [`src/__tests__`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__):
+
+- [`fixtures/code-samples.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/fixtures/code-samples.ts)
+- [`fixtures/error-messages.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/fixtures/error-messages.ts)
+- [`fixtures/mock-gemini.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/fixtures/mock-gemini.ts)
+- [`unit/copilot/concept-detector.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/unit/copilot/concept-detector.test.ts)
+- [`unit/copilot/context-builder.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/unit/copilot/context-builder.test.ts)
+- [`unit/copilot/domain-classifier.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/unit/copilot/domain-classifier.test.ts)
+- [`unit/copilot/error-patterns.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/unit/copilot/error-patterns.test.ts)
+- [`unit/copilot/prompt-builder.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/unit/copilot/prompt-builder.test.ts)
+- [`unit/copilot/response-parser.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/unit/copilot/response-parser.test.ts)
+- [`unit/glossary/loader.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/unit/glossary/loader.test.ts)
+- [`integration/explain-action.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/integration/explain-action.test.ts)
+- [`integration/debug-action.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/integration/debug-action.test.ts)
+- [`integration/generate-action.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/integration/generate-action.test.ts)
+- [`integration/plan-action.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/integration/plan-action.test.ts)
+- [`contract/input-validation.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/contract/input-validation.test.ts)
+- [`contract/output-contracts.test.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__/contract/output-contracts.test.ts)
+
+## Local Setup
+
+From the repository root:
+
+```bash
+npm install
+npm run dev:web
+```
+
+## Gemini Setup
+
+Create `apps/glossary-os/.env.local`:
+
+```bash
+GEMINI_API_KEY=your_api_key_here
+GEMINI_MODEL=gemini-2.5-flash
+```
+
+`GEMINI_MODEL` is optional.
+
+The application uses Gemini through the server-side route:
+
+- `/api/copilot`
+
+The test suite does **not** require real Gemini calls. It mocks the `fetch` boundary.
+
+## Validation
+
+```bash
+npm run test --workspace @stbr/glossary-os
+npm run typecheck:web
+npm run build --workspace @stbr/glossary-os
+```
+
+## Main Files For This Iteration
+
+- [`src/lib/copilot.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/lib/copilot.ts)
+- [`src/lib/copilot/concept-detector.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/lib/copilot/concept-detector.ts)
+- [`src/lib/copilot/domain-classifier.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/lib/copilot/domain-classifier.ts)
+- [`src/lib/copilot/error-patterns.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/lib/copilot/error-patterns.ts)
+- [`src/lib/copilot/prompt-builder.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/lib/copilot/prompt-builder.ts)
+- [`src/lib/copilot/response-parser.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/lib/copilot/response-parser.ts)
+- [`src/app/api/copilot/route.ts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/app/api/copilot/route.ts)
+- [`src/__tests__`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/src/__tests__)
+- [`vitest.config.mts`](/home/paolla/repos/solana/solana-glossary/apps/glossary-os/vitest.config.mts)