docs: reorganize docs/ into categorized subdirectories

.github/copilot-instructions.md

@@ -49,6 +49,19 @@ cd vscode-extension && npm run compile   # VS Code extension
 cd cli && npm run build                   # CLI
 ```
 
+## Documentation
+
+The `docs/` folder contains all project documentation. Start with the index:
+
+📖 **[docs/README.md](docs/README.md)** — Full categorized index of all documentation
+
+Key categories:
+- **Core Reference** — fluency scoring rules, data schemas, trackable metrics
+- **Component Docs** — per-component guides (`cli/`, `vscode-extension/`, `visual-studio/`, `sharing-server/`, `specs/`)
+- **Log File Schemas** — session log formats for all supported editors (`docs/logFilesSchema/`)
+- **Feature Docs** — per-feature documentation (`docs/features/`)
+- **ADRs** — implementation notes and architectural decisions (`docs/adr/`)
+
 ## Development Guidelines
 
 - **Minimal Changes**: Only modify files directly needed for the task. Avoid touching unrelated files.

docs/README.md

@@ -1,43 +1,84 @@
 ---
 title: Documentation Index
 created: 2026-01-19
-updated: 2026-05-03
+updated: 2026-05-15
 status: active
 type: reference
 tags: [documentation, index]
 ---
 
 # Documentation
 
-This directory contains documentation for the GitHub Copilot Token Tracker extension.
+This directory contains all documentation for the GitHub Copilot Token Tracker / AI Engineering Fluency project.
 
-## Fluency Score
+## Core Reference
 
-- **[FLUENCY-LEVELS.md](FLUENCY-LEVELS.md)** — Detailed scoring rules for the Copilot Fluency Score dashboard (stages, categories, thresholds)
+Essential reference documents covering the data model, scoring rules, and tracked metrics.
 
-## Log Files Schema Documentation
+| File | Description |
+|---|---|
+| [FLUENCY-LEVELS.md](FLUENCY-LEVELS.md) | Scoring rules for the Copilot Fluency Score (stages, categories, thresholds) |
+| [FLUENCY-METRICS-SCHEMA.md](FLUENCY-METRICS-SCHEMA.md) | Schema for fluency metrics stored in Azure Tables |
+| [TRACKABLE-DATA.md](TRACKABLE-DATA.md) | All metrics extractable from GitHub Copilot Chat session logs |
+| [USAGE-ANALYSIS.md](USAGE-ANALYSIS.md) | Guide to the Usage Analysis Dashboard features and tracked metrics |
+| [COPILOT-CLI-FORMAT-CHANGES.md](COPILOT-CLI-FORMAT-CHANGES.md) | Breaking changes to Copilot CLI session log format and their impact |
 
-For comprehensive documentation about Copilot session log file schemas, see:
+## Component Documentation
 
-📂 **[logFilesSchema/](logFilesSchema/)** - Complete schema documentation and analysis tools
+Per-component guides and READMEs.
 
-### Quick Links
+| Folder | Description |
+|---|---|
+| [cli/](cli/README.md) | CLI tool — commands, options, and development guide |
+| [vscode-extension/](vscode-extension/README.md) | VS Code extension guide |
+| [visual-studio/](visual-studio/README.md) | Visual Studio extension guide |
+| [sharing-server/](sharing-server/README.md) | Sharing server guide |
+| [specs/backend.md](specs/backend.md) | Backend API specification |
+| [specs/nonCopilotFilesDetection.md](specs/nonCopilotFilesDetection.md) | Non-Copilot file detection spec |
 
-- **[schema-analysis.md](logFilesSchema/schema-analysis.md)** - Quick reference guide
-- **[session-file-schema.json](logFilesSchema/session-file-schema.json)** - Manual schema documentation
-- **[session-file-schema-analysis.json](logFilesSchema/session-file-schema-analysis.json)** - Auto-generated analysis
-- **[gemini-cli-session-format.md](logFilesSchema/gemini-cli-session-format.md)** - Observed Gemini CLI JSONL session format on Windows
-- **[README.md](logFilesSchema/README.md)** - Detailed guide for working with schemas
-- **[vscode-variants.md](logFilesSchema/vscode-variants.md)** - VS Code variants support info
+## Log File Schemas
 
-### Quick Start
+Documentation and JSON schemas for Copilot session log file formats across different editors/tools.
+
+| File | Description |
+|---|---|
+| [logFilesSchema/README.md](logFilesSchema/README.md) | Guide for working with schemas and the analysis script |
+| [logFilesSchema/SCHEMA-ANALYSIS.md](logFilesSchema/SCHEMA-ANALYSIS.md) | Quick reference — field-level schema analysis |
+| [logFilesSchema/VSCODE-VARIANTS.md](logFilesSchema/VSCODE-VARIANTS.md) | VS Code variant support details |
+| [logFilesSchema/gemini-cli-session-format.md](logFilesSchema/gemini-cli-session-format.md) | Gemini CLI JSONL session format (Windows) |
+| [logFilesSchema/session-file-schema.json](logFilesSchema/session-file-schema.json) | Manual schema documentation (JSON) |
+| [logFilesSchema/session-file-schema-analysis.json](logFilesSchema/session-file-schema-analysis.json) | Auto-generated schema analysis (JSON) |
 
 ```powershell
