@lon-ask/dockit 0.1.1 → 0.1.2

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dockit
-description: Documentation index and search tool that provides on-demand access to up-to-date framework and library documentation for LLM context
+description: Documentation index and search tool providing on-demand framework/library docs and source code knowledge graphs for LLM context
 license: MIT
 compatibility: opencode
 metadata:
@@ -8,147 +8,138 @@ metadata:
   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
+## What dockit does
 
-## 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
+Dockit is a local documentation hub. It indexes documentation from multiple sources (GitHub Markdown, AsciiDoc, Antora, Maven Javadoc, ZIP archives) and builds source code knowledge graphs (Tree-sitter AST via Graphify). It provides hybrid TF-IDF + vector semantic search across all indexed content.
 
-## Primary Method: CLI Commands
+Run it from the terminal — no server process required. No internet needed after build.
 
-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.
+## Installation
 
 ```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"
+npm install -g @lon-ask/dockit
 ```
 
-### `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.
+Or use `npx` without installing:
 
 ```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
+npx @lon-ask/dockit <command>
 ```
 
-### `dockit get <entry> <path>`
-Fetches full content of a specific document by path (from search results).
+All data is stored in `~/.dockit/` by default. Override with `DOCKIT_DATA_DIR`.
+
+## When to use dockit
+
+Use when you need:
+- Up-to-date framework/library documentation instead of stale training data
+- API reference, class docs, or configuration guides
+- Source code structure analysis (imports, calls, inheritance graphs)
+- To find which files/modules a function touches in a codebase
 
-### `dockit build <entry>` / `dockit status <entry>`
-Builds documentation or checks build status.
+## Core Workflow
 
-## Recommended Workflow
+### Step 1: Discover available documentation
 
-### 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`
+```bash
+dockit list
+# or
+npx @lon-ask/dockit list
+```
 
-If unsure, run `dockit list` to see available entries.
+### Step 2: Global search (find the right entry)
 
-### Step 2: Search pattern
-**Global search** (no entry) — returns top result per entry:
 ```bash
 dockit search "cache"
+# Returns top result per built entry
 ```
 
-**Scoped search** (with entry) — dive deeper:
+### Step 3: Scoped search with full content
+
+```bash
+dockit search quarkus "configure cache" --get-top 3
+```
+
+The `--get-top` flag fetches full document text for the top N results. This is the primary command for LLMs — it combines search + retrieval in one invocation.
+
+### Step 4: Knowledge graph queries (source-code entries)
+
+For entries with `source-code` sources:
+
 ```bash
-dockit search quarkus "cache" --get-top 3
+dockit graph query my-project "database" --limit 10     # find nodes by name/file/type
+dockit graph gods my-project                            # most-connected nodes
+dockit graph path my-project "app.ts" "database.ts"     # dependency path
+dockit graph explain my-project "createApp"             # node details + connections
 ```
 
-Always scope to the entry once you know which framework the user is asking about.
+## CLI Reference
+
+| Command | Purpose |
+|---------|---------|
+| `dockit list` | List all configured entries |
+| `dockit search [<entry>] <query>` | Search docs (scoped or global) |
+| `dockit search [<entry>] <query> --get-top [N]` | Search + full content for top N |
+| `dockit get <entry> <path>` | Fetch specific document by path |
+| `dockit build <entry>` | Build/rebuild documentation |
+| `dockit status <entry>` | Check build status |
+| `dockit init --path <dir> [--code-path <sub>]` | Index a local project |
+| `dockit graph query <entry> <query>` | Search graph nodes |
+| `dockit graph path <entry> <from> <to>` | Dependency path between nodes |
+| `dockit graph gods <entry>` | Highest-degree (most connected) nodes |
+| `dockit graph explain <entry> <node>` | Node details with edges |
+
+## Query Refinement
 
-### Step 3: Refine the query
-Strip conversational filler. Keep only technical terms:
+Strip conversational filler. Keep only technical keywords:
 
