From 3e7f4fd35c14bcc114b03ded9024aab25ffd5f64 Mon Sep 17 00:00:00 2001 From: Rob Bos Date: Fri, 15 May 2026 11:09:15 +0200 Subject: [PATCH] docs: reorganize docs/ into categorized subdirectories - Create docs/adr/ for implementation notes and ADRs (5 files) - Create docs/features/ for per-feature documentation (10 files) - Rename IMPLEMENTATION_SUMMARY.md -> adr/LIGHT-THEME-SUPPORT.md for clarity - Keep 5 core reference docs at docs/ root - Rewrite docs/README.md as full categorized index covering all files - Add Documentation section to .github/copilot-instructions.md linking to index Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 13 +++ docs/README.md | 81 ++++++++++++++----- docs/{ => adr}/FLUENCY-DATA-IMPLEMENTATION.md | 0 .../IMPLEMENTATION-SUMMARY-SOCIAL-SHARE.md | 0 docs/{ => adr}/IMPLEMENTATION-SUMMARY.md | 0 .../LIGHT-THEME-SUPPORT.md} | 0 docs/{ => adr}/PR_SUMMARY.md | 0 docs/{ => features}/BLOB-UPLOAD-QUICKSTART.md | 0 docs/{ => features}/BLOB-UPLOAD.md | 0 docs/{ => features}/EXPORT_FEATURE_SUMMARY.md | 0 docs/{ => features}/EXPORT_FEATURE_UI.md | 0 .../FLUENCY-LEVEL-VIEWER-TEST-PLAN.md | 0 .../FLUENCY-LEVEL-VIEWER-UI-MOCKUP.md | 0 docs/{ => features}/FLUENCY-LEVEL-VIEWER.md | 0 docs/{ => features}/SOCIAL-MEDIA-SHARE.md | 0 docs/{ => features}/THEMING_CHANGES.md | 0 .../VISUAL-MOCKUP-SHARE-FEATURE.md | 0 17 files changed, 74 insertions(+), 20 deletions(-) rename docs/{ => adr}/FLUENCY-DATA-IMPLEMENTATION.md (100%) rename docs/{ => adr}/IMPLEMENTATION-SUMMARY-SOCIAL-SHARE.md (100%) rename docs/{ => adr}/IMPLEMENTATION-SUMMARY.md (100%) rename docs/{IMPLEMENTATION_SUMMARY.md => adr/LIGHT-THEME-SUPPORT.md} (100%) rename docs/{ => adr}/PR_SUMMARY.md (100%) rename docs/{ => features}/BLOB-UPLOAD-QUICKSTART.md (100%) rename docs/{ => features}/BLOB-UPLOAD.md (100%) rename docs/{ => features}/EXPORT_FEATURE_SUMMARY.md (100%) rename docs/{ => features}/EXPORT_FEATURE_UI.md (100%) rename docs/{ => features}/FLUENCY-LEVEL-VIEWER-TEST-PLAN.md (100%) rename docs/{ => features}/FLUENCY-LEVEL-VIEWER-UI-MOCKUP.md (100%) rename docs/{ => features}/FLUENCY-LEVEL-VIEWER.md (100%) rename docs/{ => features}/SOCIAL-MEDIA-SHARE.md (100%) rename docs/{ => features}/THEMING_CHANGES.md (100%) rename docs/{ => features}/VISUAL-MOCKUP-SHARE-FEATURE.md (100%) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7de5ea45..a34bf247 100644 --- a/.github/copilot-instructions.md +++ b/.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. diff --git a/docs/README.md b/docs/README.md index 3d459df5..7e50648d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ --- title: Documentation Index created: 2026-01-19 -updated: 2026-05-03 +updated: 2026-05-15 status: active type: reference tags: [documentation, index] @@ -9,35 +9,76 @@ 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 | diff --git a/docs/FLUENCY-DATA-IMPLEMENTATION.md b/docs/adr/FLUENCY-DATA-IMPLEMENTATION.md similarity index 100% rename from docs/FLUENCY-DATA-IMPLEMENTATION.md rename to docs/adr/FLUENCY-DATA-IMPLEMENTATION.md diff --git a/docs/IMPLEMENTATION-SUMMARY-SOCIAL-SHARE.md b/docs/adr/IMPLEMENTATION-SUMMARY-SOCIAL-SHARE.md similarity index 100% rename from docs/IMPLEMENTATION-SUMMARY-SOCIAL-SHARE.md rename to docs/adr/IMPLEMENTATION-SUMMARY-SOCIAL-SHARE.md diff --git a/docs/IMPLEMENTATION-SUMMARY.md b/docs/adr/IMPLEMENTATION-SUMMARY.md similarity index 100% rename from docs/IMPLEMENTATION-SUMMARY.md rename to docs/adr/IMPLEMENTATION-SUMMARY.md diff --git a/docs/IMPLEMENTATION_SUMMARY.md b/docs/adr/LIGHT-THEME-SUPPORT.md similarity index 100% rename from docs/IMPLEMENTATION_SUMMARY.md rename to docs/adr/LIGHT-THEME-SUPPORT.md diff --git a/docs/PR_SUMMARY.md b/docs/adr/PR_SUMMARY.md similarity index 100% rename from docs/PR_SUMMARY.md rename to docs/adr/PR_SUMMARY.md diff --git a/docs/BLOB-UPLOAD-QUICKSTART.md b/docs/features/BLOB-UPLOAD-QUICKSTART.md similarity index 100% rename from docs/BLOB-UPLOAD-QUICKSTART.md rename to docs/features/BLOB-UPLOAD-QUICKSTART.md diff --git a/docs/BLOB-UPLOAD.md b/docs/features/BLOB-UPLOAD.md similarity index 100% rename from docs/BLOB-UPLOAD.md rename to docs/features/BLOB-UPLOAD.md diff --git a/docs/EXPORT_FEATURE_SUMMARY.md b/docs/features/EXPORT_FEATURE_SUMMARY.md similarity index 100% rename from docs/EXPORT_FEATURE_SUMMARY.md rename to docs/features/EXPORT_FEATURE_SUMMARY.md diff --git a/docs/EXPORT_FEATURE_UI.md b/docs/features/EXPORT_FEATURE_UI.md similarity index 100% rename from docs/EXPORT_FEATURE_UI.md rename to docs/features/EXPORT_FEATURE_UI.md diff --git a/docs/FLUENCY-LEVEL-VIEWER-TEST-PLAN.md b/docs/features/FLUENCY-LEVEL-VIEWER-TEST-PLAN.md similarity index 100% rename from docs/FLUENCY-LEVEL-VIEWER-TEST-PLAN.md rename to docs/features/FLUENCY-LEVEL-VIEWER-TEST-PLAN.md diff --git a/docs/FLUENCY-LEVEL-VIEWER-UI-MOCKUP.md b/docs/features/FLUENCY-LEVEL-VIEWER-UI-MOCKUP.md similarity index 100% rename from docs/FLUENCY-LEVEL-VIEWER-UI-MOCKUP.md rename to docs/features/FLUENCY-LEVEL-VIEWER-UI-MOCKUP.md diff --git a/docs/FLUENCY-LEVEL-VIEWER.md b/docs/features/FLUENCY-LEVEL-VIEWER.md similarity index 100% rename from docs/FLUENCY-LEVEL-VIEWER.md rename to docs/features/FLUENCY-LEVEL-VIEWER.md diff --git a/docs/SOCIAL-MEDIA-SHARE.md b/docs/features/SOCIAL-MEDIA-SHARE.md similarity index 100% rename from docs/SOCIAL-MEDIA-SHARE.md rename to docs/features/SOCIAL-MEDIA-SHARE.md diff --git a/docs/THEMING_CHANGES.md b/docs/features/THEMING_CHANGES.md similarity index 100% rename from docs/THEMING_CHANGES.md rename to docs/features/THEMING_CHANGES.md diff --git a/docs/VISUAL-MOCKUP-SHARE-FEATURE.md b/docs/features/VISUAL-MOCKUP-SHARE-FEATURE.md similarity index 100% rename from docs/VISUAL-MOCKUP-SHARE-FEATURE.md rename to docs/features/VISUAL-MOCKUP-SHARE-FEATURE.md