sift-cli 1.0.2__tar.gz → 1.1.0__tar.gz

{sift_cli-1.0.2 → sift_cli-1.1.0}/.github/workflows/ci.yml

@@ -22,9 +22,12 @@ jobs:
         python: ["3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
-      - uses: astral-sh/setup-uv@v5
+      # Pinned to a full version, not a major alias: this action does not
+      # publish one. `@v10` resolves to nothing and every leg of CI fails
+      # before it runs a line -- which is how this was found.
+      - uses: astral-sh/setup-uv@v10.0.1
         with:
           enable-cache: true
 

sift_cli-1.1.0/.github/workflows/registry.yml

@@ -0,0 +1,72 @@
+name: registry
+
+# The MCP registry is the one channel that reaches a model too new to have been
+# trained on this package: clients query it live. Publishing there is a separate
+# act from publishing to PyPI because it depends on it -- the registry proves
+# that we own `sift-cli` by reading the description of the exact version named
+# in server.json, which only exists once PyPI has it.
+#
+# So this runs on the tag as well, and waits rather than assuming.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      # Trusted publishing again, and for the same reason: GitHub signs a
+      # short-lived token saying which repository this is, and the registry
+      # believes that rather than a secret we would have to store and rotate.
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+
+      # Four places say the version and they are written by hand. The test suite
+      # holds three of them together; the tag is the fourth and only exists here.
+      - name: The tag and server.json agree
+        if: github.ref_type == 'tag'
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          entry=$(python -c "import json;print(json.load(open('server.json'))['version'])")
+          echo "tag=$tag server.json=$entry"
+          test "$tag" = "$entry"
+
+      # PyPI is the source of truth for ownership, and the release workflow is
+      # still finishing when this starts. Ten minutes is generous; the wait is
+      # cheap and the failure it prevents is a publish that says the package
+      # does not exist.
+      - name: Wait until PyPI has that version
+        run: |
+          version=$(python -c "import json;print(json.load(open('server.json'))['version'])")
+          for _ in $(seq 1 60); do
+            code=$(curl -s -o /dev/null -w '%{http_code}' \
+              "https://pypi.org/pypi/sift-cli/$version/json")
+            if [ "$code" = "200" ]; then
+              echo "PyPI has $version"
+              exit 0
+            fi
+            echo "PyPI does not have $version yet ($code); waiting"
+            sleep 10
+          done
+          echo "PyPI never showed $version" >&2
+          exit 1
+
+      # Pinned, not `latest`: what publishes a release should not change under
+      # it between one release and the next.
+      - name: Install mcp-publisher
+        run: |
+          curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1/mcp-publisher_linux_amd64.tar.gz" \
+            | tar xz mcp-publisher
+          ./mcp-publisher --help > /dev/null
+
+      - name: Log in with GitHub OIDC
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish
+        run: ./mcp-publisher publish

{sift_cli-1.0.2 → sift_cli-1.1.0}/.github/workflows/release.yml

@@ -23,8 +23,11 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python: ["3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: actions/checkout@v7
+      # Pinned to a full version, not a major alias: this action does not
+      # publish one. `@v10` resolves to nothing and every leg of CI fails
+      # before it runs a line -- which is how this was found.
+      - uses: astral-sh/setup-uv@v10.0.1
         with:
           enable-cache: true
       - name: Install
@@ -38,8 +41,8 @@ jobs:
     needs: check
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
 
       # The tag and the version in the package have to be the same thing. They
       # are written in two places by two people at two times, so they are
@@ -55,7 +58,7 @@ jobs:
       - name: Build
         run: uv build
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -70,7 +73,7 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

{sift_cli-1.0.2 → sift_cli-1.1.0}/.gitignore

@@ -6,5 +6,4 @@ __pycache__/
 dist/
 build/
 *.egg-info/
-uv.lock
 .mutating.json

sift_cli-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing
+
+The unusual things about this repository are worth knowing before you spend an
+hour on it. None of them are preferences; each one is there because something
+went wrong without it.
+
+## Two languages, on purpose
+
+**The notes are in Turkish. The code, the comments and the tests are in
+English.** `notlar/`, `tanitim/` and `gelistirme/` are written for the person
+whose project this is; everything a stranger reads while working — module
+docstrings, comments, test names, commit subjects' meaning — is in English.
+
+You do not need Turkish to contribute. Read `README.md` and the docstrings; they
+are the design document.
+
+## Three rules that do not bend
+
+Every change is measured against these. A pull request that improves something
+by weakening one of them will be declined, and the reason will be this list.
+
+1. **Nothing shown is invented.** The model returns line numbers. Text always
+   comes from the local file, byte for byte.
+2. **Nothing is thrown away.** `peek` returns the raw capture. Every gap says
+   how many lines it stands for.
+3. **Nothing can break the command.** No key, no network, a nonsense reply, a
+   bug in the distiller — each falls back to something that needs none of them.
+   The command still runs, and its exit code is still its own.
+
+## Every rule gets a mutation
+
+A green test suite says the tests did not object to this version of the code. It
+does not say they would object to a worse one. Twice in this project a test
+passed while proving nothing, and both times looked exactly like the tests
+around them.
+
+So `test/mutations.py` breaks each rule deliberately, one at a time, and the
+suite has to notice:
+
+```bash
+uv run python test/mutations.py                 # all of them, ~3.5 hours
+uv run python test/mutations.py "some words"    # only the rules that mention them
+```
+
+**A change that adds a rule adds a line there.** If your mutation escapes, the
+rule is unguarded — that is a finding, not a formality, and the fix is usually a
+test rather than an argument.
+
+Three times during this project the battery found that a *test* proved nothing:
+a command that finished before the thing being tested happened, a query that
+matched itself, an input too small to reach the branch. Expect it to find yours.
+
+If a rule cannot be broken from here — a Windows-only path, say — do not add a
+mutation that will escape every run. Say in a comment which leg of CI guards it.
+
+## Running things
+
+```bash
+uv sync --all-extras --dev
+uv run pytest -q                 # about a minute
+uv run ruff check .              # must be clean
+uv run python test/budget.py     # what a ceiling costs, against the corpus (spends requests)
+uv run python test/kazanc.py     # what a view saves, by the endpoint's own count
+```
+
+The suite reaches no network and finds no key: `test/conftest.py` moves `HOME`,
+deletes the key variables and sets `SIFT_NO_MODEL=1`. That is not tidiness —
+before it existed, tests were spending the developer's own quota and one of them
+swept the real capture store.
+
+The measurement scripts do spend requests, which is why they are scripts and not
+tests.
+
+## Numbers
+
+**Do not write a number you did not measure.** Not in the README, not in a
+comment, not in a note. Where a number appears, say what measured it: the
+endpoint's own token count, this tool's arithmetic over bytes it holds, a run of
+`test/budget.py` against the corpus.
+
+Bytes divided by four is not a token count. This tool is pointed at Japanese, at
+Turkish, at base64 and at stack traces, where that rule of thumb is wrong by a
+factor rather than a margin — and `stats` refuses it explicitly.
+
+## Commits and phases
+
+Work lands one phase at a time: code, tests, a mutation, a note in the matching
+folder, and one commit. A commit message here says *what was wrong and why the
+change is the answer* — not what the diff already shows.
+
+`notlar/` is the tool's own history, `tanitim/` is about being findable,
+`gelistirme/` is about being better. A phase that decided **not** to do
+something gets a note too, with the measurement that decided it.
+
+## Reporting
+
+Bugs and ideas: <https://github.com/slymnysr/sift/issues>.
+Anything security-shaped: `SECURITY.md`.

{sift_cli-1.0.2 → sift_cli-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sift-cli
-Version: 1.0.2
+Version: 1.1.0
 Summary: Runs your command, then gives the model only the lines that matter.
 Project-URL: Homepage, https://github.com/slymnysr/sift
 Author: slmnys
@@ -26,12 +26,20 @@ Runs your command, then gives the model only the lines that matter.
 
 A test suite prints 4,000 lines and eleven of them are the failure. A build
 prints a progress bar that redraws 900 times. An install lists every package it
-touched. All of it lands in the conversation, and — this is the part that costs
-— it is re-sent in full on every turn that follows.
+touched. All of it lands in the context window, and — this is the part that
+costs — it is re-sent in full on every turn that follows.
 
-`sift` runs the command itself, keeps every byte on disk, and hands the model a
-view: the failures, the summary, the lines a reader would actually stop on. The
-rest is marked, not deleted.
+`sift` is an MCP server and a command line for that problem. It runs the command
+itself, keeps every byte on disk, and hands the model a view: the failures, the
+summary, the lines a reader would actually stop on. The rest is marked, not
+deleted.
+
+Two numbers, both measured, both reproducible from this repository. Running this
+project's own test suite prints 652 lines — 21,392 tokens, as the model's own
+tokenizer counts them. What comes back is 8 lines and 208 tokens: **99% fewer**
+(`python test/kazanc.py`). Removing almost everything is the easy half. Over a
+22-sample corpus of real build and test output, the default budget keeps **138
+of the 140 lines a reader could not do without** (`python test/budget.py`).
 
 ```
 $ sift run -- pytest
@@ -135,6 +143,9 @@ is still shown to you in full**.
 Three switches:
 
 ```bash
+SIFT_MAX_CAPTURE=0  # keep everything a command writes, however much that is
+SIFT_BASE_URL=... # ask your own endpoint instead, and no key is wanted
+SIFT_MODELS=a,b   # which models to ask there, best first
 SIFT_NO_MODEL=1   # never send anything; use the deterministic view
 SIFT_MASK=0       # send unmasked
 SIFT_CACHE=0      # ask again, even about text already answered
@@ -163,6 +174,15 @@ Captured bytes never leave `$SIFT_HOME` (`~/.cache/sift` by default). Nothing is
 uploaded, nothing is logged elsewhere, and removing a capture directory removes
 everything that was ever kept about it.
 
+One capture keeps at most a gigabyte. That is far past any real build log and
+a few seconds of a command stuck in a loop, which is the case it exists for:
+nothing is thrown away, and the disk somebody else needs is not filled either.
+Reading never stops — a pipe nobody drains would stop the command, and that is
+the one thing this will not do — so the command finishes, its exit code is its
+own, and the footer says `kept the first 1,073,741,824 bytes of it` rather than
+letting you believe you have the whole run. `SIFT_MAX_CAPTURE=0` turns the
+ceiling off for anyone who would rather have the disk.
+
 They also never go away on their own. Nothing here sweeps, expires or tidies in
 the background: `sift gc [DAYS]` is the only thing that deletes a capture, and
 it deletes when you type it and not before. What it leaves is one line per
@@ -178,8 +198,8 @@ sift run [--timeout SECONDS] [--shell] [--background] [--cwd DIR]
 sift follow [HANDLE] [--all] [--wait N]
                           what a background run has said since you last looked
 sift stop [HANDLE]        end it, and everything it started
-sift outline PATH         what a file declares, without its bodies
-sift digest PATH...       what is in files somebody else produced
+sift outline PATH|-       what a file declares, without its bodies
+sift digest PATH...|-     what is in files somebody else produced
 sift peek HANDLE|PATH [FIRST] [LAST]
 sift hook                 answer one shell-command event on stdin
 sift mcp                  speak the protocol on stdin, for a client
@@ -191,6 +211,21 @@ sift stats [COUNT]        what the shortening cost, and what it saved
 sift gc [DAYS]            remove captures older than that, and say what went
 ```
 
+A path of `-` reads standard input, which is the other way somebody else's
+output turns up:
+
+```
+$ journalctl -u nginx --since yesterday | sift digest -
+Sep 08 04:11:07 nginx[2114]: worker process 2119 exited on signal 11
+─ 8,204 lines not shown · sift peek 7c1a04e9 for any of them ─
+Sep 09 01:02:55 nginx[2114]: signal 15 (SIGTERM) received, exiting
+```
+
+What arrives on a pipe has no path anybody could type again, so it is kept as a
+capture of its own and the gap marker names that instead. The second rule is
+why: a view that left lines out and pointed at a scratch file would be pointing
+at nothing by the time somebody read it.
+
 Several paths given to `digest` are asked about at the same time, and `--all`
 follows every running command in one go. Both are the same idea: the waiting is
 the cost, so do it once. `--wait N` holds until a run actually says something
@@ -229,10 +264,28 @@ slower, costs a request and is sometimes wrong. The model decides what cannot be
 computed, and nothing else.
 
 `sift stats` says what the shortening saved and what it cost, and keeps those
-two apart: the share is this tool's own arithmetic over bytes it holds, so it is
-exact, while the cost is the endpoint's count of its own tokens, so it is
-measured. A run the endpoint did not count is left out and said so, rather than
-filled in with bytes divided by four.
+apart because they are not the same kind of number. The share is this tool's own
+arithmetic over bytes it holds, so it is exact. The cost is the endpoint's count
+of its own tokens, so it is measured. And beside it now sits the number the
+question is really about — what the output weighed, counted by the same
+tokenizer at the moment it was sent:
+
+```
+$ sift stats
+handle    captured    shown  part  asks  weighed    cost  command
+9f2c41ab  62,003 B    450 B  0.7%     1   21,392   5,120  pytest -v
+
+1 run · 62,003 B captured · 450 B shown · 0.7% of it
+cost 5,120 tokens, as the endpoint counted them
+the output put to a model weighed 21,392 tokens -- numbering and question included
+```
+
+That last line is a little more than the capture alone, because the lines went
+out numbered with a question in front of them, and it says so rather than
+subtracting a guess. It also lets the report be unflattering: on a small
+command the asking costs more than the output ever weighed, and this is where
+you would see that. A run the endpoint did not count is a dash, left out of both
+totals rather than filled in with bytes divided by four.
 
 `--keep PATTERN` shows every line matching it whatever else was chosen and
 whatever the budget says. It is your pattern, not one this tool guessed at —
@@ -304,11 +357,15 @@ nothing there is this.
 
 Python 3.12 or newer, and no dependencies for the command line.
 
-### You need your own key
+### You need a model — a key, or one of your own
+
+`sift` asks a model which lines matter. There are two ways to give it one and
+you need exactly one of them.
 
-**This is not optional and it is not shipped.** `sift` asks a free NVIDIA model
-which lines matter, and that key has to be yours — one cannot be bundled and one
-cannot be shared. It is free, and it takes a minute:
+#### A free key
+
+**Not shipped, and not shareable.** The key has to be yours. It is free, and it
+takes a minute:
 
 1. Get a key at **<https://build.nvidia.com>**
 2. Put it anywhere `sift` looks:
@@ -319,7 +376,33 @@ export SIFT_API_KEY=nvapi-...            # or NVIDIA_API_KEY
 mkdir -p ~/.config/nvidia && echo 'nvapi-...' > ~/.config/nvidia/api_key
 ```
 
-Without it the two callers are answered differently, on purpose:
+#### Or a model of your own, and no key at all
+
+Point `sift` somewhere and it asks there instead. Nothing about the question
+changes; the endpoint is asked the ordinary OpenAI-shaped way, and no
+`Authorization` header is sent when there is no key to put in it.
+
+```bash
+export SIFT_BASE_URL=http://localhost:11434/v1   # Ollama
+export SIFT_MODELS=qwen3:8b                      # what to ask, best first
+```
+
+The same two lines fit llama.cpp (`--api`), vLLM, LM Studio, LocalAI, a company
+gateway, or any other endpoint that speaks `POST /v1/chat/completions`.
+`SIFT_MODELS` takes a comma-separated ladder and is asked in order.
+
+An address you typed is treated as a decision: nothing warns you about a missing
+key, and the MCP server does not decline. What that endpoint wants for
+credentials is between you and it.
+
+> Tested here as a shape rather than as a list: the suite proves that an
+> endpoint of your own is asked, and asked without a key. Which local servers
+> answer *well* is a question about the model you run, and the corpus in
+> `test/budget.py` is how you can settle it for yours.
+
+#### Without either of them
+
+The two callers are answered differently, on purpose:
 
 - **At a terminal** everything still runs — the command, the bytes, the exit
   code, the third rule — and a loud banner says no model chose these lines and
@@ -332,6 +415,12 @@ Without it the two callers are answered differently, on purpose:
 If you *want* to run without a model, say so with `SIFT_NO_MODEL=1`. That is a
 decision rather than an oversight, everything works, and nothing lectures you.
 
+## Contributing, and reporting something
+
+`CONTRIBUTING.md` is the map: two languages on purpose, three rules that do not
+bend, and a mutation for every rule. `SECURITY.md` says what runs, what leaves
+the machine, and where to send a finding privately.
+
 ## How it was built
 
 Twenty-four phases, each one closed before the next began, each with a note in

{sift_cli-1.0.2 → sift_cli-1.1.0}/README.md

@@ -6,12 +6,20 @@ Runs your command, then gives the model only the lines that matter.
 
 A test suite prints 4,000 lines and eleven of them are the failure. A build
 prints a progress bar that redraws 900 times. An install lists every package it
-touched. All of it lands in the conversation, and — this is the part that costs
-— it is re-sent in full on every turn that follows.
+touched. All of it lands in the context window, and — this is the part that
+costs — it is re-sent in full on every turn that follows.
 
-`sift` runs the command itself, keeps every byte on disk, and hands the model a
-view: the failures, the summary, the lines a reader would actually stop on. The
-rest is marked, not deleted.
+`sift` is an MCP server and a command line for that problem. It runs the command
+itself, keeps every byte on disk, and hands the model a view: the failures, the
+summary, the lines a reader would actually stop on. The rest is marked, not
+deleted.
+
+Two numbers, both measured, both reproducible from this repository. Running this
+project's own test suite prints 652 lines — 21,392 tokens, as the model's own
+tokenizer counts them. What comes back is 8 lines and 208 tokens: **99% fewer**
+(`python test/kazanc.py`). Removing almost everything is the easy half. Over a
+22-sample corpus of real build and test output, the default budget keeps **138
+of the 140 lines a reader could not do without** (`python test/budget.py`).
 
 ```
 $ sift run -- pytest
@@ -115,6 +123,9 @@ is still shown to you in full**.
 Three switches:
 
 ```bash
+SIFT_MAX_CAPTURE=0  # keep everything a command writes, however much that is
+SIFT_BASE_URL=... # ask your own endpoint instead, and no key is wanted
+SIFT_MODELS=a,b   # which models to ask there, best first
 SIFT_NO_MODEL=1   # never send anything; use the deterministic view
 SIFT_MASK=0       # send unmasked
 SIFT_CACHE=0      # ask again, even about text already answered
@@ -143,6 +154,15 @@ Captured bytes never leave `$SIFT_HOME` (`~/.cache/sift` by default). Nothing is
 uploaded, nothing is logged elsewhere, and removing a capture directory removes
 everything that was ever kept about it.
 
+One capture keeps at most a gigabyte. That is far past any real build log and
+a few seconds of a command stuck in a loop, which is the case it exists for:
+nothing is thrown away, and the disk somebody else needs is not filled either.
+Reading never stops — a pipe nobody drains would stop the command, and that is
+the one thing this will not do — so the command finishes, its exit code is its
+own, and the footer says `kept the first 1,073,741,824 bytes of it` rather than
+letting you believe you have the whole run. `SIFT_MAX_CAPTURE=0` turns the
+ceiling off for anyone who would rather have the disk.
+
 They also never go away on their own. Nothing here sweeps, expires or tidies in
 the background: `sift gc [DAYS]` is the only thing that deletes a capture, and
 it deletes when you type it and not before. What it leaves is one line per
@@ -158,8 +178,8 @@ sift run [--timeout SECONDS] [--shell] [--background] [--cwd DIR]
 sift follow [HANDLE] [--all] [--wait N]
                           what a background run has said since you last looked
 sift stop [HANDLE]        end it, and everything it started
-sift outline PATH         what a file declares, without its bodies
-sift digest PATH...       what is in files somebody else produced
+sift outline PATH|-       what a file declares, without its bodies
+sift digest PATH...|-     what is in files somebody else produced
 sift peek HANDLE|PATH [FIRST] [LAST]
 sift hook                 answer one shell-command event on stdin
 sift mcp                  speak the protocol on stdin, for a client
@@ -171,6 +191,21 @@ sift stats [COUNT]        what the shortening cost, and what it saved
 sift gc [DAYS]            remove captures older than that, and say what went
 ```
 
+A path of `-` reads standard input, which is the other way somebody else's
+output turns up:
+
+```
+$ journalctl -u nginx --since yesterday | sift digest -
+Sep 08 04:11:07 nginx[2114]: worker process 2119 exited on signal 11
+─ 8,204 lines not shown · sift peek 7c1a04e9 for any of them ─
+Sep 09 01:02:55 nginx[2114]: signal 15 (SIGTERM) received, exiting
+```
+
+What arrives on a pipe has no path anybody could type again, so it is kept as a
+capture of its own and the gap marker names that instead. The second rule is
+why: a view that left lines out and pointed at a scratch file would be pointing
+at nothing by the time somebody read it.
+
 Several paths given to `digest` are asked about at the same time, and `--all`
 follows every running command in one go. Both are the same idea: the waiting is
 the cost, so do it once. `--wait N` holds until a run actually says something
@@ -209,10 +244,28 @@ slower, costs a request and is sometimes wrong. The model decides what cannot be
 computed, and nothing else.
 
 `sift stats` says what the shortening saved and what it cost, and keeps those
-two apart: the share is this tool's own arithmetic over bytes it holds, so it is
-exact, while the cost is the endpoint's count of its own tokens, so it is
-measured. A run the endpoint did not count is left out and said so, rather than
-filled in with bytes divided by four.
+apart because they are not the same kind of number. The share is this tool's own
+arithmetic over bytes it holds, so it is exact. The cost is the endpoint's count
+of its own tokens, so it is measured. And beside it now sits the number the
+question is really about — what the output weighed, counted by the same
+tokenizer at the moment it was sent:
+
+```
+$ sift stats
+handle    captured    shown  part  asks  weighed    cost  command
+9f2c41ab  62,003 B    450 B  0.7%     1   21,392   5,120  pytest -v
+
+1 run · 62,003 B captured · 450 B shown · 0.7% of it
+cost 5,120 tokens, as the endpoint counted them
+the output put to a model weighed 21,392 tokens -- numbering and question included
+```
+
+That last line is a little more than the capture alone, because the lines went
+out numbered with a question in front of them, and it says so rather than
+subtracting a guess. It also lets the report be unflattering: on a small
+command the asking costs more than the output ever weighed, and this is where
+you would see that. A run the endpoint did not count is a dash, left out of both
+totals rather than filled in with bytes divided by four.
 
 `--keep PATTERN` shows every line matching it whatever else was chosen and
 whatever the budget says. It is your pattern, not one this tool guessed at —
@@ -284,11 +337,15 @@ nothing there is this.
 
 Python 3.12 or newer, and no dependencies for the command line.
 
-### You need your own key
+### You need a model — a key, or one of your own
+
+`sift` asks a model which lines matter. There are two ways to give it one and
+you need exactly one of them.
 
-**This is not optional and it is not shipped.** `sift` asks a free NVIDIA model
-which lines matter, and that key has to be yours — one cannot be bundled and one
-cannot be shared. It is free, and it takes a minute:
+#### A free key
+
+**Not shipped, and not shareable.** The key has to be yours. It is free, and it
+takes a minute:
 
 1. Get a key at **<https://build.nvidia.com>**
 2. Put it anywhere `sift` looks:
@@ -299,7 +356,33 @@ export SIFT_API_KEY=nvapi-...            # or NVIDIA_API_KEY
 mkdir -p ~/.config/nvidia && echo 'nvapi-...' > ~/.config/nvidia/api_key
 ```
 
-Without it the two callers are answered differently, on purpose:
+#### Or a model of your own, and no key at all
+
+Point `sift` somewhere and it asks there instead. Nothing about the question
+changes; the endpoint is asked the ordinary OpenAI-shaped way, and no
+`Authorization` header is sent when there is no key to put in it.
+
+```bash
+export SIFT_BASE_URL=http://localhost:11434/v1   # Ollama
+export SIFT_MODELS=qwen3:8b                      # what to ask, best first
+```
+
+The same two lines fit llama.cpp (`--api`), vLLM, LM Studio, LocalAI, a company
+gateway, or any other endpoint that speaks `POST /v1/chat/completions`.
+`SIFT_MODELS` takes a comma-separated ladder and is asked in order.
+
+An address you typed is treated as a decision: nothing warns you about a missing
+key, and the MCP server does not decline. What that endpoint wants for
+credentials is between you and it.
+
+> Tested here as a shape rather than as a list: the suite proves that an
+> endpoint of your own is asked, and asked without a key. Which local servers
+> answer *well* is a question about the model you run, and the corpus in
+> `test/budget.py` is how you can settle it for yours.
+
+#### Without either of them
+
+The two callers are answered differently, on purpose:
 
 - **At a terminal** everything still runs — the command, the bytes, the exit
   code, the third rule — and a loud banner says no model chose these lines and
@@ -312,6 +395,12 @@ Without it the two callers are answered differently, on purpose:
 If you *want* to run without a model, say so with `SIFT_NO_MODEL=1`. That is a
 decision rather than an oversight, everything works, and nothing lectures you.
 
+## Contributing, and reporting something
+
+`CONTRIBUTING.md` is the map: two languages on purpose, three rules that do not
+bend, and a mutation for every rule. `SECURITY.md` says what runs, what leaves
+the machine, and where to send a finding privately.
+
 ## How it was built
 
 Twenty-four phases, each one closed before the next began, each with a note in