feat: improve skill scores for GeneralizedNotationNotation

SKILL.md

@@ -5,16 +5,6 @@ description: Generalized Notation Notation (GNN) processing pipeline for Active
 
 # GNN Pipeline Skill
 
-GNN (Generalized Notation Notation) is a text-based specification language for Active Inference generative models. This repository implements a **25-step processing pipeline** (steps 0–24) that transforms GNN specifications into executable simulations, visualizations, analysis reports, and more.
-
-## When to Use This Skill
-
-- Parsing or authoring `.md` GNN model files
-- Running the full pipeline or individual steps
-- Generating simulation code (PyMDP, RxInfer.jl, JAX, DisCoPy, ActiveInference.jl, PyTorch, NumPyro)
-- Creating visualizations, exports, or reports from GNN models
-- Working with Active Inference ontology annotations
-
 ## Quick Start
 
 ```bash
@@ -99,6 +89,28 @@ python src/12_execute.py --frameworks "lite" --verbose
 python src/12_execute.py --frameworks "all" --verbose
 ```
 
+## Validation Checkpoints
+
+After running groups of steps, verify outputs before proceeding:
+
+```bash
+# After Core steps (0-9): confirm parsed models exist
+ls output/03_gnn_output/parsed/
+
+# After Simulation steps (10-16): confirm generated code and execution results
+ls output/11_render_output/ output/12_execute_output/
+
+# After Output steps (17-24): confirm reports and deliverables
+ls output/23_report_output/
+```
+
+If a step fails, inspect its log and re-run from that point:
+
+```bash
+# Re-run from a specific step after fixing an issue
+python src/main.py --only-steps "11,12" --verbose
+```
+
 ## Module Skills
 
 Each `src/module/` directory contains its own `SKILL.md` with module-specific instructions. See `src/AGENTS.md` for the complete module registry.

src/api/SKILL.md

@@ -1,23 +1,64 @@
 ---
-name: API
-description: Capabilities for API
+name: gnn-api
+description: "GNN REST API server for pipeline execution and job management. Use when starting the GNN API server, triggering pipeline steps via HTTP, polling job status, or invoking GNN tools without the CLI."
 ---
 
-# API SKILL
+# GNN REST API (Optional Module)
 
-## Purpose
-Capabilities for the API module.
+Provides a FastAPI-based REST interface for triggering pipeline steps, polling job status, and invoking individual GNN tools over HTTP.
+
+Requires the `[api]` extra: `uv sync --extra api`
 
 ## Key Commands
-N/A
 
-## References
-- [SPEC](SPEC.md)
+```bash
+# Start the API server
+python -m api.server
 
+# Or via the MCP pipeline step (also registers API tools)
+python src/main.py --only-steps 21 --verbose
+```
 
----
-## Documentation
-- **[README](README.md)**: Module Overview
-- **[AGENTS](AGENTS.md)**: Agentic Workflows
-- **[SPEC](SPEC.md)**: Architectural Specification
-- **[SKILL](SKILL.md)**: Capability API
+## API
+
+```python
+from api.processor import create_job, get_job, list_jobs
+
+# Create a pipeline job
+job_id = create_job(
+    target_dir="input/gnn_files",
+    steps=[3, 5, 11, 12],
+    verbose=True,
+)
+
+# Poll job status
+job = get_job(job_id)
+print(job["status"])  # "pending" | "running" | "completed" | "failed"
+
+# List all jobs
+jobs = list_jobs()
+```
+
+## Recommended Workflow
+
+```bash
+# 1. Install API dependencies
+uv sync --extra api
+
+# 2. Start the server
+python -m api.server
+
+# 3. Trigger a pipeline run via HTTP
+curl -X POST http://localhost:8000/jobs \
+  -H "Content-Type: application/json" \
+  -d '{"target_dir": "input/gnn_files", "steps": [3,5,11]}'
+
+# 4. Poll job status
+curl http://localhost:8000/jobs/<job-id>
+```
+
+## References
+
+- [AGENTS.md](AGENTS.md) — Module documentation
+- [README.md](README.md) — Usage guide
+- [SPEC.md](SPEC.md) — Architectural specification

src/cli/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: gnn-cli-dispatch
+description: "GNN command-line interface dispatching 12 subcommands to pipeline module APIs. Use when running GNN pipeline commands, validating GNN files, parsing models, generating code, or checking environment health via the CLI."
+---
+
 # Core Skill: `cli_dispatch`
 
 **Function**: Unified command-line interface dispatching 12 subcommands to their respective GNN pipeline module APIs.
@@ -22,19 +27,23 @@ gnn preflight
 gnn health
 ```
 
-## Programmatic Usage
+## Recommended Workflow
+
+```bash
+# 1. Verify environment is ready
+gnn preflight
 
