docs: update CLAUDE.md and README.md with current project state

CLAUDE.md:
- Add new detector base classes (AbstractPythonAntlrDetector, AbstractTypeScriptDetector, etc.)
- Add shared detector helpers (DetectorDbHelper, FrontendDetectorHelper, StructuresDetectorHelper)
- Update test count from 1440 to 3219
- Add gotchas: H2 reserved words, cache versioning, SHA-256 hashes, SnakeYAML Boolean.TRUE,
  regex possessive quantifiers, parallel agent conflicts, SonarCloud config, CI workflow
- Add PROP_* string constant convention

README.md:
- Update test count from 1,440 to 3,219
- Update MCP tool count from 31 to 34 (added intelligence tools)
- Update REST API endpoint count from 34 to 37
- Add Intelligence tools section (get_evidence_pack, get_artifact_metadata, get_capabilities)
- Update architecture diagram counts

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: aksOps

CLAUDE.md

@@ -96,7 +96,7 @@ io.github.randomcodespace.iq
   |-- grammar/                     # ANTLR parser factory + generated parsers
   |-- graph/                       # GraphStore (Neo4j facade), GraphRepository (SDN, writes only)
   |-- health/                      # GraphHealthIndicator (Spring Actuator)
-  |-- mcp/                         # McpTools (34 @McpTool methods, read-only)
+  |-- mcp/                         # McpTools (34 @McpTool methods, read-only, includes intelligence tools)
   |-- model/                       # CodeNode, CodeEdge, NodeKind (32), EdgeKind (27)
   |-- intelligence/               # Intelligence enrichment (Phase 2-5)
   |   |-- lexical/                # LexicalEnricher, LexicalQueryService, DocCommentExtractor, SnippetStore
