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

{docs_kit-0.1.4 → docs_kit-0.1.5}/AGENTS.md

@@ -37,6 +37,16 @@ pytest tests/ -v
 
 ---
 
+## Skill templates (`docs_kit/templates/`)
+
+Skills installed by `docs-kit install` come from these Markdown templates.
+
+- **MUST** review `docs_kit/templates/` after **major** CLI or install-flow changes (new or removed commands, renamed options, changed defaults, new `INSTALL_TARGETS`, different recommended workflows).
+- **MUST** edit the relevant templates when skill text or examples would be wrong or misleading; **need not** update templates when the change does not affect what installed skills describe.
+- If you are unsure whether agents would see outdated instructions, check the templates and align them with `docs_kit/cli/commands.py` and install behavior.
+
+---
+
 ## Git Commit Workflow
 
 When the user asks to commit, stage, or write a commit message:

docs_kit-0.1.5/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.5] - 2026-03-28
+
+### Added
+
+- `docs-kit query --full` to print full chunk text; default preview truncation increased to 1500 characters (from 300).
+- Markdown chunking that keeps tables and fenced code blocks intact when possible: large tables split on row boundaries with header repeated; large code blocks split on lines with opening/closing fences preserved in each part.
+- Tests covering table/code chunking, list-heavy sections, and headers inside fences.
+
+### Changed
+
+- `docs-kit install codex` (and `codex-app` / `codex-desktop`) writes the skill to `~/.codex/skills/docs-kit/SKILL.md` and mirrors the same content to `~/.agents/skills/docs-kit/SKILL.md` for compatibility with shared agent layouts.
+- `docs-kit doctor` lists installed skills with install-target labels (`claude-code`, `cursor`, `codex`, `codex-shared`, `opencode`, `claude-desktop`) and suggests the matching `docs-kit install <target>` command when missing.
+
+### Fixed
+
+- Chunking no longer merges or normalizes markdown tables and code fences in ways that broke pipe layout or list structure.
+
+## [0.1.4] - 2026-03-28
+
+### Changed (breaking)
+
+- Removed the MCP server and MCP dependencies; agents use installed skill files that invoke the `docs-kit` CLI directly (`query`, `list`, `ingest`, `remove`, `inspect`, `doctor`, etc.).
+- CLI: added `list` and `remove`; removed `serve` and `stop`.
+- `docs-kit install` writes skills for Claude Code, Cursor, Codex, OpenCode, Claude Desktop, and related targets under `docs_kit/templates/`.
+- `doctor` checks PATH, config, Qdrant, and installed skill paths.
+- Local Qdrant access is serialized with `filelock` for concurrent CLI use.
+- Python support remains `>=3.11,<3.14`.
+
+## [0.1.3] - 2026-03-28
+
+### Added
+
+- `docs-kit serve` as a background daemon (PID + logs) and `docs-kit stop`.
+- Default MCP transport: SSE on `localhost:45139` to reduce Qdrant lock contention.
+- Install flows write URL entries pointing at `/sse` for Claude, Cursor, and Codex.
+- `doctor` checks MCP process and port reachability.
+
+### Changed
+
+- Project install without a local `docs-kit.yaml` uses in-memory defaults (no user bootstrap in that path).
+
+### Fixed
+
+- Serve daemon test log path mock (`MagicMock` parent breaking `mkdir`).
+
+## [0.1.2] - 2026-03-27
+
+### Added
+
+- Bootstrap `~/.docs-kit/docs-kit.yaml` and default Qdrant path when running a global `install` with no project config.
+- `DocsKitConfig.from_yaml` loading from the user config after `./docs-kit.yaml`.
+
+### Changed
+
+- Documented pipx-first install, config precedence, and Python 3.11–3.13 cap; `requires-python` set to `<3.14` (onnxruntime wheels).
+
+## [0.1.1] - 2026-03-27
+
+### Added
+
+- Mintlify fetcher (`llms-full.txt`, `llms.txt`, sitemap fallback) and shared `llms_txt` helpers.
+- `docs-kit ingest --provider auto|gitbook|mintlify`.
+- Formatted CLI help and banner (`DocsKitGroup` / `DocsKitCommand`, examples in epilogs).
+
+### Changed
+
+- GitBook fetcher refactor; HTML stripped before chunking via `html_utils`.
+- `install` resolves absolute `docs-kit` command and config paths; warns if YAML is missing.
+
+### Chore
+
+- Ignore local `docs/` and add release helper script to `.gitignore`.
+
+## [0.1.0] - 2026-03-27
+
+### Added
+
+- `DocsKitAgent` API: `ingest()`, `query()`.
+- CLI: `docs-kit init`, `fetch`, `ingest`, `serve`, `install`, `query`, `inspect`, `doctor`.
+- GitBook fetch via `/llms-full.txt` / `/llms.txt` and linked pages.
+- Local embeddings with FastEmbed (dense + sparse/BM25).
+- Vector store: Qdrant (local path or remote URL).
+- Document parsers for `.txt` and `.md`.
+- `DocsKitConfig` with YAML and environment variable support.
+- MCP server tools: `search_docs`, `list_sources`, `get_collection_info`, `get_full_document`.
+- Annotated `docs-kit.yaml` example, npx wrapper, sample data, CI and publish workflows.

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

