docs-kit 0.1.3__tar.gz → 0.1.4__tar.gz

docs_kit-0.1.4/AGENTS.md

@@ -0,0 +1,66 @@
+# docs-kit — Agent Instructions
+
+## Scope
+
+This document applies to AI agents working on the **docs-kit** codebase: a **PyPI** package (and optional **npx** wrapper) that **fetches documentation** (GitBook, Mintlify, or local files), **stores and embeds it locally** (markdown on disk + Qdrant), and **teaches coding agents to call the CLI** via **installed skills** — not via an MCP server.
+
+---
+
+## What the product does
+
+1. **Fetch** — Fetchers use `/llms-full.txt` and `/llms.txt` on public doc sites; **Mintlify** also falls back to `/sitemap.xml` when needed. **GitBook** and **Mintlify** are supported; `docs-kit ingest` accepts `--provider auto|gitbook|mintlify`.
+2. **Local storage** — `docs-kit fetch` writes `.md` files; `docs-kit ingest` chunks, embeds with FastEmbed (dense + sparse/BM25), and upserts into local Qdrant. Concurrent CLI processes coordinate with **filelock** on the Qdrant path.
+3. **Agent integration** — `docs-kit install <agent>` installs **skill templates** (`docs_kit/templates/`) so agents run **`docs-kit` CLI** commands (`query`, `list`, `ingest`, `remove`, `inspect`, `doctor`, etc.). **Claude Desktop** gets a zip to upload in the app; **Cursor** may also get a home-level `AGENTS.md` fallback fragment.
+4. **Install targets** (see `INSTALL_TARGETS` in `docs_kit/cli/commands.py`): `claude-code`, `claude-desktop`, `cursor`, `codex`, `codex-app`, `codex-desktop`, `opencode`.
+
+The **npx** package under `npx-wrapper/` ensures Python 3.11+ and installs/runs the **`docs-kit`** Python module; behavior lives in Python.
+
+---
+
+## Security (Non-Negotiable)
+
+- **MUST NOT** read, access, or reference `.env`, `.env.local`, `.env.*`, or any secret/credentials files.
+- **MUST NOT** recommend reading environment files. If config is needed, ask the user for non-sensitive details.
+- **MUST** treat `.env` files as if they do not exist.
+
+---
+
+## Verification After Changes
+
+From the repository root:
+
+```bash
+pytest tests/ -v
+```
+
+- **MUST NOT** claim work is complete without a successful test run when behavior or dependencies changed.
+
+---
+
+## Git Commit Workflow
+
+When the user asks to commit, stage, or write a commit message:
+
+1. **MUST** analyze staged/unstaged changes via `git status` and `git diff` in the relevant git root.
+2. **MUST** write a commit message following Conventional Commits:
+   - `feat:` — new feature
+   - `fix:` — bug fix
+   - `chore:` — maintenance, deps, config
+   - `docs:` — documentation only
+   - `style:` — formatting, no logic change
+   - `refactor:` — code restructure
+   - `test:` — tests only
+   - `perf:` — performance
+3. **SHOULD** keep subject line under 50 chars, imperative mood; use bullet points in body.
+4. **SHOULD** suggest splitting into atomic commits if changes span unrelated concerns.
+
+---
+
+## Project Context (Brief)
+
+- **Package name:** `docs-kit` (import `docs_kit`, CLI `docs-kit`). **Python:** `>=3.11,<3.14` (`pyproject.toml`); no `mcp` dependency in this tree.
+- **Main types:** `DocsKitConfig` (`docs_kit/core/config.py`), `DocsKitAgent` (`docs_kit/agent.py`).
+- **CLI:** `docs_kit/cli/commands.py` + `docs_kit/cli/__main__.py` — `init`, `fetch`, `ingest`, `query`, `inspect`, `doctor`, `install`, `remove`, `list`.
+- **Fetchers:** `docs_kit/connectors/fetchers/gitbook.py`, `mintlify.py`, shared `llms_txt` helpers.
+- **Skills / install artifacts:** `docs_kit/templates/` (e.g. `skill.md`, `claude_code_skill.md`, `cursor_agents_md.md`).
+- **Docs:** [README.md](README.md) for user-facing quickstart (if it diverges from the repo, trust the code and `docs/project-overview.md` for architecture).

{docs_kit-0.1.3 → docs_kit-0.1.4}/CLAUDE.md

