[UPDATE PRIMITIVE] Rewrite static MCP resources as actionable LLM-oriented guides

.github/instructions/server_src_resources_md.instructions.md

@@ -0,0 +1,55 @@
+---
+applyTo: 'server/src/resources/**/*.md'
+description: 'Instructions for MCP server resource markdown files served to LLMs.'
+---
+
+# Copilot Instructions for `server/src/resources/**/*.md` resource files
+
+## PURPOSE
+
+This file contains instructions for working with markdown resource files in the `server/src/resources/` directory. These files are imported at build time (via esbuild's `.md: 'text'` loader) and served to LLMs through MCP resource endpoints (e.g., `codeql://server/overview`, `codeql://languages/go/ast`). Because LLMs consume these files as authoritative reference material, correctness and consistency are critical.
+
+## REQUIREMENTS
+
+- ALWAYS name resource files to match their MCP endpoint path. For example, a resource served at `codeql://server/overview` must be named `server-overview.md`, and a resource at `codeql://languages/go/ast` must be `languages/go_ast.md`.
+- ALWAYS start each resource file with a `#`-level (H1) heading that identifies the resource topic and scope.
+- ALWAYS use the v2 module-based DataFlow/TaintTracking API (`module MyConfig implements DataFlow::ConfigSig` with `TaintTracking::Global<MyConfig>`) in all CodeQL code examples. NEVER use the deprecated v1 class-based API (`class MyConfig extends TaintTracking::Configuration` with `override predicate`).
+- ALWAYS use `codeql-pack.yml` (not `qlpack.yml`) as the pack configuration filename in all code examples and references.
+- ALWAYS ensure any new resource file has a corresponding import and registration in `server/src/types/language-types.ts` (for language-specific resources) or `server/src/lib/resources.ts` (for general resources), and that the test expectations in `server/test/src/resources/` are updated accordingly.
+- ALWAYS verify ASCII art diagrams have consistent box corners and formatting.
+- ALWAYS ensure code examples are syntactically correct — class names, constructor names, and predicate names must all match (e.g., a class named `FooAsSink` must have a constructor named `FooAsSink()`).
+- **ALWAYS run `npm run build-and-test` from the repo root directory and ensure it passes completely before committing any changes.**
+
+## PREFERENCES
+
+- PREFER actionable, tool-oriented content that tells an LLM exactly which MCP tools and prompts to invoke and in what order, over abstract descriptions.
+- PREFER concrete code examples over prose explanations for CodeQL patterns and idioms.
+- PREFER a single authoritative location for each piece of documentation — if content exists in a resource file, repo-level docs should reference it rather than restate it.
+
+## DOCUMENTATION RELATIONSHIP: `server/src/resources/` ↔ `docs/ql-mcp/`
+
+The `server/src/resources/server-*.md` files are the **authoritative source** for MCP server tools, prompts, and queries documentation. The `docs/ql-mcp/*.md` files are **thin wrappers** that link to these authoritative sources.
+
+### When to update which file
+
+| Change type                                  | Update `server/src/resources/server-*.md` | Update `docs/ql-mcp/*.md`              |
+| -------------------------------------------- | ----------------------------------------- | -------------------------------------- |
+| Add, remove, or modify an MCP tool           | YES — `server-tools.md`                   | Only if monitoring tools table changes |
+| Add, remove, or modify an MCP prompt         | YES — `server-prompts.md`                 | NO — wrapper links to resource file    |
+| Add or remove a language resource            | YES — registration in source code         | YES — update language table            |
+| Add or remove a static resource              | YES — resource file + registration        | YES — update static resources table    |
+| Change a resource URI or endpoint path       | YES — rename file to match new path       | YES — update URI references            |
+| Fix a typo or improve wording in tool/prompt | YES — resource file only                  | NO — wrapper inherits the fix          |
+
+### Rules
+
+- ALWAYS update the authoritative `server/src/resources/server-*.md` file first, then verify the `docs/ql-mcp/*.md` wrapper still links correctly.
+- ALWAYS keep `docs/ql-mcp/*.md` as thin wrappers — they should contain only a brief overview, a link to the authoritative resource file, and any content that is NOT served via MCP (e.g., the optional monitoring tools table in `docs/ql-mcp/tools.md`).
+- NEVER duplicate detailed tool, prompt, or resource descriptions in both `server/src/resources/` and `docs/ql-mcp/`. The `docs/ql-mcp/` file must defer to the resource file for all MCP-served content.
+
+## CONSTRAINTS
+
+- NEVER leave any trailing whitespace on any line.
+- NEVER include placeholder or TODO content in resource files — if a resource is not ready, exclude it from registration until the content is complete.
+- NEVER reference deprecated or removed MCP tools in resource files. When a tool is deprecated, remove all mentions from resource files.
+- NEVER mix deprecated and current API patterns in code examples within the same file or across files in this directory.

docs/ql-mcp/prompts.md

@@ -6,45 +6,6 @@
 
 The server provides **11 prompts** that guide AI assistants through common CodeQL development workflows. Each prompt is backed by a `*.prompt.md` file containing structured instructions.
 
-## Prompt Reference
+> **Authoritative reference**: The MCP-served resource at `codeql://server/prompts` ([`server/src/resources/server-prompts.md`](../../server/src/resources/server-prompts.md)) is the canonical documentation for prompts. Update that file when adding, removing, or changing any prompt.
 
-| Prompt                                    | Description                                                                                                          |
-| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `document_codeql_query`                   | Create or update documentation for a CodeQL query                                                                    |
-| `explain_codeql_query`                    | Generate a detailed explanation of a CodeQL query for workshop learning content                                      |
-| `ql_lsp_iterative_development`            | Iterative CodeQL query development using LSP tools for completion, navigation, and validation                        |
-| `ql_tdd_advanced`                         | Advanced test-driven CodeQL development with AST visualization, control flow, and call graph analysis                |
-| `ql_tdd_basic`                            | Test-driven CodeQL query development checklist — write tests first, implement query, iterate until tests pass        |
-| `run_query_and_summarize_false_positives` | Run a CodeQL query and summarize its false positives                                                                 |
-| `sarif_rank_false_positives`              | Analyze SARIF results to identify likely false positives in CodeQL query results                                     |
-| `sarif_rank_true_positives`               | Analyze SARIF results to identify likely true positives in CodeQL query results                                      |
-| `test_driven_development`                 | Test-driven development workflow for CodeQL queries using MCP tools                                                  |
-| `tools_query_workflow`                    | Guide for using built-in tools queries (PrintAST, PrintCFG, CallGraphFrom, CallGraphTo) to understand code structure |
-| `workshop_creation_workflow`              | Guide for creating CodeQL query development workshops from production-grade queries                                  |
-
-## Prompt Categories
-
-### Test-Driven Development
-
-- **`ql_tdd_basic`** — Covers the core TDD loop: write test cases, implement the query, run tests, iterate.
-- **`ql_tdd_advanced`** — Extends basic TDD with AST visualization, control flow graph analysis, and call graph exploration.
-- **`test_driven_development`** — End-to-end TDD workflow using MCP tools for each step.
-
-### Code Understanding
-
-- **`tools_query_workflow`** — Uses PrintAST, PrintCFG, CallGraphFrom, and CallGraphTo tool queries to explore how source code is represented in a CodeQL database.
-- **`explain_codeql_query`** — Produces verbal explanations and Mermaid evaluation diagrams for a given query.
-
-### Iterative Development
-
-- **`ql_lsp_iterative_development`** — Combines LSP completions, go-to-definition, and diagnostics for an interactive development loop.
-
-### Documentation and Quality
-
-- **`document_codeql_query`** — Generates standardized markdown documentation as a sibling file to a query.
-- **`run_query_and_summarize_false_positives`** — Runs a CodeQL query on a database and groups results into false-positive categories by root cause.
-- **`sarif_rank_false_positives`** / **`sarif_rank_true_positives`** — Help assess query precision by ranking SARIF results.
-
-### Workshop Creation
-
-- **`workshop_creation_workflow`** — Guides the creation of multi-exercise workshops that teach CodeQL query development.
+For the complete prompt reference (all 11 prompts with descriptions and categories), see [`server/src/resources/server-prompts.md`](../../server/src/resources/server-prompts.md).

docs/ql-mcp/resources.md

@@ -4,16 +4,20 @@
 
 ## Overview
 
-The server exposes **4 static learning resources** and a set of **dynamic per-language resources** that supply AI assistants with CodeQL reference material. Resources are read-only and backed by `*.prompt.md` files bundled with the server.
+The server exposes **8 static resources** and a set of **dynamic per-language resources** that supply AI assistants with CodeQL reference material. Resources are read-only and backed by `.md` files bundled with the server.
 
 ## Static Resources
 
-| Resource                    | URI                                 | Description                                         |
-| --------------------------- | ----------------------------------- | --------------------------------------------------- |
-| CodeQL Getting Started      | `codeql://learning/getting-started` | Comprehensive introduction to CodeQL for beginners  |
-| CodeQL Query Basics         | `codeql://learning/query-basics`    | Learn the fundamentals of writing CodeQL queries    |
-| CodeQL Security Templates   | `codeql://templates/security`       | Ready-to-use security query templates               |
-| CodeQL Performance Patterns | `codeql://patterns/performance`     | Best practices for writing efficient CodeQL queries |
+| Resource                       | URI                                         | Description                                                                       |
+| ------------------------------ | ------------------------------------------- | --------------------------------------------------------------------------------- |
+| CodeQL Query Basics            | `codeql://learning/query-basics`            | QL query writing reference: syntax, metadata, patterns, testing                   |
+| CodeQL Test-Driven Development | `codeql://learning/test-driven-development` | TDD theory and workflow for developing CodeQL queries                             |
+| CodeQL Performance Patterns    | `codeql://patterns/performance`             | Performance profiling and optimization for CodeQL queries                         |
+| CodeQL Server Overview         | `codeql://server/overview`                  | MCP server orientation guide: tools, prompts, resources, and workflows            |
+| CodeQL Server Prompts          | `codeql://server/prompts`                   | Complete reference of MCP prompts for CodeQL development workflows                |
+| CodeQL Server Queries          | `codeql://server/queries`                   | Overview of bundled tools queries: PrintAST, PrintCFG, CallGraphFrom, CallGraphTo |
+| CodeQL Server Tools            | `codeql://server/tools`                     | Complete reference of default MCP tools for CodeQL development                    |
+| CodeQL Security Templates      | `codeql://templates/security`               | Security query templates for multiple languages and vulnerability classes         |
 
 ## Language-Specific Resources
 
@@ -28,7 +32,6 @@ Each supported language can expose one or more of the following resource types u
 | java       |       ✓       |                   |                                           |
 | javascript |       ✓       |         ✓         |                                           |
 | python     |       ✓       |         ✓         |                                           |
-| ql         |       ✓       |                   |                                           |
 | ruby       |       ✓       |                   |                                           |
 
 ### Resource Types