-| User Question | Good Query |
+| 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"` |
+| "What's the Quarkus caching configuration?" | `"caching configuration"` |
+| "How does the auth middleware work?" | `"auth middleware"` |
+| "Find all files that import database.ts" | `graph query my-project "database.ts"` |
+
+## Entry Types and Behavior
+
+| Entry has | `dockit search` | `dockit graph` |
+|-----------|----------------|-----------------|
+| Docs only | Returns results | No graph available |
+| Source code only | Returns empty | Use graph tools |
+| Docs + code | Returns results (graph-boosted) | Graph tools work |
+
+## Build Status
+
+Entries start as `pending`. Build them before searching:
 
-### Step 4: Handle missing builds
-If an entry shows status `pending` or `error`, build it first:
 ```bash
-dockit build react
-dockit status react
+dockit build quarkus
+dockit status quarkus    # wait for "ready"
 ```
 
-## Alternative: MCP Tools
+If an entry shows `error`, check the build log via `dockit status <entry> --json`.
+
+## MCP Tools
 
-If Dockit is configured as an MCP server, use `dockit_*` tools instead of CLI commands:
+If configured as an MCP server, use these tools instead of CLI:
 
 | MCP Tool | CLI Equivalent |
 |----------|----------------|
 | `dockit_list_entries` | `dockit list` |
