@lon-ask/dockit 0.1.0

package/README.md

@@ -0,0 +1,496 @@
+# Dockit
+
+Local documentation hub that aggregates multiple documentation source types (ZIP, Maven, Antora, AsciiDoc, GitHub Markdown) into a unified, searchable HTML bundle — useful as LLM context. Also supports **source code knowledge graphs** powered by Graphify (Tree-sitter AST), producing structural dependency graphs for 15+ languages.
+
+Ships with two search engines: a lightweight **TF-IDF engine** and a **hybrid semantic+keyword engine** (LanceDB + all-MiniLM-L6-v2 embeddings) configurable via a single toggle.
+
+All operational data (SQLite DB, build outputs, search indexes, knowledge graphs, embeddings model cache) is stored in `~/.dockit/` by default. Override with the `DOCKIT_DATA_DIR` environment variable.
+
+## Quick Start
+
+```bash
+# 1. Clone and install
+git clone https://github.com/your-org/dockit.git
+cd dockit
+npm install
+pip3 install graphify openai   # optional — for source code graphs
+
+# 2. Make CLI available globally
+npm link
+
+# 3a. Build pre-configured docs (one-time per entry)
+dockit build quarkus
+
+# 3b. Or init a project with source code + markdown scanning
+dockit init --path /path/to/project --code-path src
+
+# 4. Start searching
+dockit search quarkus "configure cache"
+dockit graph query dockit "BuildUseCase"   # if source-code built
+```
+
+## Pre-configured Documentation
+
+| Entry | Version | Source Type | Description |
+|-------|---------|-------------|-------------|
+| **Quarkus** | 3.35 | AsciiDoc | Quarkus framework documentation |
+| **Quarkus Core** | 3.35.2 | Maven Javadoc | Quarkus Core API reference |
+| **React** | 19 | GitHub Markdown | React library documentation |
+| **Spring Boot** | 3.5.x | Antora | Production-ready Spring applications |
+| **Spring Framework** | 7.x | Antora | Core Spring ecosystem reference |
+| **Quarkus Source Code** | 3.35 | Source Code | Quarkus framework source — knowledge graph |
+| **Quarkus (Docs + Code)** | 3.35 | AsciiDoc + Source Code | Docs + code graph combined |
+| **Dockit** | 1.0 | Source Code + Markdown | Self-hosted dockit project entry |
+
+Add your own entries by editing `dockit.yaml` or using `dockit init` — see [Supported Sources](#supported-documentation-sources) below.
+
+## Search Engine
+
+Dockit ships two search engines toggleable via `dockit.yaml`:
+
+```yaml
+search:
+  engine: vector    # 'vector' (default) | 'json' (TF-IDF fallback)
+```
+
+| | JSON (TF-IDF) | Vector (Hybrid) |
+|---|---|---|
+| **Storage per entry** | ~300 KB | ~32 MB (LanceDB) |
+| **Runtime memory** | Minimal | ~200 MB |
+| **Build time** | Fast | Slower (embeds docs via ONNX) |
+| **Search method** | Term-frequency scoring (title 10x, headings 3x, body 1x) | Hybrid: parallel cosine ANN + BM25 FTS → RRF fusion |
+| **Keyword precision** | High (exact term matches) | Very high (FTS component recovers keywords) |
+| **Semantic matching** | None | Yes (finds conceptually related docs even without exact terms) |
+| **Model** | None | `all-MiniLM-L6-v2` via `@huggingface/transformers` (~88 MB ONNX) |
+| **Works offline** | Yes — zero dependencies | Yes — model bundles in npm package |
+
+### How hybrid search works
+
+```
+query → vector (cosine ANN) + BM25 (FTS) in parallel
+         → deduplicate per-path → RRF fusion → top N
+```
+
+- Vector search finds semantically related pages (e.g., "Ahead-of-Time Caching" for a cache query)
+- FTS recovers exact keyword matches (e.g., "caffeine" in the Caching guide)
+- Reciprocal Rank Fusion combines both with dynamic weighting: confident FTS gets 2x weight, uncertain FTS gets 0.7x
+- Title matches in FTS results get an additional 1.5x boost
+
+### When to use each
+
+- **`json`**: Low-resource environments, fast builds, or when exact keyword matching is sufficient
+- **`vector`** (default): Better discovery of non-obvious matches, section-level chunking with heading context in results, hybrid search that matches both keywords and concepts
+
+## CLI Usage (Recommended)
+
+The CLI is the primary way to interact with Dockit. Works from any directory, requires no server process, and is ideal for LLM agents that can execute shell commands.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `dockit search [<entry>] <query>` | Search documentation |
+| `dockit search <query>` | Global search — top result per entry |
+| `dockit search [<entry>] <query> --get-top [N]` | Fetch full content for top N results (default 3) |
+| `dockit list` | List all entries |
+| `dockit build <entry>` | Build documentation for an entry |
+| `dockit status <entry>` | Check build status |
+| `dockit get <entry> <path>` | Fetch full document content |
+| `dockit graph query <entry> <query>` | Search knowledge graph nodes by name, file, or type |
+| `dockit graph path <entry> <from> <to>` | Find shortest dependency path between two nodes |
+| `dockit graph gods <entry>` | List most connected (god) nodes |
+| `dockit graph explain <entry> <node>` | Show node details and connections |
+| `dockit init --path <dir> [--code-path <subdir>]` | Initialize a project as a dockit source |
+| `dockit dev` | Start dev servers (web UI) |
+| `dockit serve` | Start production server |
+| `dockit mcp` | Start MCP server |
+
+### Search Workflow
+
+**Step 1: Global search** — discover which entries are relevant
+
+```bash
+dockit search "cache"
+# Returns top result per entry:
+#   [React] cache
+#   [Quarkus] caching-guide
+#   [Quarkus Core] Cache API
+```
+
+**Step 2: Scoped search** — dive deeper into the chosen entry
+
+```bash
+dockit search quarkus "cache" --get-top 3
+# Returns full content for top 3 Quarkus cache documents
+```
+
+### Knowledge Graph Queries
+
+For `source-code` entries built with Graphify:
+
+```bash
+# Search nodes
+dockit graph query dockit-code "BuildUseCase"
+
+# List most connected nodes
+dockit graph gods dockit-code --limit 5
+
+# Find shortest path between two nodes
+dockit graph path dockit-code "BuildUseCase" "SourceCodeSourceProcessor"
+
+# Show node details and connections
+dockit graph explain dockit-code "BuildUseCase"
+```
+
+### Init a Project
+
+```bash
+# From project root — auto-detects name
+dockit init --code-path apps
+
+# With explicit path and version
+dockit init --path /path/to/project --name "MyApp" --version "2.0" --code-path src
+
+# This creates:
+#   - source-code source (graphify on --code-path)
+#   - github-markdown source (scans all .md files)
+#   - Builds both immediately
+```
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output as JSON (for search, list, status, graph) |
+| `--limit <n>` | Max results (default 20) |
+| `--get-top [N]` | Fetch full content for top N results (default 3) |
+| `--port <port>` | Custom port (for serve, mcp --http) |
+
+### Examples
+
+```bash
+# Global search — see which entries match
+dockit search "hooks"
+
+# Scoped search with full content
+dockit search react "how to create a hook" --get-top
+
+# JSON output for scripts/agents
+dockit search react "useState" --get-top 3 --json
+
+# Build documentation
+dockit build quarkus
+dockit status quarkus
+
+# Fetch a specific document
+dockit get react react-docs-markdown/reference/react/hooks.html
+
+# Graph queries
+dockit graph query dockit-code "SourceCodeSourceProcessor"
+dockit graph gods dockit-code
+```
+
+## MCP Server (Optional)
+
+Dockit exposes an MCP (Model Context Protocol) server for AI tools like Claude Desktop, Cline, and OpenCode.
+
+### OpenCode
+
+```json
+// ~/.config/opencode/opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "dockit": {
+      "type": "local",
+      "command": ["bash", "/path/to/dockit/scripts/mcp-wrapper.sh"],
+      "enabled": true
+    }
+  }
+}
+```
+
+### Claude Desktop / Cline
+
+```json
+// ~/.claude/claude_desktop_config.json
+{
+  "mcpServers": {
+    "dockit": {
+      "command": "bash",
+      "args": ["/path/to/dockit/scripts/mcp-wrapper.sh"]
+    }
+  }
+}
+```
+
+### HTTP Transport
+
+```bash
+# Start HTTP bridge on port 3456
+DOCKIT_MCP_HTTP_PORT=3456 ./scripts/mcp-wrapper.sh
+
+# Then curl:
+curl -X POST http://localhost:3456 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `dockit_list_entries` | List all configured entries |
+| `dockit_find_entry` | Find entries by name/description |
+| `dockit_search` | Search within a specific entry |
+| `dockit_global_search` | Search across all entries |
+| `dockit_get_doc` | Fetch full document content |
+| `dockit_build` / `dockit_build_status` | Build / check status |
+| `dockit_graph_query` | Search knowledge graph (MCP only) |
+| `dockit_graph_path` | Find shortest path between nodes (MCP only) |
+| `dockit_graph_explain` | Node details with edges (MCP only) |
+| `dockit_graph_gods` | Most connected nodes (MCP only) |
+
+## How LLMs Use Dockit
+
+Dockit includes `SKILL.md` — a skill file that instructs LLMs how to use Dockit effectively. When an LLM has access to the `dockit` CLI or MCP tools, it follows this workflow:
+
+1. **`dockit list`** / **`dockit_list_entries`** — discover available documentation
+2. **`dockit search "query"`** — global search to find relevant entries
+3. **`dockit search <entry> "query" --get-top`** — scoped search with full content
+4. **For source-code entries**: use `dockit graph query <entry> "node"` for structural queries
+5. **Answer the user's question** using the retrieved documentation as context
+
+The LLM strips conversational filler from queries, scopes searches to the right entry, and prefers Dockit documentation over training data.
+
+## Supported Documentation Sources
+
+| Type | Description | Remote Fields | Local/Offline Fields |
+|------|-------------|---------------|---------------------|
+| **ZIP Bundle** | Download or extract a ZIP of HTML documentation | `url` | `localPath` — path to pre-downloaded .zip |
+| **Maven Artifact** | Download a documentation JAR (javadoc) from Maven Central | *(none extra)* | `useMavenCommand: true` — uses local Maven + settings.xml; `localJar` — path to pre-downloaded .jar |
+| **Antora** | Build a multi-page HTML site with Antora | `repoUrl` | `localPath` — path to pre-cloned repo |
+| **AsciiDoc** | Convert `.adoc` files to HTML | `repoUrl`, `sourcePath` (optional) | `localPath` — path to pre-cloned repo |
+| **GitHub Markdown** | Clone a GitHub repo and convert `.md` files to HTML | `repoUrl`, `sourcePath` (optional), `branch` (optional) | `localPath` — path to pre-cloned repo |
+| **Source Code** | Build a knowledge graph via Graphify (Tree-sitter AST) | `repoUrl`, `sourcePath` (optional), `branch` (optional) | `localPath` — path to local repo |
+| **Combined** | Add `graphifyEnabled: true` on doc sources (AsciiDoc, Markdown, Antora) to also generate a graph | *(inherits from parent type)* | *(inherits from parent type)* |
+
+### Source code knowledge graphs
+
+The `source-code` source type runs [Graphify](https://github.com/anomalyco/graphify) (Tree-sitter AST parser) on the source directory, producing a `graph.json` with nodes (classes, functions, files) and edges (imports, calls, inherits). Supports 15+ languages including TypeScript, JavaScript, Python, Java, Go, Rust, and C++.
+
+**Configuration fields:**
+
+| Field | Description |
+|-------|-------------|
+| `repoUrl` / `localPath` / `zipPath` | Source acquisition (same pattern as other types) |
+| `sourcePath` | Subdirectory to scan for code files |
+| `graphifySourcePath` | Separate subdirectory for graphify (when different from sourcePath e.g. docs vs code) |
+
+For existing doc sources (AsciiDoc, GitHub Markdown, Antora) that point to a repo containing source code, toggle `graphifyEnabled: true` and set `graphifySourcePath` to scan the code during build:
+
+```yaml
+sources:
+  - type: asciidoc
+    label: "Docs"
+    repoUrl: "https://github.com/myorg/myrepo.git"
+    sourcePath: "docs"           # doc files
+    graphifyEnabled: true
+    graphifySourcePath: "src"    # code files for graph
+```
+
+## Offline / Proxy Mode
+
+For environments behind corporate proxies or without internet access, Dockit supports multiple fallback mechanisms:
+
+### Source Repositories (local clones)
+
+Each source type supports local paths that take precedence over remote URLs:
+
+```yaml
+# dockit.yaml — local mode entries
+entries:
+  - id: quarkus-local
+    name: Quarkus (Local)
+    version: "3.35"
+    sources:
+      - type: asciidoc
+        label: "Quarkus Docs"
+        localPath: "/home/user/repos/quarkus"
+        sourcePath: "docs/src/main/asciidoc"
+```
+
+### Embedding Model (air-gapped vector search)
+
+The embedding model downloads on first `embed()` call by default into `~/.dockit/models/`. Override with `DOCKIT_DATA_DIR` or `configure({ cacheDir: '...' })`. For air-gapped environments:
+
+**Option A — Pre-seed on connected machine, then copy:**
+```bash
+# On connected machine
+npm run download-model -w packages/embeddings
+
+# Copy ~/.dockit/models/ to the target machine
+```
+
+**Option B — Install offline via npm:**
+The model ONNX bundle ships inside the `@dockit/embeddings` npm package under `packages/embeddings/model/`. If `~/.dockit/models/` is empty at first `embed()` call, it will attempt to download — set `DOCKIT_DATA_DIR` to point to a pre-seeded directory or use `configure({ cacheDir: '/path/to/model' })`.
+
+### Pre-built Index Bundling
+
+For environments where even building is impractical, LanceDB and JSON indexes can be pre-built and bundled:
+
+1. Build indexes on a connected machine:
+   ```bash
+   dockit build quarkus
+   dockit build spring-boot
+   # ... all desired entries
+   ```
+2. Package the `~/.dockit/` directory (or specific `.lancedb/` + `index.json` files)
+3. Deploy to target machines via the same `~/.dockit/` path
+
+### Proxy Configuration
+
+Standard proxy environment variables:
+
+```bash
+export HTTP_PROXY=http://proxy.corp:8080
+export HTTPS_PROXY=http://proxy.corp:8080
+```
+
+Or override the HuggingFace CDN host via code:
+
+```ts
+import { env } from '@huggingface/transformers';
+env.remoteHost = 'https://internal-mirror.corp';  // point to internal mirror
+```
+
+### Native Binaries
+
+`@lancedb/lancedb` ships prebuilt binaries for linux x64/arm64, macOS x64/arm64, and Windows x64/arm64 — no compilation needed.
+
+### Additional offline fields
+
+| Source Type | Fields (all take precedence over remote) |
+|-------------|------------------------------------------|
+| **ZIP** | `localPath` — path to pre-downloaded .zip |
+| **Maven** | `useMavenCommand: true` — uses local `~/.m2/settings.xml` (proxies, mirrors); `localJar` — pre-downloaded .jar |
+| **Antora** | `localPath` — pre-cloned repo |
+| **AsciiDoc** | `localPath` — pre-cloned repo (kept, not cleaned up) |
+| **GitHub Markdown** | `localPath` — pre-cloned repo |
+| **Source Code** | `localPath` — local repo directory |
+
+## Web UI (Optional)
+
+Dockit includes a web interface for managing entries, configuring sources, and browsing documentation.
+
+```bash
+# Start dev servers
+dockit dev
+# Or: npm run dev
+
+# Frontend → http://localhost:5173
+# Backend  → http://localhost:3001
+```
+
+1. Open http://localhost:5173 in your browser
+2. Click **New Entry** in the sidebar
+3. Add sources (including **Source Code** type) and click **Build Now**
+4. For doc sources with repos, toggle **Generate source code knowledge graph** and set the **Source Code Path**
+5. Use the embedded viewer to browse, or search across indexed content
+
+### Build Modes
+
+- **Build Now** — server-side processing with live log output
+- **Download Script** — exports a self-contained `.sh` script with all curl commands
+
+## Data Storage
+
+All runtime data is stored in `~/.dockit/` by default:
+
+| Path | Description |
+|------|-------------|
+| `~/.dockit/dockit.db` | SQLite database (entries, sources, builds) |
+| `~/.dockit/dockit.yaml` | User configuration (auto-created by `dockit init`) |
+| `~/.dockit/.lancedb/` | Vector search index (LanceDB) |
+| `~/.dockit/models/` | HuggingFace ONNX embedding model cache |
+| `~/.dockit/{entryId}/bundle/` | Built HTML documentation per entry |
+| `~/.dockit/{entryId}/sources/` | Raw source processing artifacts |
+| `~/.dockit/{entryId}/graph.json` | Knowledge graph (source-code entries) |
+
+Override with the environment variable:
+
+```bash
+export DOCKIT_DATA_DIR=/custom/path   # all data goes here instead of ~/.dockit/
+```
+
+Configuration (`dockit.yaml`) is resolved in order:
+1. `~/.dockit/dockit.yaml` (user home, persisted by `dockit init`)
+2. Project root `dockit.yaml` (backward compatibility for development)
+
+## Architecture
+
+```
+dockit/
+├── apps/
+│   ├── server/          Express + TypeScript backend (port 3001)
+│   │   └── src/
+│   │       ├── core/domain/           Domain types & knowledge-graph types
+│   │       ├── core/ports/            IKnowledgeGraph, ISourceProcessor + ports
+│   │       ├── core/usecases/         BuildUseCase, ConfigUseCase, SearchUseCase
+│   │       ├── infrastructure/graph/  GraphifyKnowledgeGraph, GraphSearchDecorator
+│   │       ├── infrastructure/source-processors/  SourceCodeSourceProcessor + others
+│   │       └── routes/graph.ts        Graph REST endpoints
+│   └── client/          React + Vite + Tailwind CSS frontend (port 5173)
+├── bin/                 CLI entry point, graph commands, init command
+├── packages/
+│   └── embeddings/      @dockit/embeddings — ONNX model wrapper (@huggingface/transformers)
+├── ~/.dockit/            Runtime data (created automatically on first run)
+│   ├── dockit.db              SQLite database
+│   ├── dockit.yaml            Entries/sources config (auto-created by `dockit init`)
+│   ├── .lancedb/              Vector search index
+│   ├── models/                HuggingFace ONNX embedding model cache
+│   ├── {entryId}/bundle/      Build outputs per entry
+│   ├── {entryId}/sources/     Raw source processing artifacts
+│   └── {entryId}/graph.json   Knowledge graph (source-code entries)
+├── dockit.yaml          Entries/sources config
+├── SKILL.md             LLM skill instructions
+├── GRAPHIFY_SOURCE_PLAN.md  Graphify feature plan
+└── package.json         npm workspace root
+```
+
+## API Overview
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET`    | `/api/entries`                    | List entries |
+| `POST`   | `/api/entries`                    | Create entry |
+| `GET`    | `/api/entries/:id`                | Get entry detail + sources |
+| `PUT`    | `/api/entries/:id`                | Update entry |
+| `DELETE` | `/api/entries/:id`                | Delete entry + all data |
+| `POST`   | `/api/entries/:id/sources`        | Add source to entry |
+| `PUT`    | `/api/sources/:id`                | Update source |
+| `DELETE` | `/api/sources/:id`                | Remove source |
+| `POST`   | `/api/entries/:id/build`          | Trigger build |
+| `GET`    | `/api/entries/:id/build-status`   | Poll build progress |
+| `GET`    | `/api/entries/:id/cli-script`     | Download CLI script |
+| `GET`    | `/api/graph/:entry/query?q=...`   | Search knowledge graph nodes |
+| `GET`    | `/api/graph/:entry/path?from=...&to=...` | Find path between nodes |
+| `GET`    | `/api/graph/:entry/gods`          | List most connected nodes |
+| `GET`    | `/api/entries/:id/search?q=term`  | Search built docs |
+| `GET`    | `/api/bundle/:entryId/*`          | Serve bundled HTML |
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Frontend | React 19, TypeScript, Vite 6, Tailwind CSS 4, React Router 7 |
+| Backend | Express 4, TypeScript, tsx |
+| Database | SQLite via better-sqlite3 |
+| MCP | @modelcontextprotocol/server 2.0.0-alpha.2 |
+| HTML Parsing | node-html-parser |
+| AsciiDoc | @asciidoctor/core |
+| Archives | unzipper |
+| Build Pipeline | Antora CLI, Git, Maven dependency plugin |
+| Markdown | marked |
+| Vector Search | LanceDB embedded (Rust native), all-MiniLM-L6-v2 via @huggingface/transformers |
+| Knowledge Graph | Graphify (Tree-sitter AST, 15+ languages) |

package/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: dockit
+description: Documentation index and search tool that provides on-demand access to up-to-date framework and library documentation for LLM context
+license: MIT
+compatibility: opencode
+metadata:
+  audience: developers
+  workflow: documentation
+---
+
+## What I do
+- Search and retrieve documentation for frameworks and libraries (e.g., Quarkus, Spring Boot, React)
+- Provide API documentation, class references, and configuration guides
+- Fetch full document content for LLM context via CLI or MCP tools
+
+## When to use me
+Use this skill when the user asks about:
+- How to use a specific framework or library
+- API documentation, class references, or configuration reference
+- Any technology listed in available dockit entries
+
+## Primary Method: CLI Commands
+
+The `dockit` CLI is the recommended way to search and retrieve documentation.
+
+### `dockit list`
+Lists all configured documentation entries. Run this first to discover what's available.
+
+### `dockit search [<entry>] <query>`
+Searches documentation. Always provide the entry name as the first argument when you know which framework the question is about.
+
+```bash
+# Scoped to a specific entry (recommended)
+dockit search react "how to create a hook"
+dockit search quarkus "configure cache"
+
+# Global search — top result per entry (when unsure which entry)
+dockit search "cache"
+```
+
+### `dockit search [<entry>] <query> --get-top [N]`
+Searches and fetches full document content for the top N results (default 3). This is the **primary command for LLMs** — it combines search + content retrieval in one step.
+
+```bash
+# Get full content for top 3 results
+dockit search react "useState" --get-top
+
+# Get full content for top 5 results, as JSON
+dockit search react "hooks" --get-top 5 --json
+```
+
+### `dockit get <entry> <path>`
+Fetches full content of a specific document by path (from search results).
+
+### `dockit build <entry>` / `dockit status <entry>`
+Builds documentation or checks build status.
+
+## Recommended Workflow
+
+### Step 1: Identify the entry
+Determine which documentation entry is relevant:
+- "How do I use useState in React?" → entry: `react`
+- "How to configure cache in Quarkus?" → entry: `quarkus`
+
+If unsure, run `dockit list` to see available entries.
+
+### Step 2: Search pattern
+**Global search** (no entry) — returns top result per entry:
+```bash
+dockit search "cache"
+```
+
+**Scoped search** (with entry) — dive deeper:
+```bash
+dockit search quarkus "cache" --get-top 3
+```
+
+Always scope to the entry once you know which framework the user is asking about.
+
+### Step 3: Refine the query
+Strip conversational filler. Keep only technical terms:
+
+| User Question | Good Query |
+|---------------|------------|
+| "How do I create a custom hook in React?" | `"create custom hook"` |
+| "What is the latest Quarkus feature for caching?" | `"cache latest feature"` |
+
+### Step 4: Handle missing builds
+If an entry shows status `pending` or `error`, build it first:
+```bash
+dockit build react
+dockit status react
+```
+
+## Alternative: MCP Tools
+
+If Dockit is configured as an MCP server, use `dockit_*` tools instead of CLI commands:
+
+| MCP Tool | CLI Equivalent |
+|----------|----------------|
+| `dockit_list_entries` | `dockit list` |
+| `dockit_global_search` | `dockit search "query"` |
+| `dockit_search` | `dockit search <entry> "query"` |
+| `dockit_get_doc` | `dockit get <entry> <path>` |
+| `dockit_build` / `dockit_build_status` | `dockit build` / `dockit status` |
+| `dockit_graph_query` | (MCP only) |
+| `dockit_graph_path` | (MCP only) |
+| `dockit_graph_explain` | (MCP only) |
+| `dockit_graph_gods` | (MCP only) |
+
+## Source Code Entries (Knowledge Graph)
+
+For entries with `source-code` sources, the primary query mechanism is the **knowledge graph** instead of text search. Graphify's Tree-sitter AST pass parses 15+ languages and produces structural edges (*calls*, *imports*, *inherits*).
+
+### Graph MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `dockit_graph_query <entry> <query>` | Search graph nodes by name, file, or type |
+| `dockit_graph_path <entry> <from> <to>` | Find shortest dependency path between two nodes |
+| `dockit_graph_explain <entry> <node>` | Get node details with edges and connections |
+| `dockit_graph_gods <entry>` | List most connected (highest-degree) nodes |
+
+### Behavior by Entry Type
+
+| Entry Type | Search | Graph Query |
+|------------|--------|-------------|
+| Source-code only | `dockit search` returns empty | Use `dockit_graph_*` tools |
+| Mixed (docs + code) | `dockit search` works + results graph-boosted | `dockit_graph_*` tools work |
+| Docs only | `dockit search` works | No graph tools |
+
+## Notes
+- Documentation is plain text extracted from HTML
+- Content is truncated at 50KB per document
+- Entries start as `pending` and must be built before searchable
+
+## Always Show Source
+
+After answering with documentation content, always display the source in a table at the end:
+
+| Field | Value |
+|-------|-------|
+| **Type** | `<source type>` |
+| **Label** | `<source label>` |
+| **Repo** | `<repoUrl>` |
+| **Source Path** | `<sourcePath>` |
+| **Version** | `<entry version>` |
+
+To get source details, use `--json` flag with search or check `dockit list --json`. Source fields come from the entry's `sources` array in `dockit.yaml`:
+- `type` — source type (e.g., `github-markdown`, `asciidoc`, `maven`, `source-code`)
+- `label` — human-readable label
+- `repoUrl` or `localPath` — repository URL or local path
+- `sourcePath` — path within the repo
+- Entry `version` — the version of the documentation entry