User's Manual

Welcome

Thank you for bringing this in. SHPBL was built by one person who got tired of watching good software forget what it already knew — the same authentication guard written for the fifth time, the same retry loop, the same careful thing solved and then lost. Every caller who runs it is the reason it keeps getting sharper, and we hope you get something real out of it.

The free lane is a complete repository evaluation, not the full gauntlet. It returns the audit, repair order and a sealed ledger of what it found, then stops before either library is searched. The full governed sequence — composition, verification and delivery — is the Practitioner step. We would rather say that plainly than dress it up.

What the server actually does

Four movements, always in this order:

1. Audit. The repository is surveyed as it actually is — files, bytes, languages, spine files, risk signals — before any suggestion is made.
2. Name. Every capability it holds is listed with its signature, its file, its line and its stated contract.
3. Repair. The remediation is ordered, and your agent is handed verbatim source so the diffs land on real lines.
4. Harvest. What is reusable is folded into a sealed capability ledger you can keep in your own repository.

It reads public repositories that carry a proper open-source licence, your own repositories, and private repositories you have access to. No model runs on this server: the reading and the writing are always your agent's. We supply the method, the mechanical work and the library.

Connecting it

The advertised door is https://shpbl.com/mcp. It speaks OAuth: your client sends you through a sign-in page, so no key is ever typed into the client.

{
  "mcpServers": {
    "shpbl": {
      "type": "http",
      "url": "https://shpbl.com/mcp"
    }
  }
}

Clients that can only carry a static key use the key-only door instead:

URL       https://shpbl.com/api/public/mcp
Transport Streamable HTTP
Auth      None
Header    Authorization: Bearer shpbl_mcp_YOUR_KEY

If nothing in your setup speaks MCP at all — a build step, a cron job, a service — the same seventeen tools answer over plain HTTP: POST /api/public/v1/tools/{tool}, JSON in and JSON out, with the same key, the same gate and the same meter. That is documented on the HTTP API page. Nothing in this manual changes when you call it that way — only the envelope does. In TypeScript, reach for the published @shpbl/sdk client instead of writing that call yourself — see the SDK section.

Either way, a key only matters when you want a run to persist. Everything else runs without one. The step-by-step per client lives on the access page.

The TypeScript SDK

If you write TypeScript or JavaScript, the fourth door is a published package rather than a hand-rolled fetch wrapper. It is the HTTP API with types on it — the same seventeen tools, the same gate, the same key, the same meter — and no model runs inside it.

npm install @shpbl/sdk

Node 20 or newer, or any runtime with fetch — browsers, Workers, Deno, Bun. Current release 0.3.1, MIT licensed, zero runtime dependencies. Read the published package on npm and the wrapper's terms in the MIT licence.

import { ShpblClient, text } from "@shpbl/sdk";

const shpbl = new ShpblClient({ key: process.env.SHPBL_KEY }); // key optional

const audit = await shpbl.evaluateRepo({ repo: "owner/repo", brief: true });
console.log(text(audit));

Every tool listed further down this page has a method, and the tier of each one travels inside the package — so canCall(), tierOf() and ask() answer “may I call this?” with no request at all. Hitting the key wall is an object you can read, not a stack trace you parse.

• welcome() → welcome · free
• methodProtocol() → method_protocol · free
• listRepos() → list_repos · free
• evaluateRepo() → evaluate_repo · free
• fixRepo() → fix_repo · free
• harvestRepo() → harvest_repo · free
• composeCapability() → compose_capability · free
• buildIntent() → build_intent · free
• libraryIndex() → library_index · free
• runContract() → run_contract · free
• pinSource() → pin_source · free
• selfcheck() → selfcheck_mcp · free
• subscriptionStatus() → subscription_status · free
• runGauntlet() → run_gauntlet · $39/mo
• librarySearch() → library_search · $39/mo
• libraryDocument() → library_document · $39/mo
• writeToRepo() → write_to_repo · $39/mo

The conducted run keeps its rules here too. The server holds no session, so each step past the first carries the ledger digest your model folded and the fold token the last step returned; the pause for a person is real, and approval is never implied.

import { ShpblClient, gauntlet } from "@shpbl/sdk";

const shpbl = new ShpblClient({ key: process.env.SHPBL_KEY });
const session = gauntlet(shpbl, { repo: "owner/repo" });

let ledger = "";
let step = await session.next(); // step 1

while (!step.done) {
  console.log(step.text);                       // your model reads this batch
  ledger += `\n${yourModelsLinesFor(step)}`;    // one line per capability

  if (step.checkpoint) session.acknowledge();    // only if a person said yes
  step = await session.next({ ledgerDigest: ledger });
}

