Content
# Codebase Wiki
**Architectural knowledge base with MCP interface for AI agents.**
Agents discover services, generate LLM-powered docs with Mermaid C2/C3/sequence diagrams, and index them for semantic search. Includes self-learning notes and first-class workflow/flow indexing.
## Quick Start
```bash
npm install -g @carreira-cloud/codebase-wiki
cd my-project
codebase-wiki init # Initialize knowledge base
codebase-wiki serve # Browse at http://localhost:3080
codebase-wiki start-mcp # Start MCP server for AI agents
```
## Commands
| Command | Description |
|---------|-------------|
| `init` | Initialize knowledge base for current repo |
| `serve` | Start web UI (markdown + mermaid rendering, flows tab) |
| `start-mcp` | Start MCP server (stdio JSON-RPC, 12 tools) |
| `search <query>` | Search docs, notes, and flows by keyword |
| `get <service>` | Retrieve full documentation for a service |
| `list` | List all indexed services |
| `stats` | Statistics: services, flows, notes, content size |
| `install-opencode` | Install OpenCode skills and commands |
## MCP Tools
### Documentation (8 tools)
| Tool | Description |
|------|-------------|
| `wiki_index` | Index an LLM-generated architectural document |
| `wiki_search` | Search documentation by keyword |
| `wiki_get` | Retrieve full documentation for a service |
| `wiki_list` | List all indexed services |
| `wiki_delete` | Remove a service's documentation |
| `wiki_stats` | Statistics: services, content size, notes count, flows count |
### Self-Learning Notes (3 tools)
| Tool | Description |
|------|-------------|
| `wiki_note` | Store a self-learning discovery note |
| `wiki_notes_search` | Search agent notes by keyword |
| `wiki_notes_list` | List notes (optional type filter) |
### Workflows & Flows (3 tools)
| Tool | Description |
|------|-------------|
| `wiki_flow_index` | Index a workflow diagram with keywords and linked services |
| `wiki_flow_search` | Search flows across all services by keyword |
| `wiki_flow_list` | List flows (optional service/flow_type filter) |
## OpenCode Commands
```
/wiki generate <service> → Agent discovers, generates docs, indexes via MCP
/wiki generate-all → Generate docs for all services
/wiki enhance <service> <flow> → Add Mermaid C3/C2/sequence diagrams
/wiki discover-flows <service> → Discover and index all workflows with edge cases
/wiki flow-search <query> → Search flows across all services
/wiki flow-list <service> → List flows for a service
/wiki search <query> → Search docs + notes + flows
/wiki get <service> → Retrieve full doc
/wiki list → List all indexed services
/wiki stats → Knowledge base statistics
```
## Self-Learning
Agents automatically add notes when they discover something new. Six note types:
| Type | Trigger |
|------|---------|
| `gotcha` | Unexpected behavior, edge case, known bug |
| `pattern` | Recurring pattern across 2+ services |
| `integration` | Undocumented service integration detail |
| `convention` | Code convention, naming pattern |
| `decision` | Design decision (lightweight ADR) |
| `tip` | Shortcut, useful command, workflow hack |
## Flows & Diagrams
Each flow is independently indexed with:
- **Mermaid sequence diagram** (happy path + error paths + edge cases)
- **Keywords** for discoverability
- **Linked services** for cross-service navigation
- **Flow type**: happy_path, error_path, edge_case, recovery, full
Diagrams render in the web UI via Mermaid.js. The UI also renders service documentation markdown (tables, code blocks, headings) via marked.js.
## Architecture
```
src/
├── cli.ts # CLI entry (8 commands)
├── mcp-server.ts # MCP JSON-RPC server (12 tools)
├── ui-server.ts # Web UI (marked.js + mermaid.js, flows tab)
├── lancedb/client.ts # JSON file-backed storage (docs, notes, flows)
├── types.ts # TypeScript types
└── index.ts # Public API exports
docs/
├── getting-started.md
├── mcp-tools.md
├── self-learning.md
├── configuration.md
└── architecture.md
```
Storage: `.codebase-wiki/rag_db/docs.json` + `notes.json` + `flows.json`
## License
MIT — [Bruno Carreira](https://github.com/bruno-carreira)