@@ -250,11 +250,22 @@ code-iq serve /path/to/repo          # needs enrich if using index
 | `AbstractJavaParserDetector` | Java AST via JavaParser (Spring, JPA, etc.) |
 | `AbstractAntlrDetector` | ANTLR grammar-based (TS, Python, Go, C#, Rust, C++) |
 | `AbstractStructuredDetector` | Structured file parsing (YAML, JSON, TOML, etc.) |
+| `AbstractPythonAntlrDetector` | Python ANTLR detectors (shared parse, getBaseClassesText, extractClassBody) |
+| `AbstractPythonDbDetector` | Python ORM detectors (adds ensureDbNode/addDbEdge via DetectorDbHelper) |
+| `AbstractTypeScriptDetector` | TypeScript regex detectors (shared getSupportedLanguages, detect→detectWithRegex) |
+| `AbstractJavaMessagingDetector` | Java messaging detectors (shared CLASS_RE, extractClassName, addMessagingEdge) |
+
+### Shared Detector Helpers
+| Class | Purpose |
+|-------|---------|
+| `DetectorDbHelper` | Static ensureDbNode/addDbEdge for any detector emitting DATABASE_CONNECTION nodes |
+| `FrontendDetectorHelper` | Static createComponentNode/lineAt for Angular, React, Vue detectors |
+| `StructuresDetectorHelper` | Static addImportEdge/createStructureNode for Scala/Kotlin structures |
 
 ## Testing
 
 ```bash
-# Run all tests (~1440 tests)
+# Run all tests (~3219 tests)
 mvn test
 
 # Run a specific test class
@@ -352,6 +363,7 @@ mvn dependency-check:check
 - Neo4j properties round-trip via `prop_*` prefix (written by `bulkSave`, read by `nodeFromNeo4j`)
 - Jackson `FAIL_ON_UNKNOWN_PROPERTIES` disabled globally for MCP protocol compatibility
 - UTF-8 encoding everywhere (explicit `StandardCharsets.UTF_8`)
+- Property key constants: `private static final String PROP_FRAMEWORK = "framework"` — extract when a string literal appears 3+ times in a file
 
 ## Configuration
 
@@ -384,6 +396,14 @@ Placed in the codebase root, loaded by `ProjectConfigLoader` before analysis.
 - **ANTLR generated sources**: Generated during `mvn generate-sources` from `.g4` files. Do not edit.
 - **`@ActiveProfiles("test")`**: Required on any `@SpringBootTest` to avoid Neo4j startup conflicts.
 - **Dead code detection**: Must filter by semantic edges only (calls, imports, depends_on). Exclude structural edges (contains, defines) and entry points (endpoints, config files).
+- **H2 reserved words**: `key`, `value`, `order` are reserved in H2 SQL. Use `meta_key`, `meta_value` etc. in CREATE TABLE statements.
+- **Cache versioning**: `AnalysisCache` has a `CACHE_VERSION` constant (currently 2). Bump it when changing hash algorithms or schema to auto-clear stale caches.
+- **FileHasher uses SHA-256**: Changed from MD5. Hash output is 64 hex chars (not 32). Tests must expect 64-char hashes.
+- **SnakeYAML parses `on` as Boolean.TRUE**: In YAML files, bare `on` key becomes `Boolean.TRUE`. Use `String.valueOf(key)` comparisons, not `Boolean.TRUE.equals(key)` (SonarCloud S2159).
+- **Regex possessive quantifiers**: Use `*+` instead of `*` for nested quantifiers like `([^"\\]*(?:\\.[^"\\]*)*)` → `([^"\\]*+(?:\\.[^"\\]*+)*+)` to prevent stack overflow (SonarCloud S5998).
+- **Parallel agent conflicts**: Don't dispatch multiple agents editing the same files concurrently. Use worktree isolation or sequential execution.
+- **SonarCloud project key**: `RandomCodeSpace_code-iq`, org: `randomcodespace`
+- **CI workflow**: Single `ci-java.yml` runs build + SonarCloud analysis. No cross-platform builds needed (JVM).
 
 ## Updating This File
 

README.md

@@ -18,7 +18,7 @@
 
 ---
 
-**OSSCodeIQ** scans codebases to build a deterministic knowledge graph of code relationships -- classes, methods, endpoints, entities, dependencies, infrastructure resources, auth patterns, service topology, and more. 97 detectors across 35+ languages, Neo4j Embedded graph database, Spring AI MCP server (31 tools), REST API (34 endpoints), React web UI, and zero AI dependency.
+**OSSCodeIQ** scans codebases to build a deterministic knowledge graph of code relationships -- classes, methods, endpoints, entities, dependencies, infrastructure resources, auth patterns, service topology, and more. 97 detectors across 35+ languages, Neo4j Embedded graph database, Spring AI MCP server (34 tools), REST API (37 endpoints), React web UI, and zero AI dependency.
 
 ## Quick Start
 
@@ -49,8 +49,8 @@ java -jar target/code-iq-*-cli.jar serve /path/to/repo
 - **ANTLR grammars** for 10 languages (TypeScript, JavaScript, Python, Go, C#, Rust, Kotlin, Scala, C++)
 - **Neo4j Embedded** graph database -- full Cypher query support, no external server needed
 - **H2 analysis cache** -- batched streaming for memory-efficient indexing on CI runners
-- **Spring AI MCP server** -- 31 tools via streamable HTTP for AI-powered triage
-- **REST API** -- 34 endpoints for programmatic access
+- **Spring AI MCP server** -- 34 tools via streamable HTTP for AI-powered triage
+- **REST API** -- 37 endpoints for programmatic access
 - **React UI** -- Dashboard, Topology (Cytoscape.js), Explorer, Flow, MCP Console, API Docs (Swagger)
 - **Service Topology** -- AppDynamics-style service map with blast radius, circular deps, bottleneck detection
 - **CLI with 15 commands** -- analyze, index, enrich, serve, stats, graph, query, find, cypher, flow, topology, bundle, cache, plugins, version
@@ -61,7 +61,7 @@ java -jar target/code-iq-*-cli.jar serve /path/to/repo
 - **Bundle & distribute** -- package graph DB + source + interactive HTML into a ZIP
 - **100% deterministic** -- same input, same output, every time
 - **Incremental analysis** -- H2-backed file hash cache, only re-analyzes changed files
-- **1,440 tests** passing
+- **3,219 tests** passing
 
 ## Three-Command Architecture
 
@@ -196,7 +196,7 @@ code-iq serve /path/to/repo
     |         |        |
     v         v        v
  REST API   MCP     React UI
- (34 ep)   (31 tools) (6 pages)
+ (37 ep)   (34 tools) (6 pages)
 ```
 
 ## Server
@@ -234,14 +234,17 @@ Modern React 18 + TypeScript + Tailwind CSS interface:
 - `/api/topology/path` -- find path between services
 
 ### MCP Server (`/mcp`)
-31 tools via Spring AI streamable HTTP for AI-powered code triage:
+34 tools via Spring AI streamable HTTP for AI-powered code triage:
 
 **Core (21 tools):**
 `get_stats`, `get_detailed_stats`, `query_nodes`, `query_edges`, `get_node_neighbors`, `get_ego_graph`, `find_cycles`, `find_shortest_path`, `find_consumers`, `find_producers`, `find_callers`, `find_dependencies`, `find_dependents`, `find_dead_code`, `generate_flow`, `run_cypher`, `find_component_by_file`, `trace_impact`, `find_related_endpoints`, `search_graph`, `read_file`
 
 **Topology (10 tools):**
 `get_topology`, `service_detail`, `service_dependencies`, `service_dependents`, `blast_radius`, `find_path`, `find_bottlenecks`, `find_circular_deps`, `find_dead_services`, `find_node`
 
+**Intelligence (3 tools):**
+`get_evidence_pack`, `get_artifact_metadata`, `get_capabilities`
+
 ## Service Topology
 
 AppDynamics-style service topology from static code analysis:
@@ -342,7 +345,7 @@ cd code-iq
 # Build
 mvn clean package
 
-# Run tests (1,440 tests)
+# Run tests (3,219 tests)
 mvn test
 
 # Analyze this repo