+| `dockit_find_entry` | — |
 | `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
+| `dockit_build` | `dockit build <entry>` |
+| `dockit_build_status` | `dockit status <entry>` |
+| `dockit_graph_query` | `dockit graph query` |
+| `dockit_graph_path` | `dockit graph path` |
+| `dockit_graph_explain` | `dockit graph explain` |
+| `dockit_graph_gods` | `dockit graph gods` |
 
-| 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 |
+## Key Constraints
 
-## 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
+- Content is truncated at 50 KB per document
+- Documents must be built before searchable (status = `ready`)
+- Knowledge graph requires `graphify` Python package and source-code source type
+- All data is local. No cloud, no API keys required

package/apps/client/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Dockit — Documentation Hub</title>
+  </head>
+  <body class="antialiased">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/apps/client/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@dockit/client",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "lucide-react": "^0.469.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.1.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "@types/react": "^19.0.3",
+    "@types/react-dom": "^19.0.2",
+    "@vitejs/plugin-react": "^4.3.4",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.7"
+  }
+}

package/apps/client/src/App.tsx

@@ -0,0 +1,18 @@
+import { Routes, Route } from 'react-router-dom';
+import Layout from './components/Layout';
+import EntryList from './components/EntryList';
+import EntryForm from './components/EntryForm';
+import EntryDetail from './components/EntryDetail';
+
+export default function App() {
+  return (
+    <Layout>
+      <Routes>
+        <Route path="/" element={<EntryList />} />
+        <Route path="/entries/new" element={<EntryForm />} />
+        <Route path="/entries/:id/edit" element={<EntryForm />} />
+        <Route path="/entries/:id" element={<EntryDetail />} />
+      </Routes>
+    </Layout>
+  );
+}

package/apps/client/src/api/client.ts

@@ -0,0 +1,54 @@
+import type { Entry, EntryDetail, Source, SourceConfig, BuildStatusResponse, SearchResult } from '../types';
+
+const BASE = '/api';
+
+async function request<T>(url: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(`${BASE}${url}`, {
+    headers: { 'Content-Type': 'application/json' },
+    ...options,
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({ error: res.statusText }));
+    throw new Error(body.error || `Request failed: ${res.status}`);
+  }
+  return res.json();
+}
+
+export const api = {
+  entries: {
+    list: () => request<Entry[]>('/entries'),
+    get: (id: string) => request<EntryDetail>(`/entries/${id}`),
+    create: (data: { name: string; version: string; description?: string }) =>
+      request<Entry>('/entries', { method: 'POST', body: JSON.stringify(data) }),
+    update: (id: string, data: { name?: string; version?: string; description?: string }) =>
+      request<Entry>(`/entries/${id}`, { method: 'PUT', body: JSON.stringify(data) }),
+    delete: (id: string) =>
+      request<{ success: boolean }>(`/entries/${id}`, { method: 'DELETE' }),
+  },
+
+  sources: {
+    create: (entryId: string, data: { type: string; label: string; config: SourceConfig }) =>
+      request<Source>(`/entries/${entryId}/sources`, { method: 'POST', body: JSON.stringify(data) }),
+    update: (id: string, data: { label?: string; config?: SourceConfig }) =>
+      request<Source>(`/sources/${id}`, { method: 'PUT', body: JSON.stringify(data) }),
+    delete: (id: string) =>
+      request<{ success: boolean }>(`/sources/${id}`, { method: 'DELETE' }),
+  },
+
+  build: {
+    trigger: (entryId: string) =>
+      request<{ buildId: string; status: string }>(`/entries/${entryId}/build`, { method: 'POST' }),
+    status: (entryId: string) =>
+      request<BuildStatusResponse>(`/entries/${entryId}/build-status`),
+    cliScript: (entryId: string) =>
+      fetch(`${BASE}/entries/${entryId}/cli-script`).then((r) => r.text()),
+  },
+
+  search: (entryId: string, q: string) =>
+    request<SearchResult[]>(`/entries/${entryId}/search?q=${encodeURIComponent(q)}`),
+
+  searchGlobal: (q: string) =>
+    request<Array<SearchResult & { entryId: string; entryName: string; entryVersion: string }>>(`/search?q=${encodeURIComponent(q)}`),
+
+  bundleUrl: (entryId: string) => `${BASE}/bundle/${entryId}/`,
+};

package/apps/client/src/components/BuildPanel.tsx

@@ -0,0 +1,77 @@
+import { useEffect, useState, useRef } from 'react';
+import { Terminal, ChevronDown, ChevronRight, Loader2, CheckCircle, AlertCircle } from 'lucide-react';
+import type { BuildStatusResponse } from '../types';
+import { api } from '../api/client';
+
+interface Props {
+  entryId: string;
+  refreshKey: number;
+}
+
+export default function BuildPanel({ entryId, refreshKey }: Props) {
+  const [status, setStatus] = useState<BuildStatusResponse | null>(null);
+  const [open, setOpen] = useState(false);
+  const logEndRef = useRef<HTMLDivElement>(null);
+  const intervalRef = useRef<ReturnType<typeof setInterval> | undefined>(undefined);
+
+  useEffect(() => {
+    const fetch = async () => {
+      try {
+        const data = await api.build.status(entryId);
+        setStatus(data);
+        if (data.status === 'building') {
+          setOpen(true);
+        }
+        if (data.status === 'ready' || data.status === 'error') {
+          if (intervalRef.current) {
+            clearInterval(intervalRef.current);
+          }
+        }
+      } catch {
+        // ignored
+      }
+    };
+    fetch();
+    intervalRef.current = setInterval(fetch, 1500);
+    return () => { if (intervalRef.current) clearInterval(intervalRef.current); };
+  }, [entryId, refreshKey]);
+
+  if (!status || status.status === 'none') return null;
+
+  const accentColor = status.status === 'ready' ? 'bg-success' :
+                      status.status === 'error' ? 'bg-danger' : 'bg-warning';
+
+  return (
+    <div className="bg-surface ring-1 ring-border rounded-lg overflow-hidden">
+      <button
+        onClick={() => setOpen(!open)}
+        className="w-full flex items-center gap-2 px-3 py-2 hover:bg-bg-alt transition-colors text-left"
+      >
+        {open ? <ChevronDown size={14} className="text-text-muted" /> : <ChevronRight size={14} className="text-text-muted" />}
+        <Terminal size={14} className="text-text-dim" />
+        <span className="text-xs font-medium text-text">Build Log</span>
+        <span className="flex items-center gap-1 ml-auto">
+          {status.status === 'building' && <Loader2 size={12} className="animate-spin text-warning" />}
+          {status.status === 'ready' && <CheckCircle size={12} className="text-success" />}
+          {status.status === 'error' && <AlertCircle size={12} className="text-danger" />}
+          <span className={`text-[11px] font-medium ${
+            status.status === 'ready' ? 'text-success' :
+            status.status === 'error' ? 'text-danger' :
+            'text-warning'
+          }`}>
+            {status.status.charAt(0).toUpperCase() + status.status.slice(1)}
+          </span>
+        </span>
+      </button>
+      {open && (
+        <div className="relative">
+          <div className={`absolute left-0 top-0 bottom-0 w-0.5 ${accentColor}`} />
+          <div className="bg-terminal-bg text-terminal-fg p-3 pl-4 max-h-48 overflow-auto font-mono text-[11px] leading-relaxed">
+            <pre className="whitespace-pre-wrap">{status.log || 'Waiting for build to start...'}</pre>
+            <div ref={logEndRef} />
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/apps/client/src/components/DocViewer.tsx

@@ -0,0 +1,76 @@
+import { useState, useEffect } from 'react';
+import { ExternalLink, Maximize2, Minimize2, FileWarning, FileText } from 'lucide-react';
+import { api } from '../api/client';
+
+interface Props {
+  entryId: string;
+  selectedFile?: string;
+}
+
+export default function DocViewer({ entryId, selectedFile }: Props) {
+  const [expanded, setExpanded] = useState(false);
+  const [error, setError] = useState(false);
+  const url = selectedFile
+    ? `${api.bundleUrl(entryId)}${selectedFile}`
+    : api.bundleUrl(entryId);
+
+  useEffect(() => { setError(false); }, [selectedFile]);
+
+  if (!selectedFile) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full gap-3 text-center">
+        <div className="w-14 h-14 rounded-2xl bg-bg-alt flex items-center justify-center">
+          <FileText size={26} className="text-text-muted" />
+        </div>
+        <div>
+          <p className="text-sm text-text-dim font-medium">No document selected</p>
+          <p className="text-xs text-text-muted mt-1">Search for a document and click a result to view it here.</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full gap-3 text-center">
+        <div className="w-14 h-14 rounded-2xl bg-bg-alt flex items-center justify-center">
+          <FileWarning size={26} className="text-text-muted" />
+        </div>
+        <div>
+          <p className="text-sm text-text-dim font-medium">Could not load document</p>
+          <p className="text-xs text-text-muted mt-1">The documentation may not be built yet. Click &ldquo;Build&rdquo; to generate it.</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={`flex flex-col h-full ${expanded ? 'fixed inset-0 z-40 bg-bg p-4' : ''}`}>
+      <div className="flex items-center gap-2 mb-2 shrink-0">
+        <span className="text-xs text-text-muted font-mono truncate flex-1">{selectedFile}</span>
+        <button
+          onClick={() => setExpanded(!expanded)}
+          className="p-1 rounded text-text-muted hover:text-text hover:bg-bg-alt transition-colors"
+          title={expanded ? 'Exit fullscreen' : 'Fullscreen'}
+        >
+          {expanded ? <Minimize2 size={14} /> : <Maximize2 size={14} />}
+        </button>
+        <a
+          href={url}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="p-1 rounded text-text-muted hover:text-text hover:bg-bg-alt transition-colors"
+          title="Open in new tab"
+        >
+          <ExternalLink size={14} />
+        </a>
+      </div>
+      <iframe
+        src={url}
+        onError={() => setError(true)}
+        className="flex-1 w-full ring-1 ring-border rounded-lg bg-surface min-h-0"
+        title="Documentation Viewer"
+      />
+    </div>
+  );
+}