Metadata-Version: 2.5
Name: jeles
Version: 0.20.0
Summary: Jeles' verified-nugget corpus organ: pure SOIL-backed storage/ranking, a standalone MCP server, best-effort fleet gap-forwarding, and the canonical Jeles persona.
Project-URL: Homepage, https://github.com/hornbook-knowledge/Jeles
Project-URL: Repository, https://github.com/hornbook-knowledge/Jeles
Project-URL: Issues, https://github.com/hornbook-knowledge/Jeles/issues
Author: Sean Campbell
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: citations,corpus,jeles,librarian,mcp,retrieval,verified-answers,willow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Provides-Extra: connectors
Requires-Dist: arxiv>=2.1.0; extra == 'connectors'
Requires-Dist: biopython>=1.83; extra == 'connectors'
Requires-Dist: habanero>=1.2; extra == 'connectors'
Requires-Dist: internetarchive>=4.0; extra == 'connectors'
Requires-Dist: musicbrainzngs>=0.7.1; extra == 'connectors'
Requires-Dist: pyalex>=0.15; extra == 'connectors'
Requires-Dist: pygbif>=0.6.0; extra == 'connectors'
Requires-Dist: pyinaturalist>=0.19.0; extra == 'connectors'
Provides-Extra: dev
Requires-Dist: mcp<3.0.0,>=2.0.0; extra == 'dev'
Requires-Dist: nestor-meaning==0.18.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml; extra == 'dev'
Requires-Dist: tomli; (python_version < '3.11') and extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<3.0.0,>=2.0.0; extra == 'mcp'
Provides-Extra: nestor
Requires-Dist: nestor-meaning==0.18.0; extra == 'nestor'
Description-Content-Type: text/markdown

# jeles