-# Analyze current session files
+# Re-generate schema analysis
 .\.github\skills\copilot-log-analysis\analyze-session-schema.ps1
-
-# View results
-Get-Content docs\logFilesSchema\session-file-schema-analysis.json | ConvertFrom-Json
 ```
 
-See [logFilesSchema/SCHEMA-ANALYSIS.md](logFilesSchema/SCHEMA-ANALYSIS.md) for more information.
+## Feature Documentation
+
+Detailed documentation for individual features.
+
+| File | Description |
+|---|---|
+| [features/BLOB-UPLOAD.md](features/BLOB-UPLOAD.md) | Uploading session log files to Azure Blob Storage |
+| [features/BLOB-UPLOAD-QUICKSTART.md](features/BLOB-UPLOAD-QUICKSTART.md) | Quick-start guide for blob upload setup |
+| [features/EXPORT_FEATURE_SUMMARY.md](features/EXPORT_FEATURE_SUMMARY.md) | Export functionality for the Fluency Score dashboard |
+| [features/EXPORT_FEATURE_UI.md](features/EXPORT_FEATURE_UI.md) | Export feature UI layout and visual description |
+| [features/SOCIAL-MEDIA-SHARE.md](features/SOCIAL-MEDIA-SHARE.md) | Social media sharing (LinkedIn, Bluesky, Mastodon) |
+| [features/VISUAL-MOCKUP-SHARE-FEATURE.md](features/VISUAL-MOCKUP-SHARE-FEATURE.md) | Visual mockup of the social share UI |
+| [features/FLUENCY-LEVEL-VIEWER.md](features/FLUENCY-LEVEL-VIEWER.md) | Debug-only Fluency Level Viewer tool |
+| [features/FLUENCY-LEVEL-VIEWER-TEST-PLAN.md](features/FLUENCY-LEVEL-VIEWER-TEST-PLAN.md) | Test plan for the Fluency Level Viewer |
+| [features/FLUENCY-LEVEL-VIEWER-UI-MOCKUP.md](features/FLUENCY-LEVEL-VIEWER-UI-MOCKUP.md) | UI mockup for the Fluency Level Viewer |
+| [features/THEMING_CHANGES.md](features/THEMING_CHANGES.md) | Light theme support implementation details |
+
+## Architecture Decision Records (ADR)
+
+Implementation notes and decisions captured during development sessions.
+
+| File | Description |
+|---|---|
+| [adr/IMPLEMENTATION-SUMMARY.md](adr/IMPLEMENTATION-SUMMARY.md) | Fluency Level Viewer implementation summary |
+| [adr/LIGHT-THEME-SUPPORT.md](adr/LIGHT-THEME-SUPPORT.md) | Light theme support implementation summary |
+| [adr/IMPLEMENTATION-SUMMARY-SOCIAL-SHARE.md](adr/IMPLEMENTATION-SUMMARY-SOCIAL-SHARE.md) | Social media share feature implementation summary |
+| [adr/FLUENCY-DATA-IMPLEMENTATION.md](adr/FLUENCY-DATA-IMPLEMENTATION.md) | Fluency data cloud upload — gap analysis and plan |
+| [adr/PR_SUMMARY.md](adr/PR_SUMMARY.md) | PR summary: comprehensive light theme support |