@@ -4,13 +4,12 @@
 
 **docs-kit** is a distributable toolkit (PyPI **`docs-kit`**, optional **npm/npx** wrapper) that:
 
-1. **Pulls** documentation from public **GitBook** sites via AI-oriented endpoints (`/llms-full.txt` or `/llms.txt` and linked pages).
+1. **Pulls** documentation from public **GitBook** and **Mintlify** sites via AI-oriented endpoints (`/llms-full.txt` or `/llms.txt` and linked pages).
 2. **Stores** content locally — either as downloaded `.md` files (`docs-kit fetch`) or in a **local Qdrant** vector store after embedding (`docs-kit ingest`).
 3. **Ingests** with **local embeddings** (FastEmbed by default; no API keys required for embeddings).
-4. **Serves** an **MCP (Model Context Protocol) server** so **Claude Code**, **Claude Desktop**, **Cursor**, and other MCP-capable agents can query the knowledge base (`search_docs`, `list_sources`, `get_collection_info`, `get_full_document`).
-5. **Installs** MCP wiring via `docs-kit install claude-code | claude-desktop | cursor`.
+4. **Installs skill files** into AI agents (Claude Code, Cursor, Codex, OpenCode, Claude Desktop) that teach them to call `docs-kit` CLI commands directly — no background server required.
 
-**Pitch:** Point at any public GitBook docs, embed locally, expose them to your coding agents through MCP.
+**Pitch:** Point at any public docs, embed locally, let your coding agents query them directly via CLI skills.
 
 **Target:** Developers who want product/docs RAG in the agent loop without shipping docs to a remote embedding API.
 
@@ -20,7 +19,7 @@
 
 | Channel | What it is |
 |---------|------------|
-| **PyPI** | Canonical install: `pip install docs-kit`. CLI entry: `docs-kit`. |
+| **PyPI** | Canonical install: `pipx install docs-kit`. CLI entry: `docs-kit`. |
 | **npm/npx** | `npx-wrapper/` — thin Node shim that ensures Python 3.11+ and `pip install docs-kit`, then runs `python -m docs_kit …`. |
 
 ---
@@ -29,10 +28,11 @@
 
 | Path | Purpose |
 |------|---------|
-| `docs_kit/` | Python package: `DocsKitAgent`, GitBook fetcher, parsers, FastEmbed, Qdrant store, MCP server, Click CLI |
-| `docs_kit/cli/` | CLI (`docs-kit init`, `fetch`, `ingest`, `serve`, `install`, `query`, `inspect`, `doctor`) |
-| `docs_kit/mcp/` | FastMCP server (`stdio` default; `sse` with optional deps) |
+| `docs_kit/` | Python package: `DocsKitAgent`, GitBook/Mintlify fetchers, parsers, FastEmbed, Qdrant store, Click CLI |
+| `docs_kit/cli/` | CLI (`docs-kit init`, `fetch`, `ingest`, `install`, `query`, `inspect`, `list`, `remove`, `doctor`) |
+| `docs_kit/templates/` | Skill/instruction template files installed by `docs-kit install` |
 | `docs_kit/connectors/fetchers/gitbook.py` | GitBook `llms-full.txt` / `llms.txt` fetch |
+| `docs_kit/connectors/fetchers/mintlify.py` | Mintlify fetch with sitemap.xml fallback |
 | `npx-wrapper/` | npm package wrapping the Python CLI |
 | `tests/` | pytest suite |
 | `data/sample_docs/` | Sample markdown for local ingest tests |
@@ -43,8 +43,8 @@
 
 - **Python** ≥ 3.11, **Click**, **Pydantic** / **pydantic-settings**, **httpx**, **PyYAML**
 - **Embeddings:** FastEmbed (local)
-- **Vector store:** Qdrant (local path, e.g. `.docs-kit/qdrant` in config)
-- **MCP:** `mcp` + FastMCP; optional **uvicorn** / **starlette** for SSE (`docs-kit[sse]`)
+- **Vector store:** Qdrant (local embedded, path `~/.docs-kit/qdrant` for user config)
+- **Concurrency:** `filelock` for serializing concurrent embedded Qdrant access
 
 ---
 
