# Fux

> Fux ranks a repository's documentation, decisions and runbooks from a small index committed to git, fetches the cited text from the system that owns it, and verifies freshness at answer time — deterministic, offline, $0, no model in the maintenance path. Agents reach it over MCP (`fux mcp`), editors over LSP (`fux lsp`), people over the CLI.

## Overview

- [Changelog](https://raw.githubusercontent.com/arpitarya/fux/main/CHANGELOG.md)
- [fux](https://raw.githubusercontent.com/arpitarya/fux/main/README.md)

## docs

- [Glossary](https://raw.githubusercontent.com/arpitarya/fux/main/docs/GLOSSARY.md): Recurring terms in the fux repo, defined once, alphabetical.
- [Fux docs — knowledge bundle root (v0.30 rebuild)](https://raw.githubusercontent.com/arpitarya/fux/main/docs/index.md)
- [The Fux Index: Index-and-Refer Retrieval over Git-Carried Knowledge](https://raw.githubusercontent.com/arpitarya/fux/main/docs/paper/the-fux-index-paper.md): The architecture of record, rewritten from the Standing Records and the measurement store as of 2026-09-14: a deterministic, stdlib-only BM25F index committed to git as canonical JSONL, content left in the systems that own it, freshness verified per answer, two readers (Python and Node) held byte-equal by test, and an evaluation discipline of pre-registered, paired, blind-or-informed runs. Every number is measured and names its run. Section 10 carries the open work; Section 9 carries what the v0.2 design proposed and did not ship.

## records

- [SR-LAWS (0001) — the laws have exactly one home, and records cite it](https://raw.githubusercontent.com/arpitarya/fux/main/records/0001_LAWS.md): The non-negotiable constraints are normative in CLAUDE.md only; this record names them L0-L13 so a decision can cite one without restating it.
- [SR-LAW-0 (0002) — L0 — SRs are the only source of truth, and the Law records outrank every other record](https://raw.githubusercontent.com/arpitarya/fux/main/records/0002_LAW-0-authority.md): The constitutional law. A rule is stated in exactly one SR and every other artifact links to it; the Law records outrank every other SR and a conflicting record is void in the conflicting part; a Law changes only on Arpit's ruling. Carries the describes/implements/enforces test that makes the source clause followable, and states plainly which half is gated and which is judgment.
- [SR-LAW-1 (0003) — L1 — a retired SR is archived, never deleted](https://raw.githubusercontent.com/arpitarya/fux/main/records/0003_LAW-1-retired-records-archived.md): A standing record whose law, rule or subject is retired is MOVED to archive/records/, mirroring its path, in the change that retires it — with a row in archive/README.md, status: archived and a dated banner. It may be named, never cited. Superseded records are out of scope and are still rewritten or deleted in place.
- [SR-LAW-2 (0004) — L2 — $0, FOSS-only](https://raw.githubusercontent.com/arpitarya/fux/main/records/0004_LAW-2-zero-cost.md): Why fux costs nothing and depends on nothing anyone must buy; and the 2026-09-06 amendment that withdrew the zero-dependency guarantee while hardening the money clause.
- [SR-LAW-3 (0005) — L3 — content is never durable outside its source system](https://raw.githubusercontent.com/arpitarya/fux/main/records/0005_LAW-3-content-never-durable.md): The law the whole architecture rests on: the index holds statistics, never content, so nothing fux commits can leak a document a reader was not entitled to.
- [SR-LAW-4 (0006) — L4 — deterministic; no model in the maintenance path](https://raw.githubusercontent.com/arpitarya/fux/main/records/0006_LAW-4-deterministic.md): Same sources, byte-identical index and root hash. No model runs in maintenance — not to be smarter at ingest, not to summarize, not once — and since L2's amendment this law stands alone.
- [SR-LAW-5 (0007) — L5 — offline by default](https://raw.githubusercontent.com/arpitarya/fux/main/records/0007_LAW-5-offline-by-default.md): Network access only inside explicit, fenced, opt-in paths — paths, plural. An import fence enforces it, and the count of fenced paths was never part of the law.
- [SR-LAW-6 (0008) — L6 — say "index", not "db"](https://raw.githubusercontent.com/arpitarya/fux/main/records/0008_LAW-6-say-index.md): Load-bearing vocabulary, ruled by council: what fux commits is statistics that make documents findable, and calling it a database invites every expectation the architecture refuses.
- [SR-LAW-7 (0009) — L7 — Python ≥ 3.12](https://raw.githubusercontent.com/arpitarya/fux/main/records/0009_LAW-7-python-312.md): The floor that makes the other laws affordable: tomllib in the stdlib, modern typing, exception groups, and since 2026-09-28 the 3.12 typing and stdlib additions — each one a dependency not taken. L8 is its Node twin.
- [SR-LAW-8 (0010) — L8 — Node ≥ 22](https://raw.githubusercontent.com/arpitarya/fux/main/records/0010_LAW-8-node-22.md): The Node read plane's floor, the twin of L7: every published Node artefact declares engines node >=22, because Node 20 reached end of life on 2026-04-30 and 22 is the oldest line still supported.
- [SR-LAW-9 (0011) — L9 — a use record is never committed](https://raw.githubusercontent.com/arpitarya/fux/main/records/0011_LAW-9-use-record.md): The only law about USE rather than about the corpus. Written, reverted and re-narrowed in a single day; what survives is one test — will this end up in a commit?
- [SR-LAW-10 (0012) — L10 — the consumer is served build output, never source](https://raw.githubusercontent.com/arpitarya/fux/main/records/0012_LAW-10-bundled-output.md): What fux puts in front of a consumer — vendored into their repository or exposed as a published package's entry point — is a generated bundle, one artefact per plane. Decoders, fetchers and observers are the only exceptions, because there readable source IS the contract.
- [SR-LAW-11 (0013) — L11 — the golden answer key is Arpit's custody, and no agent may read one](https://raw.githubusercontent.com/arpitarya/fux/main/records/0013_LAW-11-sealed-answer-key.md): Every answer set — Claude's set 2 and set 3, Codex's set 1 — is Arpit's custody. Since 2026-09-18 a key MAY exist at one address, `work/golden/golden-answers/`, gitignored and closed to every agent on both spellings; the one route an answer travels is Arpit pasting it into a chat, and that route is Codex's alone. Claude is closed on every route, a paste included, with two carve-outs: authoring an agent-authored set, per set; and, since 2026-09-21, a named scoring program Arpit runs from his own shell, which no agent invokes and for which no guard moves. A breach does not fail loudly because a contaminated benchmark number looks exactly like a clean one.
- [SR-LAW-12 (0014) — L12 — every value lives in a config file, never in code](https://raw.githubusercontent.com/arpitarya/fux/main/records/0014_LAW-12-values-live-in-config.md): No function, module constant or parameter default in fux's engine holds a value. A tunable value is read from a committed TOML file (fux.toml, .fux/tune.toml or another .fux/*.toml); a fixed engine value is read from one internal constants file shipped with the engine. Python and Node read the same key from the same file, and a missing file or key is a hard error that names it. Setup and its templates, tests, tools and scripts are the only places a literal value may sit.
- [SR-LAW-13 (0015) — L13 — a ranking change ships only through the standing bar](https://raw.githubusercontent.com/arpitarya/fux/main/records/0015_LAW-13-the-standing-bar.md): One bar for every change meant to improve what fux ranks. The shape is fixed — gates, the change clearly helps the questions it targets, limited collateral on every other question, a net-positive whole set, and guardrails — and each pre-registration fills in only its parameters. One arm is decided, named before any number; a set already used to decide a mechanism may report another, never decide it. Tightening is free; loosening needs Arpit's ruling.
- [SR-WORK-OPEN-QUEUE (0051) — how OPEN-WORK works](https://raw.githubusercontent.com/arpitarya/fux/main/records/0051_WORK-open-queue.md): The live queue's discipline has one home, and this is it. Sixty-four rules across ten groups — what the file is, an item's lifecycle, the shape of a row, the four balls, ordering, the Blocked-on-Arpit inbox, the standing obligations, how an item is closed: archived, never deleted — how an item's file opens: with a table or diagram fit to show in a meeting — and who filed and last updated each item. OPEN-WORK.md is the list and nothing else; it and CLAUDE.md reference this record and state no rule themselves.
- [SR-WORK-ENVIRONMENTS (0052) — each sibling environment has one job](https://raw.githubusercontent.com/arpitarya/fux/main/records/0052_WORK-environments.md): Which of the three sibling directories may do what. The playground is Arpit's hands only; the lab runs every measurement on golden test data up to 10 000 documents; the benchmark compares two fux versions on its own corpora, capturing what SR-WORK-BENCHMARK says it captures. Why the three were separated, what it voids, and what would reopen it.
- [SR-WORK-BENCHMARK (0053) — what every benchmark run captures](https://raw.githubusercontent.com/arpitarya/fux/main/records/0053_WORK-benchmark.md): The seven things a benchmark run always files: the ranked lists, what moved between the two arms, hit@k at 1/5/10/20/50, the answer layer including the planted unanswerables, the committed index size, the speed, and an HTML report whose spine is one slide per capture, titled by its CAP id and comparing the two arms. Per query and per arm, never as a total. Halt gates are functionality and are not captured here.
- [SR-WORK-OWNERSHIP (0054) — owns and describes: the record-to-component model](https://raw.githubusercontent.com/arpitarya/fux/main/records/0054_WORK-ownership.md): Two relations, not one. Exactly one record OWNS each component; any number DESCRIBE it. The freshness gate demands the owner and every describer, which closes the hole that let sixteen records rot while the check stayed green. Since 2026-09-13 a record also declares its `kind`, which selects an additional gate and never switches one off.
- [SR-WORK-BACKLOG (0055) — how BACKLOG.md works](https://raw.githubusercontent.com/arpitarya/fux/main/records/0055_WORK-backlog.md): The second work file, and the last one: everything this repo has named as outstanding and nobody is doing. Thirty-one rules across six groups — what the file is, what feeds it, the shape of a row, the five classes, how an item leaves, and the one obligation it puts on every session. BACKLOG.md is the list and nothing else.
- [SR-WORK-QUALITY (0056) — what "good" means: the four-gate funnel, the declared mix, and the published cost of an error](https://raw.githubusercontent.com/arpitarya/fux/main/records/0056_WORK-quality.md): Fux measured rigorously for months and never wrote down what it was measuring. This record declares the quantity: a four-gate funnel with recall@k as the headline, a versioned query mix, unanswerable queries inside the gate, and a published confidence target that fixes the cost of a wrong citation before any score exists.
- [SR-WORK-SCALE (0057) — the 10 000-document ceiling](https://raw.githubusercontent.com/arpitarya/fux/main/records/0057_WORK-scale.md): Fux is built, measured and judged at 10 000 documents, and since 2026-08-22 that number is a ceiling on MEASUREMENT and on COMMITMENT, never on the design's reach. Above it: no threshold, budget, bound, veto, pre-registration or verdict, and no work blocked on one. Descriptions of how the design behaves at 10^5 stay and are not stale.
- [SR-WORK-LIFECYCLE (0058) — how a feature travels from fork to record](https://raw.githubusercontent.com/arpitarya/fux/main/records/0058_WORK-lifecycle.md): The five stages every non-trivial feature moves through — compare doc on a fork, proposal doc on a parked idea, the plan, the handoff in the item's own file, the paste-ready prompt — and the record that closes it. Every handoff and prompt names the model that should execute it, because an under-powered model does not error, it returns confident wrong work.
- [SR-WORK-DOCS (0059) — documentation style, discipline, and what every task owes the docs](https://raw.githubusercontent.com/arpitarya/fux/main/records/0059_WORK-docs.md): Three rules with one home: how a doc is written (short points, takeaway first, no walls of text), who may edit the agent-steering files and under what two obligations, and the seven documents a task updates before it is done. The registry lists live documents only, one row each, every target existing.
- [SR-WORK-SESSION (0060) — what a session owes before it ends](https://raw.githubusercontent.com/arpitarya/fux/main/records/0060_WORK-session.md): Three files every session touches — the append-only worklog, the interview kept current DURING the work, and the milestone log a row is earned into by landing — plus the one-line pointer a dying session leaves behind, the transition markers, the ten-line answer, and the two hazards that bite silently when two sessions share a machine.
- [SR-WORK-OKF (0061) — the repo is an OKF knowledge bundle](https://raw.githubusercontent.com/arpitarya/fux/main/records/0061_WORK-okf.md): Fux's documentation follows Google's Open Knowledge Format v0.1: the bundle is docs/ + records/ + work/, rooted at docs/index.md, and every knowledge document in it carries a non-empty type. The ALL-CAPS exemption was retired 2026-09-12 because the spec never had one and 94 of 314 files failed a bar the repo was claiming.
- [SR-WORK-ARCHIVE (0062) — one archive, and archive is not evidence](https://raw.githubusercontent.com/arpitarya/fux/main/records/0062_WORK-archive.md): There is exactly one archive, at the repo root, and anything retired moves there mirroring where it came from with a row naming its live successor. An archived doc may be NAMED but never CITED as backing a live claim, because nothing guarantees it was not overwritten after retirement. Records split by law L1: a RETIRED record is archived like any document; a SUPERSEDED record is rewritten or deleted in place.
- [SR-WORK-RELEASE (0063) — one name in two registries, and what actually blocks a merge](https://raw.githubusercontent.com/arpitarya/fux/main/records/0063_WORK-release.md): fux-engine ships to PyPI and npm from one release trigger — PyPI automatically by OIDC, npm staged for a human to approve — and the version has four hand-written sites plus one derived bundle, held equal by check-version-parity.py. main has no required status checks: history is protected, the quality gate is not, so CI green is the author's to read.
- [SR-WORK-BLOCKERS (0064) — a blocker is a file, not a remark](https://raw.githubusercontent.com/arpitarya/fux/main/records/0064_WORK-blockers.md): The moment a session cannot proceed without Arpit it writes work/BLOCKED.json and stops. Four decision values, one of which is PROCEED; no working around a blocker by picking a plausible default; and three hooks that enforce it rather than trusting anyone to remember — the inbox injection, the Stop refusal, and a per-asset write lock.
- [SR-WORK-GOVERNANCE (0065) — the governance map: what governs what, who reads it, what enforces it](https://raw.githubusercontent.com/arpitarya/fux/main/records/0065_WORK-governance.md): One map of every file that governs how this repo is worked on — the four layers (root steering, work/, docs/ + records/, archive/), each entry's audience, enforcement and update trigger. The map names homes and restates no rule that has one, and it carries NO counts: a count in prose is a fact with an expiry date, and this map's counts expired twice.
- [SR-WORK-GOLDEN (0066) — the two golden question sets, the key's custody, and what Claude may read instead](https://raw.githubusercontent.com/arpitarya/fux/main/records/0066_WORK-golden.md): The prohibition is law L11 and this record states none of it; what it holds is the process around it — the three question sets, Arpit's custody of every answer half, the one permitted key directory and the guards that defend it, the SWITCH that opens and closes it (`just golden-unlock` / `golden-lock` / `golden-retire`, mechanics in decision 15; the paste route retired 2026-09-21), what Claude may read, and the bind that keeps CLAUDE.md's view legal.
- [SR-WORK-REGISTRY (0067) — the doc registry: the rules AND the table — live documents only, a trigger and a date per row, bumped in the same change](https://raw.githubusercontent.com/arpitarya/fux/main/records/0067_WORK-registry.md): The doc registry, whole — the rules in §2 and the per-document table in §3. The trigger + last-verified contract, live documents only, the three mechanical consequences (no row into archive/, every target exists, one row per document), the same-change bump, and what the test enforces. work/DOC-REGISTRY.md is retired; this record is the registry.
- [SR-WORK-TESTDATA (0068) — the source of what test data must carry and how it is authored: checklist T, authoring rules A, feature recipes R; prompts are disposable copies](https://raw.githubusercontent.com/arpitarya/fux/main/records/0068_WORK-test-data.md): The one maintained source for golden test data — what every seed document, question set and rung must carry (T1–T14), how it is authored (A1–A24), and the input each ranking feature needs (R1–R10). Prompts are written from it when new data is needed, link it, and are deleted once their data lands.
- [SR-CLI (0101) — the command-line surface](https://raw.githubusercontent.com/arpitarya/fux/main/records/0101_cli-surface.md): Flat verbs in seven groups, one error boundary, three output modes. Freezes the CLI contract with a captured transcript of every command and its real output.
- [SR-DOTFUX (0102) — the .fux/ directory](https://raw.githubusercontent.com/arpitarya/fux/main/records/0102_fux-directory.md): Every child of .fux/ is declared committed, derived or acquired; the ignore rule is narrow by construction and asserted by doctor against git itself.
- [SR-ASK (0103) — the ask verb](https://raw.githubusercontent.com/arpitarya/fux/main/records/0103_ask.md): The agent-facing default. One scorer, one sort, shared by both candidate generators; the path that answers can never change the answer.
- [SR-FIND (0104) — the find verb](https://raw.githubusercontent.com/arpitarya/fux/main/records/0104_find.md): One line per hit, for pipes. The same ranking as ask projected to locations, plus three filters that only ever remove rows the ranking already produced.
- [SR-ANSWER (0105) — the answer verb](https://raw.githubusercontent.com/arpitarya/fux/main/records/0105_answer.md): The single best answer the index can give — a fetched, re-scored passage with a fresh sha, or the index's own structure when the source is unreachable. No model, ever, on this path.
- [SR-INGEST (0106) — how ingest works](https://raw.githubusercontent.com/arpitarya/fux/main/records/0106_ingest.md): Re-resolve every edge every run; carry unchanged documents' extraction forward. Write only shards whose bytes changed. Skips are reported once, counted by class, and recorded in the committed `.fux/.fuxignore`; deletions honoured, output byte-identical.
- [SR-URL-INGEST (0107) — URL ingestion through a consumer-owned fetcher](https://raw.githubusercontent.com/arpitarya/fux/main/records/0107_url-ingest.md): Fux never fetches. A consumer-owned file does, only under the two named fenced paths; a failed fetch is a skip and never a deletion, and what comes back is normalized.
- [SR-INDEX-LIFECYCLE (0108) — how the index is generated and updated](https://raw.githubusercontent.com/arpitarya/fux/main/records/0108_index-lifecycle.md): One canonical encoder, sharded doc-major JSONL, write-if-different; a derived accelerator bound by the differential law and detected stale by per-shard shas.
- [SR-RECORD (0109) — one line of the committed index, property by property](https://raw.githubusercontent.com/arpitarya/fux/main/records/0109_index-record.md): What every property of a committed JSONL record is for, why it is in the committed plane at all, and the ones that are conditional.
- [SR-T1-ACCELERATOR (0110) — the derived T1 accelerator](https://raw.githubusercontent.com/arpitarya/fux/main/records/0110_accelerator.md): A disposable term-major index under .fux/runtime/ that makes warm queries fast and is forbidden from changing an answer. Candidates and statistics only, never scores.
- [SR-RANKING (0111) — how documents are scored and ordered](https://raw.githubusercontent.com/arpitarya/fux/main/records/0111_ranking.md): BM25F over five fields, weight-then-saturate once, with one scorer and one sort shared by both query paths, and a rounded, id-tie-broken order.
- [SR-POSTINGS (0112) — the postings, committed and derived](https://raw.githubusercontent.com/arpitarya/fux/main/records/0112_postings.md): The same information in two shapes — doc-major in git for diffs and merges, term-major in the runtime plane for queries — and the rule that keeps them equal.
- [SR-CONFIG (0113) — fux.toml and every property in it](https://raw.githubusercontent.com/arpitarya/fux/main/records/0113_config.md): A deliberately tiny config: what each key does, why the surface is three tables, why three more are refused by name, and why one table is passed through unread.
- [SR-PORT-LIST (0114) — port, don't rewrite, and this is the complete list](https://raw.githubusercontent.com/arpitarya/fux/main/records/0114_port-list.md): Named modules come forward from the archived engine, each with its tests, when its milestone needs them. Nothing else does, and the list is closed.
- [SR-EXTRACTED (0115) — the extracted ingest mode](https://raw.githubusercontent.com/arpitarya/fux/main/records/0115_extracted-mode.md): The deterministic ingest mode, ratified by name. Everything is taken from the document; nothing is invented; every guarantee in the paper is stated for this mode and no other.
- [SR-URL-LIST (0116) — the committed URL list](https://raw.githubusercontent.com/arpitarya/fux/main/records/0116_url-list.md): One URL per line in a committed file, deduped and sorted by the loader, so config order can never change committed bytes and thousands of entries diff and merge line by line.
- [SR-FETCHER (0117) — the consumer-owned fetcher](https://raw.githubusercontent.com/arpitarya/fux/main/records/0117_fetcher.md): Fux never fetches; a consumer-owned fetcher file does. One fetcher per URL, declared not detected, returning bytes and a Content-Type — and the word is fetcher because nothing here composes.
- [SR-CDP-FETCHER (0118) — the CDP fetcher](https://raw.githubusercontent.com/arpitarya/fux/main/records/0118_cdp-fetcher.md): The browser fetcher, for documents a plain GET cannot read. Drives your existing signed-in Chrome over CDP and returns the RESOURCE the server sent — intercepted, never rendered; declared per URL, never escalated to.
- [SR-HTTP-FETCHER (0119) — the default HTTP fetcher](https://raw.githubusercontent.com/arpitarya/fux/main/records/0119_http-fetcher.md): A plain stdlib GET is the default fetcher, written write-if-missing into the consumer's repo by fux setup so core still holds zero network lines — and it never escalates.
- [SR-DIR-LIST (0120) — the committed directory list](https://raw.githubusercontent.com/arpitarya/fux/main/records/0120_dir-list.md): Source directories live in a line-oriented committed file on the URL list's grammar, with `!` subtraction. A directory may be declared archived=true — a declaration, never derived from a path.
- [SR-CACHEDIR-TAG (0121) — CACHEDIR.TAG marks a derived directory disposable](https://raw.githubusercontent.com/arpitarya/fux/main/records/0121_cachedir-tag.md): A cache-directory tag written once into every derived .fux/ directory, per the bford.info/cachedir spec, so backup and archive tools skip it without Fux-specific configuration.
- [SR-DOCS-TABLE (0122) — docs.jsonl, the docidx-ordered doc table](https://raw.githubusercontent.com/arpitarya/fux/main/records/0122_docs-table.md): One JSON line per document, sorted by id, so its position (docidx) is a stable, small join key every other derived structure references instead of repeating the string id.
- [SR-RUNTIME-MANIFEST (0123) — manifest.json, the accelerator's staleness fingerprint](https://raw.githubusercontent.com/arpitarya/fux/main/records/0123_runtime-manifest.md): A per-shard content-sha map plus schema, counts and the doc-table field set, so a reader can prove the derived plane still matches the committed index and localize exactly which shard drifted when it does not.
- [SR-RUNTIME-STAMP (0124) — stamp.json, the cheap pre-check ahead of the manifest](https://raw.githubusercontent.com/arpitarya/fux/main/records/0124_runtime-stamp.md): A deliberately non-reproducible per-shard size/mtime snapshot that short-circuits manifest.json's content-hash check on the common unchanged case, and is never itself proof of freshness.
- [SR-RUNTIME-STATS (0125) — stats.json, the corpus-wide numbers BM25F needs](https://raw.githubusercontent.com/arpitarya/fux/main/records/0125_runtime-stats.md): n and the RAW per-field token-count totals — computed once at build time so length normalisation is an O(1) lookup, and stored unweighted so a field weight cannot bake into the plane. newest_mtime was the third field and left with the recency prior on 2026-09-13.
- [SR-GRAPH (0126) — the graph lane: communities, PPR-lite, and three relational verbs](https://raw.githubusercontent.com/arpitarya/fux/main/records/0126_graph.md): The ref/tag/code edges ingest already extracts become a queryable lane — explain, graph, path — with an unseeded, deterministic community assignment in a derived plane.
- [SR-REFER (0127) — the refer plane: fetch from the source, verify by content, assemble under a byte budget](https://raw.githubusercontent.com/arpitarya/fux/main/records/0127_refer-plane.md): Fux still does not fetch — the refer plane reuses the consumer-fetcher contract. Freshness is verified by content sha rather than by age. The answer limit is a byte budget, not k.
- [SR-TYPES (0128) — which files are documents, and which metadata keys are searchable: a built-in allowlist, overridable by .fux/formats.toml and by .fuxignore](https://raw.githubusercontent.com/arpitarya/fux/main/records/0128_types-list.md): Prose plus every format a built-in decoder reads is compiled in as an allowlist; a committed types file replaces it, and .fux/.fuxignore outranks it in both directions. The file is required since W-225 stage 4a, written with that default spelled out; it never means everything and never nothing.
- [SR-MAINTENANCE (0129) — the git hooks that keep a committed index in step, the write lock, and the daemon](https://raw.githubusercontent.com/arpitarya/fux/main/records/0129_hooks.md): post-commit DEFERS — it writes a dirty list and spawns a detached one-shot re-index; post-merge re-ingests, post-checkout only rebuilds; no hook ever touches the network; every index writer holds one lock; and a resident daemon covers the URLs nobody queries.
- [SR-MERGE-DRIVER (0130) — the committed index merges line by line, last-writer-wins on (ver, sha), and refuses rather than guesses](https://raw.githubusercontent.com/arpitarya/fux/main/records/0130_merge-driver.md): The merge driver for .fux/index/*.jsonl. A shard is a header plus one JSON line per document sorted by id, so the union of two line sets is usually the right answer and a textual merge cannot see it. Higher ver wins; four cases are refused with ordinary conflict markers; the output is sorted so two machines produce the same bytes.
- [SR-CACHE (0131) — two caches, two different proofs: ARC decides what a fetch returned, the TTL store decides whether to fetch at all](https://raw.githubusercontent.com/arpitarya/fux/main/records/0131_cache.md): The refer plane's caching, carved out of SR-REFER. ARC is keyed by content address so a hit is byte-identical to a fetch or it is not a hit; the TTL fetch cache is served before any sha is confirmed and therefore lives in its own store, is opt-in, is bounded on disk, and labels its answers `cached` rather than `current`.
- [SR-AGENT-POLICY (0132) — Fux ships the policy its consumers need to read it correctly](https://raw.githubusercontent.com/arpitarya/fux/main/records/0132_agent-policy.md): Fux's readers are AI agents, and an engine whose output is misread is an engine that does not work. Fux emits intent-neutral facts and ships one canonical policy rendered into each agent's native format, installed by fux setup from a declaration, never from detection, and never clobbering a file the consumer owns.
- [SR-RS (0133) — the R predictions: what a frozen claim is, and the four ways one can end](https://raw.githubusercontent.com/arpitarya/fux/main/records/0133_predictions.md): An R is a claim frozen before measurement; its threshold may never move; its verdict is never edited; an ambiguous result goes to Arpit rather than to whoever ran it; and it ends in exactly four ways — PASS, FAIL, INCONCLUSIVE, RETIRED — of which FAIL is a success and RETIRED is not a failure. Every measured run is blind or informed, and an informed run is reclassified rather than banned.
- [SR-ARCHIVED-CONTENT (0134) — what a document declared archived does, once it is indexed](https://raw.githubusercontent.com/arpitarya/fux/main/records/0134_archived-content.md): A document from a source declared archived=true carries archived: true; ranking is byte-identical at the default weight; a configurable weight may demote it; every verb surfaces the fact; and a response-level disclaimer states what archived means without telling the reader what to conclude.
- [SR-TUNE (0135) — the tunables file, and per-source priority](https://raw.githubusercontent.com/arpitarya/fux/main/records/0135_tuning.md): `.fux/tune.toml` — a committed, setup-written, never-rewritten file holding every knob that changes ordering, plus one declared exception (`[index]`: `max_phrases`, `max_table_rows`) that changes the index; plus a per-source preference weight in either direction, where fux states the cost and refuses only what is broken.
- [SR-MCP (0136) — the MCP server, and a tool surface deliberately smaller than the CLI](https://raw.githubusercontent.com/arpitarya/fux/main/records/0136_mcp.md): `fux mcp` serves the index to coding agents over stdio JSON-RPC, stdlib-only, as three tools rather than the whole verb surface — and does not expose `answer`, because the agent is the answerer.
- [SR-ENRICH (0137) — enrichment as an agent skill, not an API call](https://raw.githubusercontent.com/arpitarya/fux/main/records/0137_enrich.md): `fux enrich` plans and validates; a coding agent generates. Fux never calls a model, so L2, L5 and the $0 law are held rather than bracketed — and partial coverage is designed for, because sha-keying makes it the steady state. SUPERSEDES SR-ENRICHED (2026-08-27, W-82 ruling 6): the `enriched` mode taxonomy, its L4 fence, provenance pinning and below-deterministic grading are folded in verbatim, and that mode is still NOT authorized to be built.
- [SR-RERANK (0138) — proximity reranking, and the cross-encoder that was refused](https://raw.githubusercontent.com/arpitarya/fux/main/records/0138_rerank.md): BM25F is a bag of words and cannot see where terms are. The reranker adds coverage, minimum span and adjacency over the refer plane's own passages, in stdlib arithmetic. A cross-encoder is refused on cross-machine determinism, not on cost. Measured 28 -> 32 of 50 goldens, 4 fixed / 0 broken, +8 ms p95 at 10 000 documents.
- [SR-DECODE (0139) — the decoder plane: bytes become Markdown in one place, and a consumer may bring a dependency fux may not](https://raw.githubusercontent.com/arpitarya/fux/main/records/0139_decode.md): Decoding gets one home, one protocol, and a consumer seam where third-party libraries are legal — declared, so a machine that cannot satisfy the declaration fails instead of committing a smaller index.
- [SR-LOCKS (0140) — the one lock fux owns, and the three files beside it that are not locks](https://raw.githubusercontent.com/arpitarya/fux/main/records/0140_locks.md): Fux holds exactly one mutex over the committed index: `.fux/runtime/write.lock`, a pid created with O_CREAT+O_EXCL in the gitignored derived plane. Every command that writes the index holds it and every read verb holds nothing. This record states the mechanism, the two-caller asymmetry, the cooperative stop that releases it, and the three sibling files — `runner.stop`, `daemon.stop`, `daemon.pid` — that are constantly mistaken for locks.
- [SR-CONFIDENCE (0141) — how much the index believes its own answer](https://raw.githubusercontent.com/arpitarya/fux/main/records/0141_confidence.md): Four deterministic signals and one band, emitted with every answer, so a consuming agent can tell a grounded result from the closest thing in a corpus that never discusses the question. Since 2026-09-22 the band REPORTS and only `none` refuses.
- [SR-PROVENANCE (0142) — fux does not keep an audit trail; it makes one derivable](https://raw.githubusercontent.com/arpitarya/fux/main/records/0142_provenance.md): How the returned output got generated — a derivation on `ask --why`, a re-runnable receipt on `answer --receipt`, and `fux verify`'s four-state verdict.
- [SR-OUTPUT (0143) — output defaults are configurable, in a third file](https://raw.githubusercontent.com/arpitarya/fux/main/records/0143_output-defaults.md): `.fux/output.toml` sets the default SHAPE of every verb's output — and of the MCP surface, which has no flags at all. A third file because it has a third boundary: it changes how a result is shown, never which documents come back.
- [SR-FUXIGNORE (0144) — .fux/.fuxignore: one file for what is not indexed, in .gitignore's grammar](https://raw.githubusercontent.com/arpitarya/fux/main/records/0144_fuxignore.md): Exclusion moves out of the source lists into one .gitignore-shaped file that is read first and decides in both directions, including over the type allowlist. `fux ingest` writes the skip list into two delimited blocks at its top.
- [SR-ACQUIRED (0145) — retained source bytes](https://raw.githubusercontent.com/arpitarya/fux/main/records/0145_acquired-plane.md): Fetched source bytes are retained in .fux/acquired/, a third category beside committed and derived: gitignored, and not rebuildable.
- [SR-REFUSAL (0146) — the response the server sent instead of the document](https://raw.githubusercontent.com/arpitarya/fux/main/records/0146_refusals.md): A declarative refusal table, every condition pure over the response bytes, plus an always-on magic-byte floor fux owns and no consumer can switch off.
- [SR-URL-FRESHNESS (0147) — six verdicts, and a per-URL ttl that can only narrow](https://raw.githubusercontent.com/arpitarya/fux/main/records/0147_url-freshness.md): How fresh a url: citation is, said in six positions that never collapse into each other; and ttl= as a per-URL bound that narrows the caller's policy and can never widen it.
- [SR-PII (0148) — redact what gets committed, leave alone what stays local](https://raw.githubusercontent.com/arpitarya/fux/main/records/0148_pii.md): A consumer-owned .fux/pii.toml redacts the committed index and nothing else; the sha is computed before redaction so refer keeps working, and editing the ruleset invalidates extraction reuse; a rule may name a checksum (luhn, verhoeff) its value must pass; fux setup writes the file and every command refuses to run without it.
- [SR-EXPAND (0149) — the caller supplies the vocabulary, and fuses its own phrasings](https://raw.githubusercontent.com/arpitarya/fux/main/records/0149_expand.md): `--expand` scores agent-supplied terms at a lower weight beside the user's own, and `-q` fuses several phrasings in rank space by RRF; a document matching only supplied terms is never returned.
- [SR-TABULAR (0150) — a table is a list of rows, and a row is the unit of an answer](https://raw.githubusercontent.com/arpitarya/fux/main/records/0150_tabular.md): How .csv, .tsv, .xlsx and .xlsm are read and cited: one passage per row, how much of a table is admitted, and the two silent data losses this record was written to close.
- [SR-CHUNKING (0151) — a chunk does three jobs, and one span cannot do all of them well](https://raw.githubusercontent.com/arpitarya/fux/main/records/0151_chunking.md): What a passage is: the one fold rule that derives every unit from heading depth with nothing declared, the boundary ladder that guarantees every document is quotable, and why the popular hierarchical answers were rejected on their own documented trade-offs.
- [SR-DOCTOR (0152) — what `fux doctor` checks, and why each row is a warning or an error](https://raw.githubusercontent.com/arpitarya/fux/main/records/0152_doctor.md): One record owns the health-check surface. Every check names a cause and never repairs it; warn is the default and error is reserved for a repo a verb will refuse; a check that degrades to `skipped` must name the row that does fail.
- [SR-NODE-SEARCH (0153) — the Node read plane: one index, two readers, three arms](https://raw.githubusercontent.com/arpitarya/fux/main/records/0153_node-search.md): Why a Node reader exists, what it may and may not do, and the decisions that keep it from becoming a second product: the _format version policy, the never-fetch rule, the url: verdict asymmetry, the shared tool-description file, and the three places where Node is deliberately a SUBSET of Python rather than a copy — the derived graph plane, the accelerator label, and the decoder boundary. Decisions 13-16 carry the SHIPPING shape, ruled AND BUILT on 2026-09-12: the consumer gets a published artefact rather than source, the bundle is built at publish time into both registries, a monorepo is auto-detected and wired up, and the .fux/fux shim resolves the binary across five package managers.
- [SR-API (0154) — `fux.api`, the importable read surface and what it costs to have one](https://raw.githubusercontent.com/arpitarya/fux/main/records/0154_api.md): Why the CLI stopped being the only contract, what the library may and may not do, and the one thing that makes this worth a frozen surface: one schema for three readers.
- [SR-AGENT-SURFACES (0155) — what an agent surface is, and the five that do not instruct](https://raw.githubusercontent.com/arpitarya/fux/main/records/0155_agent-surfaces.md): The repo shipped agent-facing files in five document kinds — skills, steering, rules, instructions, agents — and had no word for the set, calling them 'agent-steering files' in CLAUDE.md and 'vendor surfaces' in SR-AGENT-POLICY. They are AGENT SURFACES. The taxonomy splits them by what they DO: instructing surfaces carry prose an agent may or may not load; acting surfaces fire on a tool call, gate a permission, are invoked by name, run as a scoped agent, or shape a reply. Five acting surfaces ship, Claude-only. A surface the consumer co-owns is seeded, never overwritten, and cannot be byte-pinned.
- [SR-INSPECT (0156) — `fux inspect`, the index X-ray: six lenses, three flagged checks, a local dictionary that names the hashes, and per-document facts, probes and a diff](https://raw.githubusercontent.com/arpitarya/fux/main/records/0156_inspect.md): Arpit asked whether a consumed index is a good index or a bad one. `fux inspect` answers it descriptively: six lenses over the committed shards — boilerplate, findability, length and fields, duplication and templates, analyzer coverage, graph — each printing distributions and named lists, each naming the lever that would change what it found and applying none. Exactly three numbers carry a pass/attention flag and their floors are provisional, measured on the golden ladder and dropped to descriptive if one ever flags a healthy rung. The committed index holds term hashes, so the words come from a gitignored dictionary built by re-tokenising the sources locally; nothing new is committed and nothing is fetched. Since W-220 (2026-09-23) it also computes cached per-document facts, probes each document by its own title and headings (the new findability headline), folds identity, segments, chunks and a worst-first triage, and diffs two reports with edge loss always an alert; fux serve calls the same library.
- [SR-OBSERVE (0157) — `.fux/observers/`: the observe-only hook fux exposes after render, the third readable-source exemption](https://raw.githubusercontent.com/arpitarya/fux/main/records/0157_observe.md): After a verb has fully rendered, fux hands every file in `.fux/observers/` one frozen, counts-only fact record and discards whatever comes back. Nothing an observer does can change stdout, the exit code, the index or the next run; a raising or slow observer is skipped, named under FUX_DEBUG, and never fails the verb. fux ships no observer and imports none by name — cage is the first subscriber and fux does not know it. The seam, the record schema, the forbidden classes, the cap, and why the hook is after render and not before the verb.
- [SR-SERVE (0158) — `fux serve`, the explorer: a local page that renders `ask --json --why` and computes nothing](https://raw.githubusercontent.com/arpitarya/fux/main/records/0158_serve.md): Arpit's framing, 2026-09-22 — fux is like Google: if the ten documents an agent is handed are the right ten, the answer is mostly right. So the inspection surface is question-first. `fux serve` starts a stdlib server bound to 127.0.0.1 with no --host, serves one self-contained page, and answers GET /ask with the byte-identical stdout of `fux ask --json --why --band`. The page is a RENDERER: it computes no score, no band and no rank, because a second ranker in a browser is a restatement in the L0 sense. Every lever it prints is a proposal; no route writes a committed byte. Since W-220 (2026-09-23) the page has tabs — Ask, Answer (2026-09-27: the one passage `fux answer --json --band` would cite, byte-identical too), Documents, Words (2026-09-27: the vocabulary, a question as the analyzer reads it, where a term lives), Index — and the server calls fux.inspect in-process for the last two, on demand and cached under .fux/runtime/inspect/; the browser still computes nothing.
- [SR-CONSTANTS (0159) — the engine's fixed values live in one TOML file both planes read](https://raw.githubusercontent.com/arpitarya/fux/main/records/0159_constants.md): src/fux/constants.toml holds every fixed engine value — schema ids, format and rules versions, artefact names, decoder versions, and the numbers a file format or protocol defines. One Python loader and one Node loader read it; the Node bundle carries it inlined; a missing table or key stops the process naming it.
- [SR-IDENTIFIERS (0160) — identifier families are kept whole however they are typed](https://raw.githubusercontent.com/arpitarya/fux/main/records/0160_identifiers.md): A committed .fux/identifiers.toml names ID families (RF-{n}); both readers match them against the text at ingest and at query time and add one canonical term per match beside analyzer v3's output, so RF 118, rf118, RF–118 and RF-0118 are the term rf-118. [user] is hand-written and wins; [detected] is written only by `fux identifiers --write` from an inspect lens. The effective rules' digest is stamped into every shard header.
- [SR-SECTIONS (0161) — section records: a doc#section plane beside the document plane, folded back to one result per document](https://raw.githubusercontent.com/arpitarya/fux/main/records/0161_sections.md): The design of W-168 step 10 as ruled U2 · B2 · E1: each heading section of a multi-section document becomes a committed `doc#s<k>` record in its own plane, `.fux/index/sections/`, cut by a tunable-free section rule. Its best section, scored as a short document on the document yardstick, lifts the document toward that score by `section_weight` ≤ 1 (the third form, W-278). At 0.0 the plane is never opened, so ranking is byte-identical. Built; measured INCONCLUSIVE and ruled ship by Arpit (2026-10-13): section_weight = 1.0 together with section_records = true, both off by default.
- [SR-LLMS (0162) — llms.txt and llms-full.txt from the index, to stdout only](https://raw.githubusercontent.com/arpitarya/fux/main/records/0162_llms.md): `fux llms` prints an llms.txt — the indexed documents under the `--in` prefixes, titled by the index, noted by each document's own `description:`, archived ones under `## Optional` — and with `--full` the llms-full.txt convention: the same map followed by every prose document's text read off disk. fux writes no file; this repository's own pair is generated by `scripts/gen-llms.py` and held current by a test.
- [SR-LSP (0163) — the Language Server: the index where documents are edited](https://raw.githubusercontent.com/arpitarya/fux/main/records/0163_lsp.md): `fux lsp` serves the committed index to any editor over stdio LSP 3.17, stdlib-only and resident like `fux mcp`, as four features mapped onto what the index already holds — workspace symbols are a ranked search, hover on a link describes its target, references are backlinks, and a link to an archived or superseded document is a warning.
- [SR-VSCODE (0164) — the VS Code extension: MCP and LSP, no logic of its own](https://raw.githubusercontent.com/arpitarya/fux/main/records/0164_vscode.md): One dependency-free extension that registers `fux mcp` through VS Code's MCP API and runs `fux lsp` through a hand-rolled client, for every workspace folder holding `.fux/index/`. Authored as CommonJS modules, shipped as ONE bundled file inside a `.vsix` that `scripts/build-vsix.py` zips deterministically and the release workflow attaches to the GitHub release.
- [BIBLIOGRAPHY — every paper that built fux, and what it holds up](https://raw.githubusercontent.com/arpitarya/fux/main/records/BIBLIOGRAPHY.md): One row per external paper, standard or piece of prior art this repo cites, grouped by the part of the engine it touches. Each row says what it is in a line or two and then the only thing that matters: what DEPENDS on it, or what was NOT BUILT because of it. Derived from the References section of every record, compare doc, proposal, environment note and the paper itself.
- [SRs — the decision records](https://raw.githubusercontent.com/arpitarya/fux/main/records/README.md): The SR register: the convention, the ownership table, and the state of every record.
- [SR-TEMPLATE (0000) — the record template](https://raw.githubusercontent.com/arpitarya/fux/main/records/TEMPLATE.md): Copy for each completed feature or ruled measurement. One feature, one SR. Real records use type: Standing Record, and a real kind.
