diff --git a/GSD-STYLE.md b/GSD-STYLE.md
index c99e9d08a..23e6b177b 100644
--- a/GSD-STYLE.md
+++ b/GSD-STYLE.md
@@ -483,6 +483,70 @@ How to make tests pass
 
 ---
 
+## Codebase Intelligence
+
+GSD includes an automatic codebase learning system that indexes code and detects patterns.
+
+### Files
+
+| File | Purpose | Updated By |
+|------|---------|------------|
+| `.planning/intel/index.json` | File exports/imports index | PostToolUse hook |
+| `.planning/intel/conventions.json` | Detected naming/directory/suffix patterns | PostToolUse hook |
+| `.planning/intel/summary.md` | Concise context for injection | PostToolUse hook |
+
+### Index Schema
+
+```json
+{
+  "version": 1,
+  "updated": 1234567890,
+  "files": {
+    "/absolute/path/to/file.ts": {
+      "exports": ["functionA", "ClassB", "default"],
+      "imports": ["react", "./utils", "@org/pkg"],
+      "indexed": 1234567890
+    }
+  }
+}
+```
+
+### Convention Detection
+
+**Naming conventions** (requires 5+ exports, 70%+ match rate):
+- camelCase, PascalCase, snake_case, SCREAMING_SNAKE
+- 'default' is skipped (keyword, not naming indicator)
+
+**Directory purposes** (lookup table):
+- components, hooks, utils, lib, services, api, routes, types, models, tests, etc.
+
+**Suffix patterns** (requires 5+ files):
+- .test.*, .spec.*, .service.*, .controller.*, etc.
+
+### Hook Patterns
+
+**PostToolUse hook (intel-index.js):**
+- Triggers on Write/Edit of JS/TS files
+- Incremental update (single file per invocation)
+- Silent failure (never blocks Claude)
+- Regenerates conventions.json and summary.md on every update
+
+**SessionStart hook (intel-session.js):**
+- Triggers on startup/resume
+- Reads index.json and conventions.json
+- Outputs `<codebase-intelligence>` wrapped summary
+- Silent failure if intel files missing
+
+### Commands
+
+**`/gsd:analyze-codebase`** — Bulk scan for brownfield projects:
+- Creates .planning/intel/ directory
+- Scans all JS/TS files (excludes node_modules, dist, build, .git, vendor, coverage)
+- Uses same extraction logic as PostToolUse hook
+- Works standalone (no /gsd:new-project required)
+
+---
+
 ## Summary: Core Meta-Patterns
 
 1. **XML for semantic structure, Markdown for content**