@@ -62,7 +62,7 @@
 From the project root (where `pyproject.toml` lives):
 
 ```bash
-pytest tests/ -v
+/usr/local/bin/python3.13 -m pytest tests/ -v
 ```
 
 After substantive changes, run the full test suite before claiming completion.
@@ -78,8 +78,8 @@ After substantive changes, run the full test suite before claiming completion.
 
 ## Key Paths & Commands
 
-- **Config:** `docs-kit.yaml` (from `docs-kit init`) — embedding model, Qdrant `local_path`, MCP transport/port.
-- **Fetch only:** `docs-kit fetch <gitbook-url> --output docs-kit-docs`
+- **Config:** auto-created at `~/.docs-kit/docs-kit.yaml` on first use; or project-local `docs-kit.yaml` via `docs-kit init`
+- **Fetch only:** `docs-kit fetch <url> --output docs-kit-docs`
 - **Ingest URL or path:** `docs-kit ingest https://example.gitbook.io/docs` or `docs-kit ingest ./path/to/markdown`
-- **MCP:** `docs-kit serve` (stdio); SSE requires `docs-kit[sse]` and config/flags for `sse`.
-- **Agent setup:** `docs-kit install claude-code` (optional `--project` for project-level Claude Code).
+- **Agent setup:** `docs-kit install claude-code` (or `cursor`, `codex`, `opencode`, `claude-desktop`)
+- **No MCP server:** `serve` and `stop` commands do not exist; agents call CLI directly via installed skill files

