# Switchplinth

> A local-first tool that reads the ADRs, RFCs, and design docs already in your repository, extracts decisions with cited evidence, and lets you explore what-if scenarios. Canonical data is portable YAML in a .decision/ folder beside the Markdown; it runs locally with Docker Compose and exposes an MCP server on localhost.

Source: https://github.com/bcmyguest/switchplinth (Apache-2.0)

## Docs

- [Getting started](https://bcmyguest.github.io/switchplinth/docs/getting-started.md): Set up a repository and its MCP server with the setup wizard, or run the one-command food-delivery demo in Docker.
- [Up next](https://bcmyguest.github.io/switchplinth/docs/roadmap.md): What works today, and the next steps - hosted-provider tests, recall measurement, extraction beyond the sample, authentication, more formats, richer conflicts, scenario lifecycle.
- [How it works](https://bcmyguest.github.io/switchplinth/docs/architecture.md): The path from repository Markdown to evidence anchors, extracted decisions, canonical YAML, compiled scenarios, and search indexes, with the code behind each stage.
- [Concepts](https://bcmyguest.github.io/switchplinth/docs/concepts.md): Decisions, options, typed deltas, scenarios, claims, evidence anchors, and how machine inference differs from human review.
- [Portable format reference](https://bcmyguest.github.io/switchplinth/docs/portable-format.md): The .decision/ folder layout and the decision/v1 YAML records for evidence, claims, entities, aliases, decisions, scenarios, and model connections.
- [Model providers](https://bcmyguest.github.io/switchplinth/docs/providers.md): Configure a local OpenAI-compatible model server or a hosted provider for extraction and embeddings, and read the connection diagnostics.
- [MCP tools](https://bcmyguest.github.io/switchplinth/docs/mcp.md): Five read-only Model Context Protocol tools for listing decisions, searching evidence, inspecting the graph, and diffing scenarios, with input receipts, over HTTP or stdio.
- [FAQ](https://bcmyguest.github.io/switchplinth/docs/faq.md): Answers on templates, where data lives, model requirements, re-extraction safety, remote access, and what the sample does and does not show.

## Works today

- Setup wizard (`switchplinth setup`): repository or sample, first scan, MCP registration with Claude Code, Claude Desktop, Cursor, or VS Code.
- One-command Docker demo of the food-delivery sample (`./scripts/demo.sh`).
- Deterministic mock extraction and local OpenAI-compatible model extraction; a local Qwen3.8 model with reasoning off found all 7 sample decisions.
- Review log with undo, layered architecture map, What-if previews, grounded "why" answers with cited passages.
- Scenario diffs between any two selection maps, with relationship-based downstream impact (API and MCP `diff_scenarios`).
- Input receipts on graph, scenario, search, and diff results; repeat a call and compare `receipt.digest` to detect stale results.
- Capability checks from extracted requires/provides/lacks claims: What-if, API, and MCP report a component left without a required capability reachable within four relationship hops (claim-based, not code analysis).
- Five read-only MCP tools over streamable HTTP (loopback, unauthenticated) and stdio: list_decisions, search_decisions, inspect_architecture, inspect_entity, diff_scenarios.

## Up next

- Test hosted providers (OpenAI, Anthropic); untested today.
- Measure extraction recall on more repositories.
- Extraction beyond the sample, whose demo uses fixture-tuned mock rules.
- Authentication for remote API and MCP access; loopback-only today.
- More source formats beyond Markdown.
- Conflict detection beyond same-ID writes.
- Scenario rename, update, and delete.

## Optional

- [Full docs in one file](https://bcmyguest.github.io/switchplinth/llms-full.txt)