-```python
-from cli import main
+# 2. Validate GNN files before processing
+gnn validate input/gnn_files/discrete/actinf_pomdp_agent.md --strict
 
-# The CLI entry point dispatches to module APIs
-# Each subcommand maps to a specific module function:
-#   run       → main.main()
-#   validate  → gnn.schema.validate_required_sections()
-#   parse     → gnn.schema.parse_state_space()
-#   render    → render.processor
-#   health    → render.health.check_renderers()
-#   lsp       → lsp.start_server()
+# 3. Parse validated files
+gnn parse input/gnn_files/discrete/actinf_pomdp_agent.md --format json
+
+# 4. Generate simulation code
+gnn render input/gnn_files/discrete/actinf_pomdp_agent.md --framework pymdp
+
+# 5. Run full pipeline (or use --only-steps to target specific phases)
+gnn run --target-dir input/gnn_files --verbose --only-steps "3,5,11,12"
 ```
 
 ## Features
@@ -46,4 +55,10 @@ from cli import main
 - **Environment Checks**: Dependency and configuration validation via `gnn preflight` and `gnn health`
 - **Live Development**: File monitoring with 250ms debounce via `gnn watch`
 - **Dependency Graphs**: Mermaid/text graph output via `gnn graph`
-- **API \& LSP Servers**: FastAPI server (`gnn serve`) and Language Server (`gnn lsp`)
+- **API & LSP Servers**: FastAPI server (`gnn serve`) and Language Server (`gnn lsp`)
+
+## References
+
+- [AGENTS.md](AGENTS.md) — Module documentation
+- [README.md](README.md) — Usage guide
+- [SPEC.md](SPEC.md) — Subcommand specification

src/gnn/SKILL.md

@@ -78,6 +78,26 @@ is_valid, errors = validate_gnn(content_string)
 - `GNNParsingSystem`, `GNNFormat` — registry-backed multi-format I/O
 - `GNNFormalParser`, `ParsedGNN`, `ParsedGNNFormal` — formal parser types
 
+## Recommended Workflow
+
+```python
+# 1. Discover files
+files = discover_gnn_files("input/gnn_files/")
+
+# 2. Parse each file
+for f in files:
+    model = parse_gnn_file(f)
+
+    # 3. Validate — check for structural/syntax errors before downstream use
+    is_valid, errors = validate_gnn(open(f).read())
+    if not is_valid:
+        print(f"Validation failed for {f}: {errors}")
+        continue  # skip invalid files rather than propagating bad data
+
+    # 4. Proceed with valid models
+    # ...
+```
+
 ## Output
 
 Parsed models are consumed by downstream steps:
@@ -86,7 +106,6 @@ Parsed models are consumed by downstream steps:
 - **Steps 7–8** (Export/Viz): generates outputs
 - **Step 11** (Render): generates simulation code
 
-
 ## MCP Tools
 
 This module registers tools with the GNN MCP server (see `mcp.py`):
@@ -105,9 +124,3 @@ This module registers tools with the GNN MCP server (see `mcp.py`):
 - [../../doc/gnn/tutorials/gnn_examples_doc.md](../../doc/gnn/tutorials/gnn_examples_doc.md) — Example models
 
 
----
-## Documentation
-- **[README](README.md)**: Module Overview
-- **[AGENTS](AGENTS.md)**: Agentic Workflows
-- **[SPEC](SPEC.md)**: Architectural Specification
-- **[SKILL](SKILL.md)**: Capability API

src/mcp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gnn-mcp-protocol
-description: GNN Model Context Protocol processing and tool registration. Use when registering GNN operations as MCP tools, building MCP server configurations, or integrating GNN capabilities with LLM tool-use workflows.
+description: "GNN Model Context Protocol server and tool registration. Use when registering GNN pipeline operations as MCP tools, starting the MCP JSON-RPC server, configuring tool discovery, or exposing GNN capabilities to LLM agents via tool-use."
 ---
 
 # GNN MCP Protocol (Step 21)
@@ -90,6 +90,25 @@ The `MCP` singleton honours these knobs, all propagated through
 | `overall_timeout` | `float` | `120.0` | Wall-clock budget for parallel discovery |
 | `force_refresh` | `bool` | `False` | Re-discover modules even if already loaded |
 
+## Recommended Workflow
+
+```python
+from mcp import initialize, register_tools, get_available_tools, create_mcp_server
+
+# 1. Initialize the MCP registry
+initialize(performance_mode="high", strict_validation=True)
+
+# 2. Discover and register all pipeline module tools
+register_tools()
+
+# 3. Verify tools registered correctly
+tools = get_available_tools()
+assert len(tools) > 0, "No tools registered — check module discovery"
+
+# 4. Start the JSON-RPC server
+server = create_mcp_server()
+```
+
 ## Output
 
 - MCP configuration in `output/21_mcp_output/`
@@ -102,11 +121,3 @@ The `MCP` singleton honours these knobs, all propagated through
 - [README.md](README.md) — Usage guide
 - [SPEC.md](SPEC.md) — Module specification
 - [MCP Protocol Spec](https://modelcontextprotocol.io/)
-
-
----
-## Documentation
-- **[README](README.md)**: Module Overview
-- **[AGENTS](AGENTS.md)**: Agentic Workflows
-- **[SPEC](SPEC.md)**: Architectural Specification
-- **[SKILL](SKILL.md)**: Capability API