docs_kit-0.1.4/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.3
+Name: docs-kit
+Version: 0.1.4
+Summary: Fetch docs, embed locally, expose to AI agents via skills.
+License: MIT License
+        
+        Copyright (c) 2026 Docs Kit Limited
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Requires-Python: <3.14,>=3.11
+Requires-Dist: click>=8.0.0
+Requires-Dist: fastembed>=0.6.0
+Requires-Dist: filelock>=3.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.2.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: qdrant-client>=1.10.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# docs-kit
+
+[![PyPI version](https://img.shields.io/pypi/v/docs-kit)](https://pypi.org/project/docs-kit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/docs-kit)](https://pypi.org/project/docs-kit/)
+[![CI](https://github.com/docs-kit/docs-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/docs-kit/docs-kit/actions/workflows/ci.yml)
+
+Fetch docs from GitBook, Mintlify, or local files, embed them locally, and teach AI agents to search them via installed **skills** (CLI commands). No API keys for the default embedding path. No background server or MCP.
+
+## What it does
+
+- Fetches public docs from **GitBook** and **Mintlify** sites via `/llms-full.txt` and `/llms.txt`, with a **sitemap.xml** fallback on Mintlify when those endpoints are missing
+- **`docs-kit ingest`:** `--provider auto` (default) uses a combined strategy (llms endpoints → sitemap). **`--provider gitbook`** uses the GitBook-only fetcher; **`--provider mintlify`** uses the same pipeline as `auto`
+- Ingests local `.md` and `.txt` files
+- Stores vectors in **embedded Qdrant** on disk — typically `~/.docs-kit/qdrant` when using the auto-created user config, or `.docs-kit/qdrant` (resolved relative to your `docs-kit.yaml`) for a project-local config from `docs-kit init`
+- **Hybrid retrieval** (dense embeddings + sparse / BM25-style vectors) for `docs-kit query` and agent-driven queries
+- Installs **skill files** into Claude Code, Cursor, Codex, OpenCode, and Claude Desktop so agents run `docs-kit` over the shell
+- Concurrent CLI runs coordinate with a **file lock** on the local Qdrant path
+
+## Install
+
+Recommended: **`pipx`** so `docs-kit` is on your PATH:
+
+```bash
+pipx install docs-kit
+```
+
+Install `pipx` if needed:
+
+```bash
+brew install pipx
+pipx ensurepath
+```
+
+Or **`pip`** inside a virtual environment:
+
+```bash
+pip install docs-kit
+```
+
+Optional: the repo includes an **`npx-wrapper/`** npm package that bootstraps Python and runs the same CLI (`npx docs-kit …` when published or linked locally).
+
+## Quickstart
+
+```bash
+# 1. Install (once)
+pipx install docs-kit
+
+# 2. Ingest docs
+docs-kit ingest https://docs.example.com
+
+# 3. Install skill into your agent
+docs-kit install claude-code   # or: cursor, codex, opencode, claude-desktop
+
+# 4. Use the agent — it can run docs-kit query / list / ingest when relevant
+```
+
+No server to start. On first use, config and the default vector store path are created under **`~/.docs-kit/`** unless you use a project-local `docs-kit.yaml`.
+
+## How it works
+
+docs-kit installs a **skill** (Markdown + YAML frontmatter) into each tool’s skills directory. The skill tells the agent when to use docs-kit and which commands to run (`query`, `list`, `ingest`, `remove`, `inspect`, `doctor`, …). Agents execute **`docs-kit`** via their normal terminal integration.
+
+For more architecture detail (config resolution, layout, security posture), see [docs/project-overview.md](docs/project-overview.md).
+
+## Install targets
+
+| Command | Where the skill lands |
+|---------|------------------------|
+| `docs-kit install claude-code` | `~/.claude/skills/docs-kit/SKILL.md` |
+| `docs-kit install codex` | `~/.agents/skills/docs-kit/SKILL.md` |
+| `docs-kit install cursor` | `~/.cursor/skills/docs-kit/SKILL.md` + marked block in `~/.cursor/AGENTS.md` when needed |
+| `docs-kit install opencode` | `~/.config/opencode/skills/docs-kit/SKILL.md` (and may mirror under `~/.agents/skills/` if absent) |
+| `docs-kit install claude-desktop` | `~/.docs-kit/exports/claude-desktop/docs-kit.zip` — upload via Claude Desktop **Customize → Skills** |
+
+`codex-app` and `codex-desktop` are accepted aliases for the Codex install path.
+
+Use **`--project`** with `claude-code` for `.claude/skills/docs-kit/SKILL.md` in the current repo.
+
+## Commands
+
+### `docs-kit install <agent>`
+
+Install the docs-kit skill into a supported agent.
+
+```bash
+docs-kit install claude-code
+docs-kit install cursor
+docs-kit install codex
+docs-kit install opencode
+docs-kit install claude-desktop
+docs-kit install claude-code --project
+docs-kit install cursor --config ./docs-kit.yaml
+```
+
+If no config is found, **`~/.docs-kit/docs-kit.yaml`** is created automatically (non-project installs).
+
+### `docs-kit ingest <path-or-url>`
+
+Ingest a local file, directory, or documentation URL.
+
+```bash
+docs-kit ingest ./docs
+docs-kit ingest https://docs.example.com
+docs-kit ingest https://docs.example.com --provider gitbook
+docs-kit ingest ./docs --recreate
+```
+
+`--provider`: `auto` (default), `gitbook`, or `mintlify`.
+
+### `docs-kit query <text>`
+
+Run hybrid retrieval from the CLI.
+
+```bash
+docs-kit query "How do I authenticate?"
+docs-kit query "getting started" --limit 3
+docs-kit query "..." --config ./docs-kit.yaml
+```
+
+### `docs-kit list`
+
+List ingested sources with ingestion timestamps.
+
+```bash
+docs-kit list
+docs-kit list --config ./docs-kit.yaml
+```
+
+### `docs-kit fetch <url>`
+
+Download **GitBook** docs as Markdown files only (does not embed). For Mintlify or mixed hosting, use **`docs-kit ingest`** or copy files locally first.
+
+```bash
+docs-kit fetch https://docs.example.com
+docs-kit fetch https://docs.example.com --output ./downloaded-docs
+```
+
+### `docs-kit remove <source>`
+
+Remove an ingested source by URL or file path.
+
+```bash
+docs-kit remove https://docs.example.com/page
+docs-kit remove ./docs/getting-started.md
+```
+
+### `docs-kit inspect`
+
+Show collection stats and embedding settings.
+
+```bash
+docs-kit inspect
+docs-kit inspect --config ./docs-kit.yaml
+```
+
+### `docs-kit doctor`
+
+Check `docs-kit` on PATH, effective config, Qdrant path / connectivity, and which skills are installed.
+
+```bash
+docs-kit doctor
+docs-kit doctor --config ./docs-kit.yaml
+```
+
+### `docs-kit init`
+
+Create a project-local **`docs-kit.yaml`** (optional if you rely on `~/.docs-kit/docs-kit.yaml`).
+
+```bash
+docs-kit init
+docs-kit init --dir ./sandbox
+```
+
+## Configuration
+
+**Resolution order:** `--config` → `./docs-kit.yaml` in the current working directory → `~/.docs-kit/docs-kit.yaml` (created on first use when applicable).
+
+Example **project-local** `docs-kit.yaml` from `docs-kit init`:
+
+```yaml
+embedding:
+  provider: fastembed
+  model: BAAI/bge-small-en-v1.5
+
+vector_store:
+  provider: qdrant
+  local_path: .docs-kit/qdrant   # resolved relative to this file’s directory
+  collection_name: knowledge_base
+  retrieval_limit: 5
+  score_threshold: 0.35
+
+ingestion:
+  chunk_size: 800
+  chunk_overlap: 120
+  bm25_model: Qdrant/bm25
+```
+
+The auto-created **user** config under `~/.docs-kit/` sets `local_path` to an absolute directory under **`~/.docs-kit/qdrant`**. To use a **remote** Qdrant instance, set `vector_store.url` and leave local storage unused.
+
+## Supported sources
+
+| Source | Strategy |
+|--------|----------|
+| GitBook sites | `/llms-full.txt` → `/llms.txt` (GitBook fetcher); `auto` / `mintlify` use the broader pipeline below |
+| Mintlify & typical llms.txt sites | `/llms-full.txt` → `/llms.txt` → `/sitemap.xml` |
+| Local `.md` / `.txt` | Read from disk |
+
+## Requirements
+
+- **Python 3.11–3.13** (`requires-python` excludes 3.14+ while dependencies such as `onnxruntime` lack wheels)
+- Disk space for the embedding model (on the order of tens of MB for the default model)
+
+If your default `python` is 3.14:
+
+```bash
+pipx install docs-kit --python python3.13
+```
+
+## Migration from v0.1.x
+
+Older releases configured an **MCP server** in agent settings. That integration has been removed in favor of **skills + CLI**.
+
+1. Remove legacy **`mcpServers.docs-kit`** (or equivalent) from `~/.claude/settings.json`, Cursor MCP config, `~/.codex/config.toml`, etc.
+2. Run **`docs-kit install <agent>`** again to install skills.
+3. Existing **`~/.docs-kit/docs-kit.yaml`** and ingested data remain valid; any unused **`mcp:`** section in YAML can be deleted for clarity.

docs_kit-0.1.4/README.md

@@ -0,0 +1,226 @@
+# docs-kit
+
+[![PyPI version](https://img.shields.io/pypi/v/docs-kit)](https://pypi.org/project/docs-kit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/docs-kit)](https://pypi.org/project/docs-kit/)
+[![CI](https://github.com/docs-kit/docs-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/docs-kit/docs-kit/actions/workflows/ci.yml)
+
+Fetch docs from GitBook, Mintlify, or local files, embed them locally, and teach AI agents to search them via installed **skills** (CLI commands). No API keys for the default embedding path. No background server or MCP.
+
+## What it does
+
+- Fetches public docs from **GitBook** and **Mintlify** sites via `/llms-full.txt` and `/llms.txt`, with a **sitemap.xml** fallback on Mintlify when those endpoints are missing
+- **`docs-kit ingest`:** `--provider auto` (default) uses a combined strategy (llms endpoints → sitemap). **`--provider gitbook`** uses the GitBook-only fetcher; **`--provider mintlify`** uses the same pipeline as `auto`
+- Ingests local `.md` and `.txt` files
+- Stores vectors in **embedded Qdrant** on disk — typically `~/.docs-kit/qdrant` when using the auto-created user config, or `.docs-kit/qdrant` (resolved relative to your `docs-kit.yaml`) for a project-local config from `docs-kit init`
+- **Hybrid retrieval** (dense embeddings + sparse / BM25-style vectors) for `docs-kit query` and agent-driven queries
+- Installs **skill files** into Claude Code, Cursor, Codex, OpenCode, and Claude Desktop so agents run `docs-kit` over the shell
+- Concurrent CLI runs coordinate with a **file lock** on the local Qdrant path
+
+## Install
+
+Recommended: **`pipx`** so `docs-kit` is on your PATH:
+
+```bash
+pipx install docs-kit
+```
+
+Install `pipx` if needed:
+
+```bash
+brew install pipx
+pipx ensurepath
+```
+
+Or **`pip`** inside a virtual environment:
+
+```bash
+pip install docs-kit
+```
+
+Optional: the repo includes an **`npx-wrapper/`** npm package that bootstraps Python and runs the same CLI (`npx docs-kit …` when published or linked locally).
+
+## Quickstart
+
+```bash
+# 1. Install (once)
+pipx install docs-kit
+
+# 2. Ingest docs
+docs-kit ingest https://docs.example.com
+
+# 3. Install skill into your agent
+docs-kit install claude-code   # or: cursor, codex, opencode, claude-desktop
+
+# 4. Use the agent — it can run docs-kit query / list / ingest when relevant
+```
+
+No server to start. On first use, config and the default vector store path are created under **`~/.docs-kit/`** unless you use a project-local `docs-kit.yaml`.
+
+## How it works
+
+docs-kit installs a **skill** (Markdown + YAML frontmatter) into each tool’s skills directory. The skill tells the agent when to use docs-kit and which commands to run (`query`, `list`, `ingest`, `remove`, `inspect`, `doctor`, …). Agents execute **`docs-kit`** via their normal terminal integration.
+
+For more architecture detail (config resolution, layout, security posture), see [docs/project-overview.md](docs/project-overview.md).
+
+## Install targets
+
+| Command | Where the skill lands |
+|---------|------------------------|
+| `docs-kit install claude-code` | `~/.claude/skills/docs-kit/SKILL.md` |
+| `docs-kit install codex` | `~/.agents/skills/docs-kit/SKILL.md` |
+| `docs-kit install cursor` | `~/.cursor/skills/docs-kit/SKILL.md` + marked block in `~/.cursor/AGENTS.md` when needed |
+| `docs-kit install opencode` | `~/.config/opencode/skills/docs-kit/SKILL.md` (and may mirror under `~/.agents/skills/` if absent) |
+| `docs-kit install claude-desktop` | `~/.docs-kit/exports/claude-desktop/docs-kit.zip` — upload via Claude Desktop **Customize → Skills** |
+
+`codex-app` and `codex-desktop` are accepted aliases for the Codex install path.
+
+Use **`--project`** with `claude-code` for `.claude/skills/docs-kit/SKILL.md` in the current repo.
+
+## Commands
+
+### `docs-kit install <agent>`
+
+Install the docs-kit skill into a supported agent.
+
+```bash
+docs-kit install claude-code
+docs-kit install cursor
+docs-kit install codex
+docs-kit install opencode
+docs-kit install claude-desktop
+docs-kit install claude-code --project
+docs-kit install cursor --config ./docs-kit.yaml
+```
+
+If no config is found, **`~/.docs-kit/docs-kit.yaml`** is created automatically (non-project installs).
+
+### `docs-kit ingest <path-or-url>`
+
+Ingest a local file, directory, or documentation URL.
+
+```bash
+docs-kit ingest ./docs
+docs-kit ingest https://docs.example.com
+docs-kit ingest https://docs.example.com --provider gitbook
+docs-kit ingest ./docs --recreate
+```
+
+`--provider`: `auto` (default), `gitbook`, or `mintlify`.
+
+### `docs-kit query <text>`
+
+Run hybrid retrieval from the CLI.
+
+```bash
+docs-kit query "How do I authenticate?"
+docs-kit query "getting started" --limit 3
+docs-kit query "..." --config ./docs-kit.yaml
+```
+
+### `docs-kit list`
+
+List ingested sources with ingestion timestamps.
+
+```bash
+docs-kit list
+docs-kit list --config ./docs-kit.yaml
+```
+
+### `docs-kit fetch <url>`
+
+Download **GitBook** docs as Markdown files only (does not embed). For Mintlify or mixed hosting, use **`docs-kit ingest`** or copy files locally first.
+
+```bash
+docs-kit fetch https://docs.example.com
+docs-kit fetch https://docs.example.com --output ./downloaded-docs
+```
+
+### `docs-kit remove <source>`
+
+Remove an ingested source by URL or file path.
+
+```bash
+docs-kit remove https://docs.example.com/page
+docs-kit remove ./docs/getting-started.md
+```
+
+### `docs-kit inspect`
+
+Show collection stats and embedding settings.
+
+```bash
+docs-kit inspect
+docs-kit inspect --config ./docs-kit.yaml
+```
+
+### `docs-kit doctor`
+
+Check `docs-kit` on PATH, effective config, Qdrant path / connectivity, and which skills are installed.
+
+```bash
+docs-kit doctor
+docs-kit doctor --config ./docs-kit.yaml
+```
+
+### `docs-kit init`
+
+Create a project-local **`docs-kit.yaml`** (optional if you rely on `~/.docs-kit/docs-kit.yaml`).
+
+```bash
+docs-kit init
+docs-kit init --dir ./sandbox
+```
+
+## Configuration
+
+**Resolution order:** `--config` → `./docs-kit.yaml` in the current working directory → `~/.docs-kit/docs-kit.yaml` (created on first use when applicable).
+
+Example **project-local** `docs-kit.yaml` from `docs-kit init`:
+
+```yaml
+embedding:
+  provider: fastembed
+  model: BAAI/bge-small-en-v1.5
+
+vector_store:
+  provider: qdrant
+  local_path: .docs-kit/qdrant   # resolved relative to this file’s directory
+  collection_name: knowledge_base
+  retrieval_limit: 5
+  score_threshold: 0.35
+
+ingestion:
+  chunk_size: 800
+  chunk_overlap: 120
+  bm25_model: Qdrant/bm25
+```
+
+The auto-created **user** config under `~/.docs-kit/` sets `local_path` to an absolute directory under **`~/.docs-kit/qdrant`**. To use a **remote** Qdrant instance, set `vector_store.url` and leave local storage unused.
+
+## Supported sources
+
+| Source | Strategy |
+|--------|----------|
+| GitBook sites | `/llms-full.txt` → `/llms.txt` (GitBook fetcher); `auto` / `mintlify` use the broader pipeline below |
+| Mintlify & typical llms.txt sites | `/llms-full.txt` → `/llms.txt` → `/sitemap.xml` |
+| Local `.md` / `.txt` | Read from disk |
+
+## Requirements
+
+- **Python 3.11–3.13** (`requires-python` excludes 3.14+ while dependencies such as `onnxruntime` lack wheels)
+- Disk space for the embedding model (on the order of tens of MB for the default model)
+
+If your default `python` is 3.14:
+
+```bash
+pipx install docs-kit --python python3.13
+```
+
+## Migration from v0.1.x
+
+Older releases configured an **MCP server** in agent settings. That integration has been removed in favor of **skills + CLI**.
+
+1. Remove legacy **`mcpServers.docs-kit`** (or equivalent) from `~/.claude/settings.json`, Cursor MCP config, `~/.codex/config.toml`, etc.
+2. Run **`docs-kit install <agent>`** again to install skills.
+3. Existing **`~/.docs-kit/docs-kit.yaml`** and ingested data remain valid; any unused **`mcp:`** section in YAML can be deleted for clarity.

docs_kit-0.1.4/docs_kit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.4"

{docs_kit-0.1.3 → docs_kit-0.1.4}/docs_kit/cli/__main__.py

@@ -1,5 +1,5 @@
 import click
-from docs_kit.cli.commands import init_cmd, ingest_cmd, serve_cmd, stop_cmd, inspect_cmd, doctor_cmd, query_cmd, fetch_cmd, install_cmd, remove_cmd, list_cmd
+from docs_kit.cli.commands import init_cmd, ingest_cmd, inspect_cmd, doctor_cmd, query_cmd, fetch_cmd, install_cmd, remove_cmd, list_cmd
 from docs_kit.cli.help import DocsKitGroup, HELP_CONTEXT_SETTINGS, format_examples
 
 
@@ -9,19 +9,17 @@ from docs_kit.cli.help import DocsKitGroup, HELP_CONTEXT_SETTINGS, format_exampl
     epilog=format_examples(
         "docs-kit ingest https://docs.example.com",
         'docs-kit query "How do I authenticate?"',
-        "docs-kit serve",
+        "docs-kit install claude-code",
     ),
 )
 @click.version_option(package_name="docs-kit")
 def cli():
-    """Fetch docs, embed them locally, and expose retrieval over MCP."""
+    """Fetch docs, embed them locally, and expose them to AI agents via skills."""
     pass
 
 
 cli.add_command(init_cmd, "init")
 cli.add_command(ingest_cmd, "ingest")
-cli.add_command(serve_cmd, "serve")
-cli.add_command(stop_cmd, "stop")
 cli.add_command(inspect_cmd, "inspect")
 cli.add_command(doctor_cmd, "doctor")
 cli.add_command(query_cmd, "query")