A contract moves; compatibility() tells you whether the release you pinned still matches the live server, so you hear about a change from your own pipeline rather than a bug report. The client reference — options, error classes, the drift report — lives on the SDK page. The method it runs is this manual.

Your first run

On the first message of a new conversation your agent calls welcome — the onboarding tool. It returns this manual in miniature: the greeting, the tool menu and the sentences you can say. Then say something like “audit owner/repo with SHPBL”, and it begins.

If you would rather see the shape of the job before you spend anything, ask for an estimate first. harvest_repo with mode: "walk" and estimate: true reads no source at all and tells you the batch count and the character total. It is free, and it is the honest pre-flight.

The seventeen tools

In the order a run uses them. Twelve are free with no key; five are what a $39/month subscription opens.

Things you can just say

You never call a tool yourself. You talk to the agent you already use, and it picks.

• “Audit <owner>/<repo> with SHPBL and tell me plainly what it can do.”
• “With my Practitioner key, run the full SHPBL gauntlet on my repo and check in at every step.”
• “Estimate a SHPBL harvest first — I want to know the cost before we start.”
• “Use SHPBL to write the fix for the thing it flagged, and show me the diff.”
• “Ask SHPBL whether this problem is already solved in its library.”
• “Have SHPBL audit itself so I can see whether the method is real.”

How a run behaves

The procedure is law, not advice — and that is enforced by the server, not requested of the model. In practice you should see:

• One step per turn. Call, do, report a single readable line, then the next. Never the whole run in one breath.
• Proof of the last step. The conductor refuses step two and beyond without the digest of the step before it, so no step can be skipped quietly.
• A check-in. Every third harvest step it stops, reports, and asks whether to continue. You can ask for fewer pauses; the agent may not raise the interval on its own.
• No filling in gaps. If the supplied material does not answer something, it writes “not present” rather than guessing.
• A named deviation. There is exactly one legal reason to depart from a step — it would break a stated rule — and when that happens it stops and asks you.

What it will never touch

Some files are read by the tools you build with, so a change that looks obviously right in a diff can break your running app the moment it merges. A run reads them, writes about them, and hands the decision to you and to whatever agent already owns them: environment files, every lockfile, generated code, agent instruction files, backend wiring and migration history, build, CI and deploy config, .git, vendored output and anything holding a credential.

The write-back tool refuses those paths outright, at every tier, with no override.

Reusing your own harvest

A kept run writes a .shpbl/ folder into your repository, with a README.md that lists what was harvested. On the next run, ask your agent to read those lines and pass them back as the run's own library. It then checks each concern against what you already solved before citing anything new — your library compounds, and it stays yours. Those entries are held for that one call and never stored by SHPBL.

The library it reasons against

The library contains 1,000+ engineered components and 3,000+ runnable capability units, counted separately and never summed. The engineered components are engines, building blocks and finished products that ship real source. The capability units are the runnable parts your agent composes from; they carry no catalogue warranty, and an agent is told so before it cites one. The crown jewels are standalone artifacts that need no composition to run, of which 121 are certified by the harness, 88 are provisional, and 53 are inconclusive because the harness could not exercise their input contract — a limit of the harness, never a defect claimed about the artifact.

Model-free here means one specific thing: no model runs inside our runtime, and the library is owned outright. Nothing in the library is model output, and no call we make reaches a model on your behalf. Your agent does the reading and the writing; we supply the method, the mechanical work and the library.

The meter, plainly

A Practitioner month covers 100,000 calls. Refused calls are not charged — if the server declines a call for entitlement, licence or safety reasons, it is not metered. At call 100,001 the paid tools stop for the rest of the calendar month, the counter resets on the first, and the keyless free tools keep working. No overage is sold and none is billed; write to us and the ceiling is lifted once for that month at no charge. One key per person, unlimited machines and CI, no device or seat check anywhere.

Keeping what a run produces

The $499 Complete Master Library is a tangible thing: a hard copy mailed to your home, licensed to you in perpetuity, and a second copy contributed to a nonprofit you choose. Borrowing the capability library over MCP or the API is free for the first seven days, then $39 a month, and cancels in one link in Stripe. Either way, whatever a run produces is yours outright — nothing flows back into our library, and there is no contribution loop.

Support, ideas and suggestions

Write to dev@KESJr.com. A real person reads it, and good ideas from callers have changed this server before. If a run found something surprising in your repository, we would like to hear about that too.

Kenneth E. Sweet Jr. · SHPBL · Abilene, Texas — made by humans who care.