Metadata-Version: 2.4
Name: skelpr
Version: 0.1.1
Summary: Agent-agnostic code-intelligence and safe-validation backend with hybrid retrieval, file:line citations, and MCP agent integration.
Author: Skelpr contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/skelpr-thrive360/skelpr
Project-URL: Repository, https://github.com/skelpr-thrive360/skelpr
Project-URL: Issues, https://github.com/skelpr-thrive360/skelpr/issues
Keywords: mcp,model-context-protocol,agents,ai-agents,claude,cursor,code-intelligence,code-review,rag,hybrid-search,embeddings,retrieval,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Environment :: Console
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Requires-Dist: pydantic>=2.6
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.27
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Provides-Extra: vector
Requires-Dist: qdrant-client>=1.9; extra == "vector"
Provides-Extra: ast
Requires-Dist: tree-sitter>=0.21; extra == "ast"
Requires-Dist: tree-sitter-languages>=1.10; extra == "ast"
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn[standard]>=0.29; extra == "server"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: skelpr[server]; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: markdown>=3.6; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: pylint>=3.2; extra == "dev"
Provides-Extra: all
Requires-Dist: skelpr[postgres]; extra == "all"
Requires-Dist: skelpr[vector]; extra == "all"
Requires-Dist: skelpr[ast]; extra == "all"
Requires-Dist: skelpr[server]; extra == "all"
Requires-Dist: skelpr[mcp]; extra == "all"
Dynamic: license-file

# Skelpr

