docs: reorganize docs — move guides to docs/guides, roadmap into docs

Move docs/*.md (adding-a-language, ai-agent-guide, recommended-practices)
into docs/guides/. Move roadmap/ contents (ROADMAP.md, BACKLOG.md,
llm-integration.md) into docs/. Update all cross-references in README,
CONTRIBUTING, STABILITY, SUPPORT, and recommended-practices.

Author: github-actions[bot]

CONTRIBUTING.md

@@ -197,7 +197,7 @@ recall will be questioned during review.
 Adding a new language is one of the most impactful contributions. We have a
 dedicated step-by-step guide:
 
-**[Adding a New Language](docs/adding-a-language.md)**
+**[Adding a New Language](docs/guides/adding-a-language.md)**
 
 This covers the full dual-engine workflow (WASM + native Rust), including every
 file to modify, code templates, and a verification checklist.

README.md

@@ -144,7 +144,7 @@ Or connect directly via MCP:
 codegraph mcp          # 17-tool MCP server — AI queries the graph directly
 ```
 
-Full agent setup: [AI Agent Guide](docs/ai-agent-guide.md) · [CLAUDE.md template](docs/ai-agent-guide.md#claudemd-template)
+Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) · [CLAUDE.md template](docs/guides/ai-agent-guide.md#claudemd-template)
 
 ---
 
@@ -416,7 +416,7 @@ codegraph mcp --repos a,b      # Restrict to specific repos (implies --multi-rep
 
 ### CLAUDE.md / Agent Instructions
 
-Add this to your project's `CLAUDE.md` to help AI agents use codegraph (full template in the [AI Agent Guide](docs/ai-agent-guide.md#claudemd-template)):
+Add this to your project's `CLAUDE.md` to help AI agents use codegraph (full template in the [AI Agent Guide](docs/guides/ai-agent-guide.md#claudemd-template)):
 
 ```markdown
 ## Code Navigation
@@ -474,15 +474,15 @@ Use `--kind function` to cut noise. Use `--file <pattern>` to scope.
 
 ## 📋 Recommended Practices
 
-See **[docs/recommended-practices.md](docs/recommended-practices.md)** for integration guides:
+See **[docs/guides/recommended-practices.md](docs/guides/recommended-practices.md)** for integration guides:
 
 - **Git hooks** — auto-rebuild on commit, impact checks on push, commit message enrichment
 - **CI/CD** — PR impact comments, threshold gates, graph caching
 - **AI agents** — MCP server, CLAUDE.md templates, Claude Code hooks
 - **Developer workflow** — watch mode, explore-before-you-edit, semantic search
 - **Secure credentials** — `apiKeyCommand` with 1Password, Bitwarden, Vault, macOS Keychain, `pass`
 
-For AI-specific integration, see the **[AI Agent Guide](docs/ai-agent-guide.md)** — a comprehensive reference covering the 6-step agent workflow, complete command-to-MCP mapping, Claude Code hooks, and token-saving patterns.
+For AI-specific integration, see the **[AI Agent Guide](docs/guides/ai-agent-guide.md)** — a comprehensive reference covering the 6-step agent workflow, complete command-to-MCP mapping, Claude Code hooks, and token-saving patterns.
 
 ## 🔁 CI / GitHub Actions
 
@@ -619,7 +619,7 @@ npm install
 npm test
 ```
 
-Looking to add a new language? Check out **[Adding a New Language](docs/adding-a-language.md)**.
+Looking to add a new language? Check out **[Adding a New Language](docs/guides/adding-a-language.md)**.
 
 ## 📄 License
 

STABILITY.md

@@ -109,7 +109,7 @@ LTS will be activated based on community adoption and demand — there is no fix
 |---------|--------------|---------|
 | CLI commands | Documented via `--help` and [README](README.md#-commands) | No change needed |
 | Programmatic API (`index.js`) | Documented in README examples | Auto-generated JSDoc reference (Phase 3+) |
-| MCP tools | Documented in [AI Agent Guide](docs/ai-agent-guide.md) | Versioned schema reference (Phase 3+) |
+| MCP tools | Documented in [AI Agent Guide](docs/guides/ai-agent-guide.md) | Versioned schema reference (Phase 3+) |
 
 The planned auto-generated reference will cover all public exports from `index.js` with full type signatures, parameter descriptions, and usage examples.
 

SUPPORT.md

@@ -8,8 +8,8 @@ Here are the best ways to get help with codegraph:
 
 - [README](README.md) — Quick start, commands, features, and configuration
 - [CONTRIBUTING.md](CONTRIBUTING.md) — Development setup and contribution guide
-- [Recommended Practices](docs/recommended-practices.md) — Git hooks, CI/CD, AI agent integration
-- [Adding a New Language](docs/adding-a-language.md) — Step-by-step language support guide
+- [Recommended Practices](docs/guides/recommended-practices.md) — Git hooks, CI/CD, AI agent integration
+- [Adding a New Language](docs/guides/adding-a-language.md) — Step-by-step language support guide
 
 ### Questions & Discussions
 

roadmap/BACKLOG.md docs/BACKLOG.mdroadmap/BACKLOG.md renamed to docs/BACKLOG.md

@@ -517,5 +517,5 @@ cp node_modules/@optave/codegraph/.github/workflows/codegraph-impact.yml .github
 codegraph embed
 
 # 7. (Optional) Add CLAUDE.md for AI agents
-# See docs/ai-agent-guide.md for the full template
+# See docs/guides/ai-agent-guide.md for the full template
 ```