The **verified-corpus organ**, extracted from the [Ask Jeles](https://github.com/rudi193-cmd) app into its own installable package — plus the canonical **Jeles persona**.

A *nugget* is a human-verified question/answer pair with citations:
`{question, answer, sources, verified_by, verified_at, tags}`. This package
is the settled layer of answers that sits *in front of* a host's live
search — a confident nugget match answers instantly; everything else falls
through to the host's own search path unchanged. Misses are logged as
*gaps* ("I don't know yet") so the corpus knows what it's been asked and
couldn't answer.

## What's in the organ

| Module | Role |
| --- | --- |
| `jeles.corpus` | Pure storage + ranked lookup of verified nuggets and gap logging. **Stdlib-only, no MCP, no network at import.** Reuses willow-mcp's SOIL `Store` SQLite schema at `$WILLOW_STORE_ROOT/<collection>/store.db` — writes are upserts that touch only jeles' own columns, in WAL mode with `BEGIN IMMEDIATE`, so the store really is shared rather than shared-until-one-side-writes. |
| `jeles.reactions` | Pure `(event) -> [proposed actions]` handlers. `conflict_scan` searches for what *supersedes or refutes* a design claim rather than what resembles it, and proposes a nugget only when two **independent, relevant, non-excluded** domains corroborate it — otherwise a contested gap. `search_adapter` is its web edge. |
| `jeles.corpus_server` | Standalone `MCPServer` (MCP SDK 2.x) over the corpus (`python -m jeles.corpus_server`). Mirrors willow-mcp's shape (`app_id` on every tool) **without depending on willow-mcp**. Writes through it are *assertions*, not verifications — see [below](#as-a-standalone-mcp-server). |
| `jeles.sources` | **The institutional collections themselves** — 66 registered source functions, 62 of them in the default fan-out (arXiv, PubMed, Crossref, OpenAlex, Library of Congress, Europeana, CourtListener, the Smithsonian, the Almanac's dataset catalogs), plus the concurrent fan-out across them. **Stdlib-only** at import; optional `jeles[connectors]` prefers maintained clients for a first slice and keeps urllib fallbacks. |
| `jeles.connectors` | Optional façades over pyalex / habanero / arxiv / Bio.Entrez / internetarchive / musicbrainzngs / pygbif / pyinaturalist. Not imported until a `search_*` call asks. |
| `jeles.institutional` | The third hop: fans a query across `jeles.sources` in-process, and shapes results like every other hit. Optionally delegates to a hosted [`jeles-remote`](https://github.com/rudi193-cmd/jeles-remote) instead. |
| `jeles.willow_mcp_client` | Best-effort, fire-and-forget forwarding of gaps into willow-mcp's fleet-wide backlog. Never blocks, never raises; 30s retry cooldown so a single failed connect doesn't permanently disable forwarding. |
| `jeles.load_persona()` | Loads the canonical Jeles persona JSON (this package is its canonical home). |

## Design principles

1. **The corpus sits in front of live search, it doesn't replace it.** A confident nugget match answers instantly — no search, no LLM call.
2. **`corpus.py` stays pure.** Storage and ranking have no MCP, no network, no side effects beyond SQLite. Everything MCP-shaped wraps it; it never depends on anything MCP-shaped itself. This is what keeps its tests fast and network-free.
3. **The corpus is its own standalone MCP server, on purpose.** `corpus_server.py` is a small `MCPServer` any stdio client can run directly, mirroring willow-mcp's shape without depending on it.
4. **Two kinds of "ask," two gap-logging rules.** `search_nuggets()` (passive/background) checks the corpus but never logs a gap on a miss. `ask_corpus()` (deliberate) treats a miss — or a match below `MIN_ASK_SCORE` — as a real gap worth tracking, and logs it.
5. **Ranking and answering are different decisions.** `search_nuggets()` ranks loosely and will happily surface a near-miss. `ask_corpus()` answers only when the nugget's question contains *every* content word the asker used, and the two questions overlap symmetrically — so a nugget about *staging* cannot answer a question about *production*, and one word cannot pull an answer out of a nugget it barely resembles. Saying "I don't know yet" and logging the gap is the correct output far more often than it looks.
6. **The collections live here, not behind a service.** `sources.py` is the same relationship `corpus.py` has with `corpus_server.py`: a pure core that something thin wraps. A hosted deployment is a convenience — never a prerequisite, never a secret you must hold, never a second repository in the test loop. Stated precisely, because the short version was wrong: `jeles-remote`'s `main.py` is a 74-line FastAPI shim, but it wraps its **own vendored copy** of `sources.py` (`import sources`, a file in that repo), not this module. That copy was forked from the same origin and has drifted — 833 differing lines, ~200 fewer, six fewer source functions, and *zero* references to `_egress`, so the SSRF/key-leak fix that landed here is simply absent from it. Treat jeles-remote as a downstream fork due a re-vendor, not as a thin wrapper that inherits this package's fixes.
7. **Local is the source of truth; the fleet backlog is additive.** `corpus.log_gap()` (synchronous, local SQLite) always runs first and makes the host fully functional offline. `willow_mcp_client.forward_gap()` is a *best-effort* copy into willow-mcp's shared backlog.

## Quick start: on your own, no fleet

Jeles was built as an organ inside a willow-mcp fleet, where the fleet signs
each app's manifest and that manifest bounds what the corpus may touch. It
refuses to open its store without one, signed. On your own machine, make one
and sign it with your own GPG key:

```bash
pip install jeles
jeles-seed --init-local     # writes ~/.jeles, signs the manifest with your default GPG key
# then export the three variables it prints, e.g.:
export WILLOW_MCP_APPS_ROOT=~/.jeles/mcp_apps
export WILLOW_STORE_ROOT=~/.jeles/store
export JELES_CORPUS_APP_ID=jeles-corpus
jeles-seed                  # load the bundled seed
python -c "from jeles import corpus; print(corpus.ask_corpus('What is a black hole?'))"
```

`--init-local` keeps to its own `~/.jeles` tree (or `--home DIR`), never
willow-mcp's `~/.willow/mcp_apps`. The manifest it writes grants only the
corpus's own two collections, and it never overwrites an existing one. If
`gpg` isn't installed or you have no key yet (`gpg --quick-gen-key "Your
Name <you@example.org>"` makes one), the manifest is left unsigned and the
command prints the one `gpg --detach-sign` line to run. Jeles itself never
writes or imitates a signature.

Then set the two things only you can supply: `JELES_SOURCES_CONTACT_EMAIL`
(your address for the scholarly APIs' polite pools) and, if you'll review
intake material yourself, `JELES_VERIFIER` (your name). Both are in
[Configuration](#configuration).

## Install

**Base `jeles` has zero runtime dependencies.** The corpus, the persona, and the
reactions are stdlib-only, so a host can depend on this package without
inheriting a single version constraint from it. Only the standalone MCP server
needs the SDK, and it lives behind an extra.

```bash
pip install jeles           # corpus + persona + reactions. No dependencies.
pip install "jeles[mcp]"    # adds the MCP SDK, for the standalone server
pip install "jeles[nestor]" # adds Nestor, to check human-rung seals (below)
pip install "jeles[connectors]"  # maintained clients for institutional sources (optional)
pip install -e ".[dev]"     # editable, with pytest and the SDK
```

`jeles.sources` stays stdlib-only at import. With `[connectors]`, eight
scholarly/biodiversity façades (OpenAlex, Crossref, arXiv, PubMed, Internet
Archive, MusicBrainz, GBIF, iNaturalist) prefer the maintained client and keep
their urllib twins as fallback. Scrapers and the rest of the registry are
unchanged. Connector HTTP uses the client's own stack and therefore bypasses
`jeles._egress` / `_urlopen` guards; the urllib twin path keeps those caps
(Loki F3 — accepted adoption trade).

### The seed corpus

The wheel ships a starting corpus: **87 files, 1163 question/answer pairs**, in
`jeles/seed/`, beside the 84 host cards. It is not loaded on install and not on
first use — seeding writes to *your* store, and an unrequested write is the
thing `corpus_put`'s gate exists to refuse. It is a command you type:

```bash
jeles-seed --dry-run    # report what would be written, write nothing
jeles-seed              # load it into $WILLOW_STORE_ROOT
```

**What this batch is.** It was produced by research agents running adversarial
rounds against themselves — challenge, factcheck, steelman — and the rounds'
own artifacts ship alongside the answers, so the reasoning is auditable rather
than summarised. That is real work, and it is still a machine's. So every pair
loads at `asserted` unless a signature or the commons rule below says
otherwise, and an `asserted` nugget **cannot answer a question**: `corpus_ask` returns it under `candidates` with
`found: false`. An unsigned seed makes the corpus *searchable*, not *settled*.

**What a signature changes.** A pair carrying a Nestor seal
(`{"seal_sig": "..."}`, signed over the normalized question, the answer, and
the signer's name) is verified *on your machine*, against a keyring *you*
trust, and lands at `verified`. That is the whole reason to ship seals rather
than a `verified: true` field. A field is a claim by whoever shipped it; a
signature is evidence you can check without trusting them at all. Seals that do
not verify here are not discarded — the pair loads at the rung it can prove,
the signature travels with it for a reviewer, and `jeles-seed` prints how many
were refused and why.

Signing cannot happen in this package. `jeles._nestor_seal` verifies and never
signs, and `nestor.keyring` refuses to produce a seal from a public-key entry:
*"Signing happens where the private key lives."* So the `verified` rung is
reachable only where a person, out of process, has already earned it.

**Commons are the exception: verified by the public record, no seal needed.** Seed pairs
in `core-*` domains, in files classified `"commons"`, or classified
`"commons"` one pair at a time (an agreed fact inside a file that is otherwise
argument, such as a fact-check verdict), with citations, are knowns, not
claims. They land at `verified`, credited to the record they rest on and not
to whoever loaded them: `verified_by: "public record: NASA, Encyclopaedia
Britannica"` and `evidence: {"scheme": "public-record-v1", "credited_to":
[...], "sealed": false}`. The people behind each discovery are named in the
card itself. That is a citation, not a signature. Every entry that can answer
(`verified` or `corroborated`) is stored at `visibility: "serve"`, so a
session reading the shared SOIL store through willow-mcp's serve mode, which
caps callers at `serve`, can use it; asserted research stays `internal`. It never carries a `seal_sig`, so a
reader can still tell it apart from a sealed pair, and Nestor reconciliation
can find what is still left to seal.

**Seal ≠ sole evidence of human verification.** A missing seal (asserted seed,
unsealed intake, draft/pending in a sibling organ) means this corpus cannot
*prove or serve* a human receipt yet — not that no human ever checked the
claim. Sealing catches the ledger up to human work already done. Agents must
still refuse to present asserted/unsealed material as settled: that is what
the ladder authorizes, not a verdict about offline human review.

Or as a host dependency, straight from git — the default branch is `master`,
and `@main` resolves to nothing here:

```
jeles @ git+https://github.com/hornbook-knowledge/Jeles@master
```

Prefer a released version over a branch for anything you deploy: a branch ref
re-resolves on every install, so two machines built a week apart get different
code under the same requirement line.

`jeles[mcp]` requires **MCP SDK 2.x** (`corpus_server.py` uses
`mcp.server.mcpserver.MCPServer`; `mcp.server.fastmcp` was removed in SDK 2.0).
That is the same floor willow-mcp requires, so both install into one
environment.

### Versioning

The version comes from the git tag (`hatch-vcs`), not from a literal in
`pyproject.toml`, and `jeles.__version__` reads it back out of installed package
metadata. There is exactly one place a release number is decided, so a tag
cannot disagree with the artifact it builds.

## Usage

### As a library

```python
from jeles import corpus

corpus.put_nugget(
    question="What is the primary color in Grove?",
    answer="The primary color in Grove is #ffffff (white).",
    sources=["safe-library/themes/grove.json"],
    verified_by="designer",
    tags=["color", "grove", "primary"],
)

hit = corpus.ask_corpus("What is the primary color in Grove?")
# -> {"found": True, "exact": True, "nugget": {...}, "candidates": [...]}

miss = corpus.ask_corpus("What is the accent color in Tokyo Night?")
# -> {"found": False, ...}   and the question is logged as a gap
```

### As a standalone MCP server

```bash
python -m jeles.corpus_server      # stdio; or use the `jeles-corpus-mcp` console script
```

Tools: `corpus_ask`, `corpus_search`, `corpus_get`, `corpus_list`, `corpus_put`,
`corpus_gaps`, `corpus_resolve_gap`, `corpus_web_search`, `corpus_search_status`,
`corpus_institutional_search`, `corpus_sources`, `corpus_verify_claim`,
`corpus_host_card`, `corpus_fleet_status` — each
takes an `app_id` for naming-convention parity with willow-mcp. Four of those
are the outward hops: the open web, why a search returned what it did, the 61
institutional and academic collections, and what those collections are. They
were added without this list being updated, so it said six for as long as there
were ten — and again on 2026-08-28, when two tools were registered, tested, added
to this list, and left out of `corpus_server`'s own module docstring. Three lists
say what the tools are, so all three are now pinned to the registry:
`test_exactly_the_documented_tools_are_registered` (a new tool cannot appear
unnoticed), `test_the_module_docstring_names_every_registered_tool`, and
`test_the_readme_names_every_registered_tool` — this paragraph included. That is
why the count above can be trusted.

`corpus_resolve_gap` closes a gap — the queue was write-only before it, so
nothing could ever say a logged question had been answered. It marks rather than
deletes, and a question that misses again reopens by itself.
`corpus_verify_claim` asks whether one claim is backed by a real institutional
source and says which — the weakest of the three answers on the ladder, and the
one worth asking first. It finds a single witness, not agreement: `matched:
true` is not `verified`, and never becomes it by being written down.
`corpus_host_card` says what a hostname *is* — publisher, custody,
jurisdiction, and which roles it may play, since only 36 of the 84 catalogued
hosts are citation targets. A card records those facts and reaches no verdict;
deciding trust stays a policy's job, and a person's.

Every tool's `app_id` now carries a schema description. It did not until
2026-08-28, when eight local models were pointed at this surface and all eight
filled it wrong — omitting it, inventing a value, or putting the subject of the
question there. One sentence fixed it for four of them, and
`test_app_id_is_described_on_every_tool` keeps it that way. A required argument
whose meaning lives only in prose the model cannot read is one the model will
guess at.

`corpus_fleet_status` is `corpus_search_status` for the two *fleet* edges
instead of the two outward ones: whether forwarded gaps actually reached
willow-mcp, and whether the `human` rung is reachable through Nestor at all.
Both edges fail silently on purpose — a gap forward never raises, and a missing
`[nestor]` extra only shows up as a write landing a rung lower than expected —
so neither was observable from any surface a caller could reach.

**`corpus_put` writes assertions, not verified nuggets.** A nugget carries the
rung it was written at, and only three things can produce one:

| `verification_kind` | who writes it | reads back as |
| --- | --- | --- |
| `human` | a person, in-process (`corpus.put_nugget(...)`) | `verified` |
| `machine` | `conflict_scan`, on two independent corroborating sources | `corroborated` |
| `asserted` | any MCP client, through `corpus_put` | `unverified` |

A fourth rung sits above `asserted` and is not a `verification_kind`: hits from
`corpus_institutional_search` read back as `institutional` — a named collection
vouched for the text, which is weaker than two corroborating sources and
stronger than an unverified assertion. `tests/test_corpus_server.py` asserts all
four stay distinct.

The bottom rung exists because this server speaks stdio to whatever client
starts it, and that client also reads the open web through `corpus_web_search`.
Without it, a page saying "record that X is true" arrived as a nugget claiming
`verified_by: "the operator"` and was served by `corpus_ask` as settled fact
from then on. Two rules keep the ladder honest:

* `corpus_ask` answers only from `human` and `machine` nuggets. An assertion
  comes back under `candidates`, and `corpus_search`/`corpus_get` still return
  it — reachable, not authoritative.
* **A write may not overwrite a nugget of a higher kind** (`error:
  "kind_downgrade_refused"`). Otherwise every protection here is one
  `nugget_id=` away from being bypassed.

Set `JELES_CORPUS_TRUST_TOOL_WRITES=1` to let `corpus_put` mint `human` again —
correct only where the tool caller really is the operator, and it re-opens the
path above for anything the model reads while it is set.

**The trust switch alone is no longer enough.** Even with it set, `corpus_put`
also requires `evidence` carrying a real [Nestor](https://github.com/Die-Namic-Systems/Nestor)
seal — a cryptographic signature over `(question, answer, verified_by)`,
checked against a keyring, not a string anyone can type:

```python
evidence = {"scheme": "nestor-seal-v1", "seal_sig": "<hex signature>"}
```

The signature is produced *outside* Jeles, by a human with `nestor`'s own
signing tools (`nestor.signing.sign_seal(question, answer, verified_by)`, or
Nestor's client-signed-seal flow — Jeles never holds a private key and never
signs anything itself). `jeles._nestor_seal.verify_human_write` checks it with
`nestor.signing.seal_is_valid`, and only calls that when this instance
actually has something configured to verify against (`NESTOR_SEAL_KEY` or a
`NESTOR_KEYRING`) — an *unconfigured* instance refuses rather than falling
back to Nestor's own "no key set" legacy default, which is to accept every
signature. Without a valid seal the write still succeeds, just at
`verification_kind: "asserted"` — refused the rung, not trusted for it. Needs
the `[nestor]` extra; without it, `corpus_put` behaves exactly as if no
evidence had verified, whatever the trust switch says.

This closes a specific, previously-forgeable path (box scan
`design/box-scan-2026-07-24.md` B6): the trust switch used to be sufficient by
itself, so any tool caller that knew it was set could type `verified_by="a
human"` and land on the top rung. The direct in-process route —
`corpus.put_nugget(...)`, called from a person's own script — is unaffected;
it was never reachable from a tool in the first place, and this module does
not gate it.

### The persona

```python
import jeles
persona = jeles.load_persona()   # dict; canonical Jeles persona
```

## Configuration

| Env var | Default | Effect |
| --- | --- | --- |
| `WILLOW_STORE_ROOT` | `~/.willow/store` | Root under which `<collection>/store.db` lives. |
| `JELES_CORPUS_COLLECTION` | `ask_jeles_corpus` | Nugget collection name (back-compat with Ask Jeles). |
| `JELES_CORPUS_GAPS_COLLECTION` | `ask_jeles_corpus_gaps` | Local gap-log collection name. |
| `JELES_CORPUS_APP_ID` | `ask-jeles` for gap-forwarding; `jeles-corpus` for the manifest-scoped store gate (see `jeles/corpus.py`) | `app_id` used both when forwarding gaps to willow-mcp and when the corpus checks its own manifest-scoped `store_scope`/`store_write`. **Set this to `jeles-corpus` on a willow-mcp fleet — never `jeles`, the retired Ask Jeles specialist seat, which is refused outright** — see below. |
| `JELES_CORPUS_TOPIC` | `ask-jeles-corpus` | Backlog topic gaps are forwarded under. |
| `WILLOW_MCP_CMD` | — | Explicit command to launch willow-mcp (else `willow-mcp` on PATH, else `python -m willow_mcp`). |
| `ASK_JELES_USE_WILLOW_MCP` | `1` | Set to `0`/`false`/`no` to disable fleet gap-forwarding entirely. |
| `JELES_CORPUS_TRUST_TOOL_WRITES` | unset | Set to `1` to let `corpus_put` write `human`-verified nuggets — but only when the write also carries a verifying Nestor seal; see [the MCP server section](#as-a-standalone-mcp-server). |
| `NESTOR_SEAL_KEY` / `NESTOR_KEYRING` | unset | Read by `nestor.signing` (via the `[nestor]` extra), not by this package directly — what a `human`-rung seal is checked against. Neither set means `corpus_put` refuses the `human` rung outright, whatever `JELES_CORPUS_TRUST_TOOL_WRITES` says. |

| `JELES_REMOTE_URL` | unset | Base URL of a `jeles-remote` delegate. **Unset means the in-process fan-out is the only lane** — remote is opt-in, not a default. |
| `JELES_REMOTE_SECRET` | unset | Shared secret sent as `X-Jeles-Secret`. Dropped if a redirect changes host — see `_egress.SchemeGuardedRedirects`. |
| `JELES_REMOTE_TIMEOUT` | `20` | Seconds before the remote delegate is given up on. |
| `JELES_SEARCH_BACKEND` | `ddg` | Open-web backend: `searxng`, `brave`, `tavily` or `ddg`. Only `searxng` may reach a private address, because only it is an address the operator chose. |
| `JELES_SOURCES_CONTACT_EMAIL` | unset | Your contact address for the OpenAlex/Crossref "polite pool" and NCBI's `email` parameter, which buy better rate limits. **No default** — it identifies whoever runs the deployment, so unset means the parameter is omitted and the calls go anonymous. |
| `JELES_SOURCES_UA` | `Jeles/1.0 (academic librarian; +<repo URL>)` | User-Agent for the source APIs. Set it to identify your own deployment. |
| `JELES_INTAKE_DIR` | `./jeles-intake`, else a sibling `willow-memory/jeles-intake` | Where the intake scripts read local Q/A JSON from. |
| `JELES_FLEET_ENV` | unset | A `fleet.env` the scripts read `WILLOW_STORE_ROOT` and friends from when they are not exported. Without it they look in `$WILLOW_HOME`, a sibling `willow-memory` checkout, then `~/.willow`. |
| `JELES_VERIFIER` | unset | The reviewer's name for `scripts/jeles-verify-intake.py`. **No default** — the script refuses to promote anything until a person is named, by this or `--verified-by`. |
The Ask Jeles-flavored defaults are preserved so an existing store and its
already-forwarded fleet backlog keep resolving after the extraction.

### Forwarding gaps to a willow-mcp fleet

Two settings decide whether `forward_gap()` lands anything, and until recently
neither said so when it was wrong:

- **`JELES_CORPUS_APP_ID`.** willow-mcp authorizes every tool call against
  `$WILLOW_HOME/mcp_apps/<app_id>/manifest.json`, and the back-compat default
  `ask-jeles` is not a seat it seeds — so out of the box a forward is denied
  with `no manifest for 'ask-jeles'`. Set it to `jeles-corpus`, the organ's
  own seat, once the operator has seeded and signed its manifest (and given
  it `gap_write`). **Never `jeles`** — that is the retired Ask Jeles
  specialist seat, not this organ's identity, and `jeles/corpus.py`'s own
  manifest-scoped store gate refuses it outright (ae23d366). This same env
  var also decides which manifest `jeles/corpus.py` checks its local
  reads/writes against, so the value has to be one seat for both purposes.
  The *topic* is independent: gaps still land under `ask-jeles-corpus` unless
  `JELES_CORPUS_TOPIC` says otherwise, so an existing backlog keys the same.
- **`WILLOW_STORE_ROOT`.** Unset, this package writes under `~/.willow/store`
  while willow-mcp serves `$WILLOW_HOME/store` — both work perfectly, on two
  different databases, with no error on either side.

`willow_mcp_client.forward_status()` reports which seat is in use, how many
forwards have landed, and why the last one failed. It exists because the
failures used to be unobservable: `forward_gap()` caught everything, logged at
DEBUG, and dropped it, so a misconfigured fleet looked exactly like a working
one. It still never raises and never blocks — a host asking a question must not
fail because a fleet backlog is unreachable — it just no longer stays quiet
about it.

To stand this package up against real willow-mcp and nestor checkouts in one
command (one venv, one store, one gate, then six seam checks), use willow-mcp's
`scripts/fleet-standup.sh`.

## Tests

```bash
pytest -q
```

`corpus.py`'s tests are fast and network-free by construction. The willow-mcp
client tests do not spin up a real subprocess — but that is now enforced rather
than assumed. `_launch()` resolves a launcher from three independent probes
(`$WILLOW_MCP_CMD`, a `willow-mcp` console script on `PATH`, an importable
`willow_mcp` package) and any one of them succeeding produces a launcher, so
stubbing only `shutil.which` left the third probe answering from whatever the
venv happened to contain. The dependency edge runs willow-mcp → jeles, so the
normal deployment of this module has `willow_mcp` importable beside it, and
there those tests really did spawn one. CI never noticed, because it installs
`jeles[dev,mcp]` and nothing else — the probe failed by accident of the install
set. The `no_willow_mcp` fixture (`tests/test_willow_mcp_client.py`) shuts all
three, `None` in `sys.modules` being the import system's own "this import must
fail" sentinel. An import-purity test asserts that importing `jeles.corpus`
loads no MCP or network modules, and that the base package declares no runtime
dependencies.

`tests/test_corpus_server.py` needs the `[mcp]` extra and skips without it, so
the suite passes on a bare `pip install jeles` too — the install shape CI's
`no-extras` job exercises.

## License

Apache-2.0 — see [LICENSE](LICENSE).