[![CI](https://github.com/skelpr-thrive360/skelpr/actions/workflows/ci.yml/badge.svg)](https://github.com/skelpr-thrive360/skelpr/actions/workflows/ci.yml)
[![Security](https://github.com/skelpr-thrive360/skelpr/actions/workflows/security.yml/badge.svg)](https://github.com/skelpr-thrive360/skelpr/actions/workflows/security.yml)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](#requirements)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/skelpr-thrive360/skelpr/blob/main/LICENSE)
[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](https://github.com/skelpr-thrive360/skelpr/blob/main/CONTRIBUTING.md)

**Surgical code retrieval for AI agents, PR reviews, and fixes — in a real agent A/B: 52% fewer tokens, 43% faster answers, and +16 accuracy points.**

Every AI coding tool dumps whole files into the LLM context window: slow, expensive, and hallucination-prone. Skelpr is the surgical librarian — AST-aware parsing and hybrid search (lexical + vector + symbol graph) extract only the exact snippets an LLM needs to answer, review, patch, and validate, each carrying a precise `file:line` citation.

<details>
<summary><b>Table of contents</b></summary>

- [⚡ Measured impact](#measured-impact)
- [👀 See it in action](#see-it-in-action)
- [Quick start](#quick-start)
- [Why Skelpr?](#why-skelpr)
- [Who it's for](#who-its-for)
- [Two integration modes](#two-integration-modes)
- [How it compares](#how-it-compares)
- [MCP integration](#mcp-integration)
- [Install](#install)
- [Requirements](#requirements)
- [Local models](#local-models)
- [CLI commands](#cli-commands)
- [FAQ](#faq)
- [Roadmap](#roadmap)
- [Development](#development)
- [Docs](#docs)
- [Contributing](#contributing)
- [License](#license)

</details>

---

## ⚡ Measured impact

**Agent mode · MCP A/B:** **-52%** agent tokens · **-43%** wall-clock · **+16** accuracy points vs. native tools only

Self-reported benchmarks — full methodology in [docs/BENCHMARK.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/BENCHMARK.md).

### Agent mode · A/B: what happens to a real coding agent (MCP integration)

7 tasks x 2 arms (Antigravity · Gemini 3.6 Flash Medium + Skelpr MCP vs. native tools only) on the Sock Shop microservices demo:

- 🧠 **Tokens: -52%** (766k → 367k) — cache-read tokens, the biggest quota consumer, drop **-64%**
- ⚡ **Wall-clock: -43%** (580s → 332s) — one `skelpr_search` (avg 0.63s) replaces ~5 native file reads
- 🎯 **Accuracy: +16 points** (619 → 635) — including a **+40** jump on the negative task (60 → 100), where search *proves absence* with a cited no-results answer

> ⚠️ The +16 accuracy swing is driven by the negative task's evaluator phrase match (60 → 100 — both answers are equally correct); on the other six tasks the WITH arm totals 535 vs 559. Token and time savings are unaffected. Per-task breakdown: [docs/BENCHMARK.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/BENCHMARK.md).

> 📊 Suite totals, per-task tables, verbatim agent outputs, and the "run it yourself" guide: **[docs/BENCHMARK.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/BENCHMARK.md)** · 🔎 WITH vs WITHOUT, every answer side by side: **[docs/comparisons/COMP_ANTIGRAVITY.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/comparisons/COMP_ANTIGRAVITY.md)**

### CLI mode · Standalone: agentic multi-turn vs. the hybrid engine

| Pipeline Strategy | Avg. Latency | Avg. Prompt Tokens | Avg. Cost / Query | Accuracy (0-10) | vs. Agentic Multi-Turn |
|---|---|---|---|---|---|
| Agentic Multi-Turn | 19.62s | 7,491 | $0.00076 | 8.7 / 10 | reference |
| **Skelpr Hybrid Engine** | **5.61s** (−71%) | **2,474** (−67%) | **$0.00021** (−72%) | **9.0 / 10** | **67% fewer tokens · 3.5x faster · +0.3 accuracy** |

> Same questions, same model (`gemini-2.5-flash`); per-task detail in [docs/BENCHMARK.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/BENCHMARK.md). Instead of multi-turn browsing, the hybrid engine retrieves pre-ranked, cited chunks in one pass — same grounded accuracy, a fraction of the round-trips.

## 👀 See it in action

Real output from the A/B harness (Sock Shop repo, 2026-09-09/10). The agent asks *"does a 'recommendations' service exist?"* — three searches, ~0.7s total, and it answers with a cited **no**:

```text
$ skelpr_search "recommendation recommendations inventory service" --top-k 10

## Skelpr Search Results — 10 chunks

[GRAPH]    .skelpr/graphify/summary.txt:1-2                          architecture graph summary
[LEXICAL]  deploy/kubernetes/autoscaling/grafana-service.yaml:1-23   matched 1/4 terms, filename matches 'service'
[LEXICAL]  deploy/kubernetes/autoscaling/heapster-service.yaml:1-17  matched 1/4 terms, filename matches 'service'
[LEXICAL]  deploy/kubernetes/manifests/02-carts-svc.yml:1-5          ...

$ skelpr_search "recommendationservice inventoryservice recommendation inventory" --top-k 10

## Skelpr Search Results — 1 chunk

[GRAPH]    .skelpr/graphify/summary.txt:1-2                          architecture graph summary
```

Zero code defines a recommendations service — so the agent answers **100/100** on the negative task (it scored 60/100 without Skelpr). Full verbatim exchange: [docs/BENCHMARK.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/BENCHMARK.md).

## Quick start

Two things have to be running before the first run, and Skelpr cannot start either of
them for you:

1. **Docker Desktop, started and finished booting.** `skelpr setup` talks to the daemon
   (`docker info`) to start Postgres and Qdrant and to build the sandbox image. If Docker
   Desktop is installed but not running, setup stops after step 1 and says so.
2. **An embedding model server** — LM Studio serving
   `text-embedding-nomic-embed-text-v1.5` (GGUF, `Q8_0`, ~146 MB) on
   `http://127.0.0.1:1234/v1`. Without it, indexing still runs but vector recall
   degrades to a local hashing fallback. Steps: [Local models](#local-models).

```bash
cd <your-repo>

# 1. Start Docker services (Postgres + Qdrant + sandbox) — Docker Desktop must be up
skelpr setup

# 2. Configure LLM provider
skelpr init --gemini YOUR_KEY    # Google Gemini
skelpr init --openai sk-proj-..  # OpenAI
skelpr init --anthropic sk-ant-.. # Anthropic
skelpr init --openrouter YOUR_KEY # OpenRouter
skelpr init --groq gsk_...       # Groq
skelpr init --local              # Local model server

# 3. Index repository (AST chunking + hybrid indexing)
skelpr index

# 4. Query, review, or fix
skelpr ask "how does authentication token refresh work?"
skelpr review --diff origin/main...HEAD
skelpr fix --issue "ValueError in user_service.py on line 42" --apply
skelpr validate                   # Run sandboxed tests/lints
skelpr serve                      # Optional FastAPI server on :8080
```

## Why Skelpr?

- **Precision Over Volume** — AST-aware chunking isolates exact functions, classes, and scopes, significantly reducing the *lost-in-the-middle* hallucination problem common with large context dumps.
- **Minimal Token Payloads** — Plug in premium cloud models (OpenAI, Anthropic) for massive enterprise repositories without runaway token costs, or run ultra-fast local models (Qwen, Gemma via LM Studio/vLLM) without hitting context limits.
- **Grounded & Verifiable** — Every output includes precise `file:line` citations. Edits are verified via sandboxed validation before applying.
- **Enterprise-oriented** — Multi-tenant architecture with row-level security, state consistency tracking, and AST-based patching for reliable code modifications.

## Who it's for

- **Agent power-users** — give Claude Code, Cursor, Windsurf, or any MCP-compatible agent surgical, cited code access with one command.
- **Teams on paid models** — keep premium cloud LLMs for enterprise repos without runaway token bills, at the same or better accuracy.
- **Local-first developers** — run Qwen/Gemma entirely offline via LM Studio, vLLM, or Ollama: no API keys, no context-limit ceilings, no code leaving your machine.

## Two integration modes

Most users start with **Agent (MCP)** — drop Skelpr behind the coding agent you already use, no LLM key needed. Pick **Standalone** when you want Skelpr to drive the LLM itself.

| | Agent (MCP) | Standalone Package |
|---|---|---|
| **What you get** | Surgical codebase access for your existing agent | Full ask/review/fix/validate pipeline |
| **LLM needed** | No (agent's LLM) | Yes (your endpoint) |
| **Commands** | Agent calls MCP tools | `skelpr ask/fix/review/validate` |
| **Retrieval** | Skelpr (same engine) | Skelpr (same engine) |
| **Reasoning** | Agent's own LLM | Your LLM via Skelpr |
| **Best for** | Enhancing Claude Code, Cursor, Windsurf, etc. | Self-contained coding assistant |

**Agent (MCP)** — Skelpr runs as a code-intelligence backend via the MCP protocol; the agent's LLM handles reasoning, so **no LLM key is needed on the Skelpr side** (local embeddings via LM Studio make it fully keyless).

**Standalone** — Skelpr handles everything end to end: retrieval, context building, LLM calls, patching, and validation. Requires an LLM API key or local model server.

> 🧩 Mode diagrams, the shared retrieval engine, and the fallback hierarchy: **[docs/ARCHITECTURE.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/ARCHITECTURE.md)**

## How it compares

| Instead of … | With Skelpr |
|---|---|
| Letting agents browse/read every file | -52% agent tokens, -43% wall-clock, +16 accuracy in agent A/B |
| grep + clicking through files | One hybrid search returns the exact files, pre-ranked, with `path:line` citations |
| Embedding-only RAG | Deterministic-first fusion (lexical > symbol > graph > vector) — exact matches win, absence is *provable*, and paths are never hallucinated |

## MCP integration

The generic Skelpr MCP server exposes code intelligence to any MCP-compatible agent (Claude Code, Cursor, Windsurf, and more).

```bash
pip install ".[mcp]"
cd <your-repo>
skelpr setup          # one-time: verify deps (model endpoint, storage) + build sandbox image
skelpr init && skelpr index
skelpr install-mcp    # auto-detect agents, preflight check, write config
```

`install-mcp` auto-detects installed agents, warns before overwriting existing entries (`--force` to skip), and supports `--project-level` for repo-local config. Register custom agents with `skelpr register-agent "<name>" <id> --cli <cmd> --global-config <path>`.

**Available MCP tools:**

- `skelpr_search` — Hybrid code search (lexical + symbol + graph + vector); default top-5 chunks with 600-char snippets to keep agent context compact
- `skelpr_get_context` — Token-budgeted context for agent context windows (default 4000-token budget, top-8 chunks, full chunk text)
- `skelpr_find_symbol` / `skelpr_dependencies` — Symbol definition and location lookup; structural relationships and dependencies
- `skelpr_validate` — Run validation commands in isolated sandbox
- `skelpr_apply_ast_patch` — Optional AST-precise structural patching
- `skelpr_health` — System health and backend status

> 📚 Manual registration, project-level config, and troubleshooting: **[docs/MCP_SETUP.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/MCP_SETUP.md)**

## Install

```bash
pip install skelpr                        # from PyPI (recommended)
pip install "skelpr[postgres,vector,ast,server]"   # production backends
pip install "skelpr[mcp]"                 # MCP server support
pip install "skelpr[all]"                 # everything

# From source (contributors):
git clone https://github.com/skelpr-thrive360/skelpr.git skelpr && cd skelpr
pip install -e ".[all]"                    # editable dev install
pip install -e ".[dev]"                    # + pytest/ruff/mypy
```

> Prefer the bleeding edge? Install from source with the `git clone` above. (If the
> repository is not yet public, use `pip install skelpr` or ask a maintainer for
> access.)

## Requirements

| Requirement | Needed for | Notes |
|---|---|---|
| Python ≥ 3.10 | everything | |
| `git` on PATH | diff / review / patch | degrades without it for index / ask |
| `ripgrep` | fast lexical search | recommended; pure-Python fallback otherwise |
| **Docker Desktop, running** | `skelpr setup`, sandboxed `validate` | Setup checks the daemon with `docker info` first. Start Docker Desktop before you run it — that one command starts Postgres 16 (port 5434) and Qdrant (6333/6334) and builds the `skelpr-runner:latest` sandbox image. Without Docker the core still runs end to end on in-memory fallbacks. |
| **An embeddings server** | `skelpr index` + vector retrieval, in both modes | LM Studio serving `text-embedding-nomic-embed-text-v1.5` (GGUF `Q8_0`, ~146 MB) at `http://127.0.0.1:1234/v1` is the default. Any OpenAI-compatible `/v1/embeddings` you host works. |
| A generation model server | `ask` / `fix` / `review` / `chat` (CLI mode) | LM Studio serving `qwen2.5-14b-instruct`, or a cloud provider key. Not needed in MCP mode — the agent brings its own model. |

## Local models

Skelpr speaks to any OpenAI-compatible server, and expects **two different models for two
different jobs**:

| Job | Model | Used by |
|---|---|---|
| Embeddings | `text-embedding-nomic-embed-text-v1.5` — GGUF, `Q8_0` | `skelpr index` and vector retrieval — needed in **both** modes |
| Generation | `qwen2.5-14b-instruct` | `ask` / `fix` / `review` / `chat` — CLI mode only |

### 1. The embedding model (required)

Non-vector retrieval works without it, and vector search degrades to a deterministic
hashing embedder instead of failing — so a missing embedding server shows up as *quietly
worse recall*, not as an error. Start it before you index.

**LM Studio** (what the default config points at):

1. Install LM Studio from <https://lmstudio.ai>.
2. In the model catalog, search `nomic-embed-text-v1.5` (publisher `nomic-ai`) and
   download the **`Q8_0` GGUF** build — the exact one the default targets:

   | Field | Value |
   |---|---|
   | Model | `nomic-ai/nomic-embed-text-v1.5` |
   | Format | `GGUF` |
   | Quantization | `Q8_0` |
   | Architecture | `nomic-bert` |
   | Domain | `embedding` |
   | Size on disk | ~146 MB |

3. Load the model, then start the local server (**default port 1234**) and confirm it
   answers:

   ```bash
   curl -s http://127.0.0.1:1234/v1/embeddings \
     -H 'Content-Type: application/json' \
     -d '{"input":["hello"],"model":"text-embedding-nomic-embed-text-v1.5@q8_0"}'
   ```

4. Keep the identifier in `.skelpr.yaml` matching what the server advertises. LM Studio
   puts the quantization in the model name, which is where the `@q8_0` suffix comes from:

   ```yaml
   embeddings:
     endpoint: http://127.0.0.1:1234/v1
     model: text-embedding-nomic-embed-text-v1.5@q8_0
   ```

Loading the model on another machine, a GPU box, or a vLLM/Ollama server you run
elsewhere is supported — point `embeddings.endpoint` at it. `skelpr index` tells you
which side you landed on:

```text
INFO  Embedding server online at http://127.0.0.1:1234/v1/embeddings (dim=768)
WARNING  No local embedding server reachable at http://127.0.0.1:1234/v1; using hashing fallback
```

### 2. The generation model (CLI mode)

```bash
# LM Studio — load qwen2.5-14b-instruct and start the server on port 1234
# vLLM
vllm serve qwen2.5-14b-instruct --dtype auto --max-model-len 32768
# Ollama
ollama serve && ollama pull qwen2.5:14b
```

> ⚙️ Full LM Studio setup steps and the complete `.skelpr.yaml` reference: **[docs/CONFIGURATION.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/CONFIGURATION.md)**

## CLI commands

**Core**

- `skelpr setup` — Start Docker services (Postgres + Qdrant) and build the sandbox image
- `skelpr init` — Create `.skelpr.yaml` configuration
- `skelpr index` — Build/refresh hybrid knowledge base
- `skelpr ask` — Ask grounded questions about the repo
- `skelpr chat` — Interactive loop for ask/fix (no shell quoting needed)
- `skelpr context` — Export token-optimized context chunks to stdout
- `skelpr review` — Review a git diff and emit structured findings
- `skelpr fix` — Diagnose an issue and generate a minimal patch
- `skelpr validate` — Run configured test/lint/typecheck in sandbox
- `skelpr serve` — Start the local FastAPI server

**MCP**

- `skelpr install-mcp` / `skelpr uninstall-mcp` — Configure/remove the MCP server for detected agents
- `skelpr register-agent` — Register a custom MCP-compatible agent (e.g. Antigravity, Devin)

**GitHub integration (opt-in)**

- `skelpr github setup` — Configure GitHub PR review automation (manual/automatic modes)
- `skelpr github status` — Show current GitHub review automation status

## FAQ

**Do I need Docker?** No. The core runs end-to-end out of the box with in-memory fallbacks. Docker adds sandboxed validation plus Postgres + Qdrant for production-scale indexing.

**Do I need an LLM API key?** CLI mode: yes — a cloud key or a local OpenAI-compatible server. Agent mode: no — the agent brings its own LLM; local embeddings via LM Studio make the whole setup keyless.

**Which languages does it support?** Any language with a tree-sitter grammar (regex fallback for the rest); lexical search is language-agnostic via ripgrep.

**Which agents work out of the box?** Claude Code, Cursor, and Windsurf auto-detect via `skelpr install-mcp`; any MCP-compatible agent (Antigravity, Devin, …) via `skelpr register-agent`.

**How is this different from plain embedding RAG?** RAG ranks by similarity only. Skelpr fuses five signals — lexical, symbol, graph, filename, vector — with deterministic source priority, so exact matches win, every result is `path:line`-cited, and negative queries return a *provable* no.

## Roadmap

- Full cross-backend tenant isolation (Qdrant, filesystem, and sandbox scoped like PostgreSQL RLS)
- More agents pre-registered in `install-mcp`
- Repeat-run the A/B arms to quantify single-run variance (the fix task has scored 84 / 92 / 84 across identical runs)

## Development

```bash
pip install -e ".[dev]"
pytest tests/                                  # run all tests
pytest tests/test_indexing.py tests/test_retrieval.py tests/test_mcp_server.py
```

- Test the MCP server: `python -c "from skelpr.integrations.mcp_server import skelpr_health; print(skelpr_health())"`, or via the MCP Inspector: `npx -y @modelcontextprotocol/inspector@latest python -m skelpr.integrations.mcp_server` (connection, health, retrieval, symbols, dependencies, and validation verified).
- **Observability** — optional Langfuse tracing for retrieval benchmarking; each `skelpr_get_context` call produces a trace with retrieval metrics, timing, context size, and backend status. See [docs/observability-and-beta-testing.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/observability-and-beta-testing.md).
- **Benchmarking** — agent-agnostic A/B harness (Antigravity/Cursor) with per-arm artifacts; see [tests/benchmarking/README.md](https://github.com/skelpr-thrive360/skelpr/blob/main/tests/benchmarking/README.md), [docs/BENCHMARK.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/BENCHMARK.md), and the WITH/WITHOUT side-by-side answers in [docs/comparisons/](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/comparisons/) (one `COMP_<AGENT>.md` per agent).
- **Plan board** — the shortlist of next work as a checkbox list, with one detail file (why now, what to build, done-when) per item: [NEXT_STEPS/README.md](https://github.com/skelpr-thrive360/skelpr/blob/main/NEXT_STEPS/README.md).

## Docs

| Doc | Contents |
|---|---|
| [docs/BENCHMARK.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/BENCHMARK.md) | Full benchmark reports + how to reproduce |
| [docs/comparisons/COMP_ANTIGRAVITY.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/comparisons/COMP_ANTIGRAVITY.md) | WITH vs WITHOUT — every task's verbatim answer side by side (one doc per agent) |
| [docs/ARCHITECTURE.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/ARCHITECTURE.md) | Mode diagrams, retrieval engine, fallback hierarchy, enterprise features |
| [docs/CONFIGURATION.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/CONFIGURATION.md) | Local model setup + `.skelpr.yaml` reference |
| [docs/MCP_SETUP.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/MCP_SETUP.md) | MCP installation, manual registration, troubleshooting |
| [docs/observability-and-beta-testing.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/observability-and-beta-testing.md) | Langfuse tracing setup |

## Contributing

Contributions are welcome — especially **benchmark runs on other agent stacks**, new evaluator tasks, and retrieval-quality fixes.

```bash
pip install -e ".[dev]"
python scripts/check.py            # board + benchmark claims + repo hygiene (seconds)
python scripts/check.py --all      # + ruff, mypy, pytest
pytest -m "not slow and not docker and not live"   # fast loop; no Docker or backends needed
```

- **[CONTRIBUTING.md](https://github.com/skelpr-thrive360/skelpr/blob/main/CONTRIBUTING.md)** — setup, the two commands that matter, PR rules, DCO sign-off.
- **[docs/CODE_MAP.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/CODE_MAP.md)** — which module does what, plus recipes (add a language, add a retrieval signal, add an MCP tool, add a benchmark task).
- **[ROADMAP.md](https://github.com/skelpr-thrive360/skelpr/blob/main/ROADMAP.md)** — what is next, and which items are good first contributions.
- **[docs/BENCHMARK.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/BENCHMARK.md)** — reproduce or extend the A/B harness.

Two project-specific rules worth knowing before you open a PR: **published numbers must be re-derivable from artifacts** (`scripts/check_claims.py` enforces it), and **no absolute path from your machine may be committed** (`scripts/check_repo_hygiene.py` enforces it — see [docs/HYGIENE.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/HYGIENE.md)).

## Community

- **Questions and ideas:** [Discussions](https://github.com/skelpr-thrive360/skelpr/discussions) (Q&A, Ideas, Show & tell)
- **Bugs and features:** [Issues](https://github.com/skelpr-thrive360/skelpr/issues/new/choose)
- **Security:** report privately via [SECURITY.md](https://github.com/skelpr-thrive360/skelpr/blob/main/SECURITY.md) — never in a public issue
- **Conduct:** [CODE_OF_CONDUCT.md](https://github.com/skelpr-thrive360/skelpr/blob/main/CODE_OF_CONDUCT.md) · **Who decides what:** [GOVERNANCE.md](https://github.com/skelpr-thrive360/skelpr/blob/main/GOVERNANCE.md) · **Who is who:** [MAINTAINERS.md](https://github.com/skelpr-thrive360/skelpr/blob/main/MAINTAINERS.md)
- **Support and response expectations:** [SUPPORT.md](https://github.com/skelpr-thrive360/skelpr/blob/main/SUPPORT.md) · **What is stable:** [docs/STABILITY.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/STABILITY.md)

## License

Apache-2.0 — see [LICENSE](https://github.com/skelpr-thrive360/skelpr/blob/main/LICENSE) for details, [NOTICE](https://github.com/skelpr-thrive360/skelpr/blob/main/NOTICE) for the attribution
notice, and [THIRD_PARTY_NOTICES.md](https://github.com/skelpr-thrive360/skelpr/blob/main/THIRD_PARTY_NOTICES.md) for the dependencies, the
benchmark corpus and the model output quoted in the docs.

Releases are listed in [CHANGELOG.md](https://github.com/skelpr-thrive360/skelpr/blob/main/CHANGELOG.md); the release process is in
[docs/RELEASING.md](https://github.com/skelpr-thrive360/skelpr/blob/main/docs/RELEASING.md).