@@ -69,6 +69,16 @@ After substantive changes, run the full test suite before claiming completion.
 
 ---
 
+## Skill templates (`docs_kit/templates/`)
+
+Installed agent skills are generated from these templates. They must stay aligned with the real CLI and install flow.
+
+- **MUST** open and review `docs_kit/templates/` after **major** changes to commands, flags, defaults, install targets, or agent integration (anything that changes what users or agents actually run).
+- **MUST** update the affected template files when those changes alter skill instructions; **need not** touch templates when the change is clearly unrelated (e.g. internal refactors with no CLI or install behavior change).
+- Stale templates mislead agents; treat template drift as a product bug on par with wrong CLI help text.
+
+---
+
 ## Git Commits
 
 - **MUST** write descriptive commit messages using [Conventional Commits](https://www.conventionalcommits.org/): `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `test`, `perf`.

{docs_kit-0.1.4 → docs_kit-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: docs-kit
-Version: 0.1.4
+Version: 0.1.5
 Summary: Fetch docs, embed locally, expose to AI agents via skills.
 License: MIT License
         
@@ -107,7 +107,7 @@ For more architecture detail (config resolution, layout, security posture), see
 | 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 codex` | `~/.codex/skills/docs-kit/SKILL.md` (also mirrors to `~/.agents/skills/docs-kit/SKILL.md` for compatibility) |
 | `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** |
@@ -154,9 +154,12 @@ Run hybrid retrieval from the CLI.
 ```bash
 docs-kit query "How do I authenticate?"
 docs-kit query "getting started" --limit 3
+docs-kit query "season 5 end date" --full
 docs-kit query "..." --config ./docs-kit.yaml
 ```
 
+Use `--full` when you want the entire chunk body instead of the default preview.
+
 ### `docs-kit list`
 
 List ingested sources with ingestion timestamps.
@@ -197,6 +200,8 @@ docs-kit inspect --config ./docs-kit.yaml
 
 Check `docs-kit` on PATH, effective config, Qdrant path / connectivity, and which skills are installed.
 
+For Codex installs, `doctor` reports both the native `~/.codex/skills/...` install and the shared compatibility mirror under `~/.agents/skills/...` when present.
+
 ```bash
 docs-kit doctor
 docs-kit doctor --config ./docs-kit.yaml

{docs_kit-0.1.4 → docs_kit-0.1.5}/README.md

@@ -68,7 +68,7 @@ For more architecture detail (config resolution, layout, security posture), see
 | 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 codex` | `~/.codex/skills/docs-kit/SKILL.md` (also mirrors to `~/.agents/skills/docs-kit/SKILL.md` for compatibility) |
 | `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** |
@@ -115,9 +115,12 @@ Run hybrid retrieval from the CLI.
 ```bash
 docs-kit query "How do I authenticate?"
 docs-kit query "getting started" --limit 3
+docs-kit query "season 5 end date" --full
 docs-kit query "..." --config ./docs-kit.yaml
 ```
 
+Use `--full` when you want the entire chunk body instead of the default preview.
+
 ### `docs-kit list`
 
 List ingested sources with ingestion timestamps.
@@ -158,6 +161,8 @@ docs-kit inspect --config ./docs-kit.yaml
 
 Check `docs-kit` on PATH, effective config, Qdrant path / connectivity, and which skills are installed.
 
+For Codex installs, `doctor` reports both the native `~/.codex/skills/...` install and the shared compatibility mirror under `~/.agents/skills/...` when present.
+
 ```bash
 docs-kit doctor
 docs-kit doctor --config ./docs-kit.yaml

docs_kit-0.1.5/docs_kit/_version.py

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

{docs_kit-0.1.4 → docs_kit-0.1.5}/docs_kit/cli/commands.py

@@ -48,6 +48,14 @@ def _get_user_config_path() -> Path:
     return _get_user_config_dir() / "docs-kit.yaml"
 
 
+def _get_codex_skill_path() -> Path:
+    return Path.home() / ".codex" / "skills" / "docs-kit" / "SKILL.md"
+
+
+def _get_shared_agent_skill_path() -> Path:
+    return Path.home() / ".agents" / "skills" / "docs-kit" / "SKILL.md"
+
+
 def _build_user_bootstrap_config():
     DocsKitConfig = _get_config_class()
     config = DocsKitConfig()
@@ -350,17 +358,18 @@ def doctor_cmd(config_path: str | None):
     # Skill install status
     click.echo("  Installed skills:")
     skill_locations = [
-        ("Claude Code", home / ".claude" / "skills" / "docs-kit" / "SKILL.md"),
-        ("Cursor", home / ".cursor" / "skills" / "docs-kit" / "SKILL.md"),
-        ("Codex", home / ".agents" / "skills" / "docs-kit" / "SKILL.md"),
-        ("OpenCode", home / ".config" / "opencode" / "skills" / "docs-kit" / "SKILL.md"),
-        ("Claude Desktop", _get_user_config_dir() / "exports" / "claude-desktop" / "docs-kit.zip"),
+        ("claude-code", "claude-code", home / ".claude" / "skills" / "docs-kit" / "SKILL.md"),
+        ("cursor", "cursor", home / ".cursor" / "skills" / "docs-kit" / "SKILL.md"),
+        ("codex", "codex", _get_codex_skill_path()),
+        ("codex-shared", "codex", _get_shared_agent_skill_path()),
+        ("opencode", "opencode", home / ".config" / "opencode" / "skills" / "docs-kit" / "SKILL.md"),
+        ("claude-desktop", "claude-desktop", _get_user_config_dir() / "exports" / "claude-desktop" / "docs-kit.zip"),
     ]
-    for label, path in skill_locations:
+    for label, install_target, path in skill_locations:
         if path.exists():
             click.echo(f"    [OK] {label}: {path}")
         else:
-            click.echo(f"    [--] {label}: not installed (run: docs-kit install {label.lower().replace(' ', '-')})")
+            click.echo(f"    [--] {label}: not installed (run: docs-kit install {install_target})")
 
 
 @click.command(
@@ -370,12 +379,14 @@ def doctor_cmd(config_path: str | None):
     epilog=format_examples(
         'docs-kit query "How do I authenticate?"',
         'docs-kit query "getting started" --limit 3',
+        'docs-kit query "season 5 end date" --full',
     ),
 )
 @click.argument("text")
 @click.option("--config", "config_path", default=None, help="Path to docs-kit.yaml.")
 @click.option("--limit", default=None, type=int, help="Maximum chunks to return.")
-def query_cmd(text: str, config_path: str | None, limit: int | None):
+@click.option("--full", is_flag=True, default=False, help="Show full chunk text without truncation.")
+def query_cmd(text: str, config_path: str | None, limit: int | None, full: bool):
     """Run a retrieval query against the vector store (no server required)."""
     config = _load_config(config_path)
     agent = _get_agent_class()(config=config)
@@ -386,9 +397,12 @@ def query_cmd(text: str, config_path: str | None, limit: int | None):
         sys.exit(1)
 
     for i, chunk in enumerate(chunks, start=1):
-        preview = chunk.text[:300] + "..." if len(chunk.text) > 300 else chunk.text
+        if full:
+            body = chunk.text
+        else:
+            body = chunk.text[:1500] + "..." if len(chunk.text) > 1500 else chunk.text
         click.echo(f"[{i}] score={chunk.score:.2f}  source={chunk.source}")
-        click.echo(preview)
+        click.echo(body)
         click.echo("---")
 
 
@@ -506,10 +520,13 @@ def install_cmd(agent: str, project: bool, config_path: str | None):
         return
 
     if normalized in {"codex", "codex-app", "codex-desktop"}:
-        dest = home / ".agents" / "skills" / "docs-kit" / "SKILL.md"
+        dest = _get_codex_skill_path()
+        shared_dest = _get_shared_agent_skill_path()
         content = _build_skill_content("skill.md", effective_config_path)
         _install_skill_file(content, dest)
+        _install_skill_file(content, shared_dest)
         click.echo(f"Installed docs-kit skill at {dest}")
+        click.echo(f"  Also installed shared compatibility skill at {shared_dest}")
         if created_user_config:
             click.echo(f"  Created user config at {_get_user_config_path()}")
         elif effective_config_path is not None:
@@ -544,7 +561,7 @@ def install_cmd(agent: str, project: bool, config_path: str | None):
         click.echo(f"Installed docs-kit skill at {dest}")
 
         # Also write to shared ~/.agents/skills/ path if not already installed by codex
-        shared_dest = home / ".agents" / "skills" / "docs-kit" / "SKILL.md"
+        shared_dest = _get_shared_agent_skill_path()
         if not shared_dest.exists():
             _install_skill_file(content, shared_dest)
             click.echo(f"  Also installed at shared path {shared_dest}")

{docs_kit-0.1.4 → docs_kit-0.1.5}/docs_kit/core/chunking.py

@@ -32,6 +32,7 @@ def chunk_text(text: str, chunk_size: int = 800, chunk_overlap: int = 120) -> li
 
 _HEADER_RE = re.compile(r"^(#{1,6})\s+(.*)", re.MULTILINE)
 _FENCE_OPEN_RE = re.compile(r"^ {0,3}(`{3,}|~{3,})")
+_TABLE_LINE_RE = re.compile(r"^\s*\|")
 
 
 def _fence_ranges(text: str) -> list[tuple[int, int]]:
@@ -192,6 +193,159 @@ def _chunk_prose_section(body: str, prefix: str, chunk_size: int, chunk_overlap:
     return [f"{prefix}{w}" for w in windows]
 
 
+# ---------------------------------------------------------------------------
+# Table and code block preservation
+# ---------------------------------------------------------------------------
+
+def _split_tables_and_code(body: str) -> list[tuple[str, str]]:
+    """Split a section body into typed segments: ('prose'|'table'|'code', text).
+
+    Table blocks: contiguous runs of pipe-prefixed lines (markdown table rows).
+    Code blocks: fenced code blocks (``` or ~~~).
+    Everything else: prose.
+
+    Original newlines are preserved within table and code segments.
+    """
+    lines = body.splitlines(keepends=True)
+    blocks: list[tuple[str, str]] = []
+    current_type: str = "prose"
+    current_lines: list[str] = []
+    fence_char: str | None = None
+    fence_len: int = 0
+
+    def _flush():
+        nonlocal current_lines
+        if current_lines:
+            text = "".join(current_lines)
+            if text.strip():
+                blocks.append((current_type, text))
+            current_lines = []
+
+    for line in lines:
+        fence_match = _FENCE_OPEN_RE.match(line)
+        is_table_line = bool(_TABLE_LINE_RE.match(line))
+
+        if fence_char is not None:
+            # Inside a fenced code block — accumulate until closing fence
+            current_lines.append(line)
+            if fence_match and fence_match.group(1)[0] == fence_char and len(fence_match.group(1)) >= fence_len:
+                fence_char = None
+            continue
+
+        if fence_match and current_type != "table":
+            # Opening fence — flush current block, start code block
+            _flush()
+            current_type = "code"
+            current_lines.append(line)
+            fence_char = fence_match.group(1)[0]
+            fence_len = len(fence_match.group(1))
+            continue
+
+        if is_table_line:
+            if current_type != "table":
+                _flush()
+                current_type = "table"
+            current_lines.append(line)
+        else:
+            if current_type in ("table", "code"):
+                _flush()
+                current_type = "prose"
+            current_lines.append(line)
+
+    _flush()
+    return blocks
+
+
+def _chunk_table_block(table_text: str, prefix: str, chunk_size: int) -> list[str]:
+    """Chunk a markdown table, keeping it atomic when possible.
+
+    If the table exceeds chunk_size, split at row boundaries. The header row
+    and separator row are repeated at the top of every split chunk.
+    """
+    full = f"{prefix}{table_text.strip()}"
+    if len(full) <= chunk_size:
+        return [full]
+
+    rows = [r for r in table_text.splitlines() if r.strip()]
+    if len(rows) < 3:
+        # No data rows to split — keep as-is even if oversized
+        return [full]
+
+    header_row = rows[0]
+    separator_row = rows[1]
+    data_rows = rows[2:]
+
+    header_block = f"{header_row}\n{separator_row}\n"
+    chunks: list[str] = []
+    group_rows: list[str] = []
+    group_len = len(prefix) + len(header_block)
+
+    for row in data_rows:
+        row_len = len(row) + 1  # +1 for newline
+        if group_rows and group_len + row_len > chunk_size:
+            chunk_text_val = prefix + header_block + "\n".join(group_rows)
+            chunks.append(chunk_text_val)
+            group_rows = [row]
+            group_len = len(prefix) + len(header_block) + row_len
+        else:
+            group_rows.append(row)
+            group_len += row_len
+
+    if group_rows:
+        chunks.append(prefix + header_block + "\n".join(group_rows))
+
+    return chunks if chunks else [full]
+
+
+def _chunk_code_block(code_text: str, prefix: str, chunk_size: int) -> list[str]:
+    """Chunk a fenced code block, keeping it atomic when possible.
+
+    If the block exceeds chunk_size, split at line boundaries preserving
+    the opening fence line at the top of each split chunk.
+    """
+    full = f"{prefix}{code_text.strip()}"
+    if len(full) <= chunk_size:
+        return [full]
+
+    lines = code_text.splitlines()
+    if not lines:
+        return []
+
+    opening_fence = lines[0]
+    closing_fence = None
+    content_lines = lines[1:]
+    if len(lines) > 1:
+        fence_match = _FENCE_OPEN_RE.match(lines[-1])
+        if fence_match:
+            closing_fence = lines[-1]
+            content_lines = lines[1:-1]
+
+    # Keep each emitted chunk as valid fenced markdown.
+    closing_fence = closing_fence or opening_fence
+    wrapper_len = len(prefix) + len(opening_fence) + 1 + len(closing_fence)
+
+    chunks: list[str] = []
+    current: list[str] = []
+    current_len = wrapper_len
+
+    for line in content_lines:
+        line_len = len(line) + 1
+        if current and current_len + line_len > chunk_size:
+            chunks.append(prefix + "\n".join([opening_fence, *current, closing_fence]))
+            current = [line]
+            current_len = wrapper_len + line_len
+        else:
+            current.append(line)
+            current_len += line_len
+
+    if current:
+        chunks.append(prefix + "\n".join([opening_fence, *current, closing_fence]))
+    elif not chunks:
+        chunks.append(prefix + "\n".join([opening_fence, closing_fence]))
+
+    return chunks if chunks else [full]
+
+
 def _merge_small_chunks(chunks: list[str], chunk_size: int) -> list[str]:
     """Merge adjacent chunks that are both smaller than chunk_size/2."""
     if not chunks:
@@ -208,7 +362,12 @@ def _merge_small_chunks(chunks: list[str], chunk_size: int) -> list[str]:
 
 
 def chunk_markdown(text: str, chunk_size: int = 800, chunk_overlap: int = 120) -> list[str]:
-    """Chunk markdown text with structure-awareness."""
+    """Chunk markdown text with structure-awareness.
+
+    Tables and fenced code blocks are preserved with their original newlines.
+    Prose is whitespace-normalized and split with a sliding window.
+    List-heavy sections use bullet-item grouping.
+    """
     if not text.strip():
         return []
     if chunk_overlap >= chunk_size:
@@ -222,6 +381,12 @@ def chunk_markdown(text: str, chunk_size: int = 800, chunk_overlap: int = 120) -
         if _is_list_heavy(body):
             raw_chunks.extend(_chunk_list_section(body, prefix, chunk_size))
         else:
-            raw_chunks.extend(_chunk_prose_section(body, prefix, chunk_size, chunk_overlap))
+            for block_type, block_text in _split_tables_and_code(body):
+                if block_type == "table":
+                    raw_chunks.extend(_chunk_table_block(block_text, prefix, chunk_size))
+                elif block_type == "code":
+                    raw_chunks.extend(_chunk_code_block(block_text, prefix, chunk_size))
+                else:
+                    raw_chunks.extend(_chunk_prose_section(block_text, prefix, chunk_size, chunk_overlap))
 
     return _merge_small_chunks([c for c in raw_chunks if c.strip()], chunk_size)

{docs_kit-0.1.4 → docs_kit-0.1.5}/docs_kit/templates/claude_code_skill.md

@@ -1,6 +1,6 @@
 ---
 name: docs-kit
-description: Search and manage documentation knowledge bases using docs-kit CLI. Use when the user asks about third-party library docs, API references, or wants to ingest/manage documentation sources.
+description: Search and manage documentation knowledge bases using docs-kit CLI. Use when the user asks about third-party library docs, API references, vendor documentation, version-specific API behavior, GitBook or Mintlify public docs, offline or local doc search, or wants to ingest a doc URL before answering a question.
 allowed-tools:
   - Bash(docs-kit *)
   - Bash({{DOCS_KIT_CMD}} *)
@@ -25,7 +25,7 @@ Use docs-kit when the user:
 
 1. Run `{{DOCS_KIT_CMD}} list` to check what documentation is already available.
 2. If relevant docs are present, run `{{DOCS_KIT_CMD}} query "your question"` to find relevant chunks.
-3. If docs are not yet ingested, suggest: `{{DOCS_KIT_CMD}} ingest <url-or-path>`
+3. If docs are not yet ingested, run `{{DOCS_KIT_CMD}} ingest <url-or-path>` (confirm with user if the source is unfamiliar).
 4. Use retrieved chunks to inform your answer, citing sources.
 
 ## Commands
@@ -34,7 +34,9 @@ Use docs-kit when the user:
 ```bash
 {{DOCS_KIT_CMD}} query "your search query"
 {{DOCS_KIT_CMD}} query "how to authenticate" --limit 10
+{{DOCS_KIT_CMD}} query "how to authenticate" --limit 10 --full
 ```
+Use `--full` to return untruncated passage text.
 Returns relevant chunks with source attribution and relevance scores.
 
 ### List ingested sources
@@ -70,6 +72,12 @@ Returns relevant chunks with source attribution and relevance scores.
 {{DOCS_KIT_CMD}} inspect
 ```
 
+### Initialize project config
+```bash
+{{DOCS_KIT_CMD}} init
+```
+Creates a project-local `docs-kit.yaml` config file.
+
 ### Diagnose issues
 ```bash
 {{DOCS_KIT_CMD}} doctor

docs_kit-0.1.5/docs_kit/templates/claude_desktop_skill.md

@@ -0,0 +1,36 @@
+---
+name: docs-kit
+description: Search and manage documentation knowledge bases using docs-kit CLI. Use when the user asks about third-party library docs, API references, vendor documentation, version-specific API behavior, GitBook or Mintlify public docs, offline or local doc search, or wants to ingest a doc URL before answering a question.
+---
+
+# docs-kit — Documentation Knowledge Base
+
+docs-kit is a globally installed CLI tool that fetches, embeds, and searches documentation locally.
+All configuration and data are stored under `~/.docs-kit/` — no extra setup required.
+
+Executable: `{{DOCS_KIT_CMD}}`
+
+## When to use
+
+Use docs-kit when the user:
+- Asks a question about a library, framework, or API whose docs may be ingested
+- Wants to search documentation for code examples, API references, or guides
+- Wants to ingest new documentation from a URL or local files
+- Wants to manage (list, remove, inspect) ingested documentation sources
+
+## Workflow
+
+1. Run `{{DOCS_KIT_CMD}} list` to check what documentation is available.
+2. Run `{{DOCS_KIT_CMD}} query "your question"` to search ingested docs.
+3. If docs are not yet ingested, propose: `{{DOCS_KIT_CMD}} ingest <url-or-path>`
+
+## Commands
+
+- `{{DOCS_KIT_CMD}} query "search terms" --limit 10` — search documentation (add `--full` for untruncated text)
+- `{{DOCS_KIT_CMD}} list` — list all ingested sources
+- `{{DOCS_KIT_CMD}} ingest <url-or-path>` — ingest new docs (add `--recreate` to re-ingest)
+- `{{DOCS_KIT_CMD}} fetch <url> --output <dir>` — download docs to local files
+- `{{DOCS_KIT_CMD}} remove <source>` — remove a source
+- `{{DOCS_KIT_CMD}} inspect` — collection stats
+- `{{DOCS_KIT_CMD}} init` — create project-local config
+- `{{DOCS_KIT_CMD}} doctor` — diagnose issues

docs_kit-0.1.5/docs_kit/templates/cursor_agents_md.md

@@ -0,0 +1,33 @@
+> Prefer `~/.cursor/skills/docs-kit/SKILL.md` when present; this block is a fallback.
+
+# docs-kit — Documentation Knowledge Base
+
+docs-kit is a globally installed CLI tool for searching and managing local documentation embeddings.
+All configuration and data are stored under `~/.docs-kit/` — no extra setup required.
+
+Executable: `{{DOCS_KIT_CMD}}`
+
+## When to use
+
+Use docs-kit when the user:
+- Asks a question about a library, framework, or API whose docs may be ingested
+- Wants to search documentation for code examples, API references, or guides
+- Wants to ingest new documentation from a URL or local files
+- Wants to manage (list, remove, inspect) ingested documentation sources
+
+## Workflow
+
+1. Run `{{DOCS_KIT_CMD}} list` to check what documentation is available.
+2. Run `{{DOCS_KIT_CMD}} query "your question"` to search.
+3. If docs are not yet ingested, run `{{DOCS_KIT_CMD}} ingest <url-or-path>` (confirm with user if the source is unfamiliar).
+
+## Commands
+
+- `{{DOCS_KIT_CMD}} query "search terms" --limit 10` — search ingested documentation (add `--full` for untruncated text)
+- `{{DOCS_KIT_CMD}} list` — list all ingested sources with dates
+- `{{DOCS_KIT_CMD}} ingest <url-or-path>` — ingest docs from a URL or local path (add `--recreate` to re-ingest)
+- `{{DOCS_KIT_CMD}} fetch <url> --output <dir>` — download docs to local Markdown files
+- `{{DOCS_KIT_CMD}} remove <source>` — remove a previously ingested source
+- `{{DOCS_KIT_CMD}} inspect` — show collection stats
+- `{{DOCS_KIT_CMD}} init` — create project-local config
+- `{{DOCS_KIT_CMD}} doctor` — diagnose issues

{docs_kit-0.1.4 → docs_kit-0.1.5}/docs_kit/templates/skill.md

@@ -1,6 +1,6 @@
 ---
 name: docs-kit
-description: Search and manage documentation knowledge bases using docs-kit CLI. Use when the user asks about third-party library docs, API references, or wants to ingest/manage documentation sources.
+description: Search and manage documentation knowledge bases using docs-kit CLI. Use when the user asks about third-party library docs, API references, vendor documentation, version-specific API behavior, GitBook or Mintlify public docs, offline or local doc search, or wants to ingest a doc URL before answering a question.
 ---
 
 # docs-kit — Documentation Knowledge Base
@@ -22,7 +22,7 @@ Use docs-kit when the user:
 
 1. Run `{{DOCS_KIT_CMD}} list` to check what documentation is already available.
 2. If relevant docs are present, run `{{DOCS_KIT_CMD}} query "your question"` to find relevant chunks.
-3. If docs are not yet ingested, suggest: `{{DOCS_KIT_CMD}} ingest <url-or-path>`
+3. If docs are not yet ingested, run `{{DOCS_KIT_CMD}} ingest <url-or-path>` (confirm with user if the source is unfamiliar).
 4. Use retrieved chunks to inform your answer, citing sources.
 
 ## Commands
@@ -31,7 +31,9 @@ Use docs-kit when the user:
 ```bash
 {{DOCS_KIT_CMD}} query "your search query"
 {{DOCS_KIT_CMD}} query "how to authenticate" --limit 10
+{{DOCS_KIT_CMD}} query "how to authenticate" --limit 10 --full
 ```
+Use `--full` to return untruncated passage text.
 
 ### List ingested sources
 ```bash
@@ -60,6 +62,12 @@ Use docs-kit when the user:
 {{DOCS_KIT_CMD}} inspect
 ```
 
+### Initialize project config
+```bash
+{{DOCS_KIT_CMD}} init
+```
+Creates a project-local `docs-kit.yaml` config file.
+
 ### Diagnose issues
 ```bash
 {{DOCS_KIT_CMD}} doctor