{
  "markdown": "# Fux\n\n**Deterministic knowledge retrieval for AI-assisted codebases — rank from a\nsmall git-carried index, fetch content from the systems that own it, verify\nat answer time.**\n\n> **Status (2026-08-24): `fux-engine` 2.0.0-alpha.0 on PyPI — the record\n> shape moves to `fux.index.v2`.** M2 through M5 (accelerator, graph lane,\n> refer plane, maintenance hooks) are in; this release adds five-field\n> BM25F, per-source tuning (`.fux/tune.toml`), proximity reranking,\n> `fux enrich` and `fux mcp`. From any repo:\n> ```bash\n> fux setup                # writes the files you own, write-if-missing\n> fux ingest               # builds the committed .fux/index/*.jsonl (+ the accelerator)\n> fux ask \"your question\"  # ranks with BM25F, cites the source file\n> fux find \"your question\" # ranked locations, one per line\n> fux answer \"a question\"  # the single best answer the index can give\n> ```\n> **What fux indexes is two committed files, not config.**\n> `.fux/sources/dirs` and `.fux/sources/urls`, one entry per line, on one\n> grammar — so a 5 000-entry corpus diffs and merges line by line, and the\n> loader sorts so file order can never change a committed byte.\n> **Warm `ask` is measured at a worst-case p95 of 27.2 ms on 8 870 RFC\n> documents** — against a pre-registered 150 ms bar, where the reference\n> scan takes 4.2 s (prediction **R3 PASS**,\n> [the run](work/regression/2026-08-12-m2-accelerator/report.md)).\n>\n> The speed comes from a **derived** index under `.fux/runtime/` — never\n> committed, rebuilt from the committed shards by `fux build`. It is bound by\n> a **differential law**: its results are *byte-identical* to the reference\n> scan's, asserted over thousands of comparisons rather than spot-checked.\n> **`ask`/`find`/`answer` scan by default** (no build step needed); pass\n> `--fast` to opt into the accelerator when one exists and is fresh — same\n> results, faster (Arpit, 2026-08-21). `--scan` still forces the reference\n> path explicitly, for bug reproduction.\n>\n> **There is no dense lane and no bundled model** (2026-08-25). One existed\n> behind `ask --hybrid`, shipped off by default, and was deleted after its own\n> gate measured **0 fixed / 2 broken** — the bundled embedding mean-pooled\n> static token vectors, so it was as order-blind as the lexical scorer it was\n> meant to complement. Removing it took the wheel from **6.84 MB to 233 KB**.\n> Ranking is unchanged; the flag is gone.\n>\n> **The corpus is maintained with `fux add` / `fux remove` / `fux update`**\n> (2026-08-21), over directories, single documents and URLs alike — the entry\n> picks the list. `add` ingests by default; `remove` takes a document out of\n> the index *and* the graph, deleting its line or subtracting it from a listed\n> ancestor; `update` re-reads what is listed and never writes a line. They\n> replace `fux url` and `fux ingest --refresh-urls`\n> ([ADR-CLI](docs/adr/0002_cli-surface.md)).\n>\n> URLs join the corpus through a consumer-owned fetcher file. `fux setup`\n> writes two — `http.py` (a plain stdlib GET, the default) and `cdp.py`\n> (Chrome DevTools Protocol, also pure stdlib, which **borrows the session\n> your own signed-in Chrome already holds** and hands fux the bytes the server\n> sent) — into `.fux/fetchers/`, where they become **your** code and fux never\n> rewrites them. Neither renders a page; both return bytes plus a content type\n> and the decoder plane does the rest. Add one with\n> `fux add <URL> [--cdp] [--plain]`, which records the line **and fetches that\n> one URL**. That and `fux update` are the engine's **two** networked paths;\n> both say on stderr that they went out, and everything else is offline. A\n> line picks its own fetcher; nothing escalates automatically\n> ([ADR-URL-LIST](docs/adr/0018_url-list.md) ·\n> [ADR-FETCHER](docs/adr/0019_fetcher.md)).\n> **The graph lane has landed (M3, released in `0.34.0`)** — `explain`/`graph`/`path`,\n> unseeded label-propagation communities, a lazy PPR walk\n> ([ADR-GRAPH](docs/adr/0029_graph.md)). **Both acceptance gaps are closed**\n> (2026-08-22): 24/24 on a graded 66-document corpus, and the derived\n> `graph.json` hashes identically across two independent architectures\n> ([the run](work/regression/2026-08-22-graph-acceptance/report.md)).\n>\n> **Archived content says so, and the ranking does not move.** A source\n> declared `archived=true` carries `archived: true` on every verb, an\n> `[archived]` marker in `ask`'s text, and a stderr disclaimer — while\n> results stay byte-identical unless `[ranking] archived_weight` is set\n> below its `1.0` default\n> ([ADR-ARCHIVED-CONTENT](docs/adr/0037_archived-content.md)).\n>\n> The v0.26 engine and its docs are archived under\n> [`archive/v0.26/`](archive/v0.26/), reference-only. The new architecture\n> is specified in\n> [`work/paper/the-fux-index-paper.md`](work/paper/the-fux-index-paper.md)\n> (§4–§6 knowingly stale until M6) and built against\n> [the ADR register](docs/adr/README.md).\n>\n> **The pruning gate closed (2026-08-09): FAIL.** Keeping only each\n> document's top-*k* terms was measured, twice, against a corpus that could\n> actually test it — no selector came within 35.9 points of preserving\n> candidate recall at a 6 % budget. The committed index carries **full\n> postings**, permanently — [P1-RERUN](work/regression/2026-08-09-pruning-rerun/VERDICT.md).\n\n## The idea\n\n- **Sources own content.** Repo docs stay in git; Confluence pages stay in\n  Confluence. Fux never keeps a durable copy (except explicit per-source\n  `snapshot` policy).\n- **Git carries the index** — doc-major, sharded, human-readable JSONL;\n  full per-document postings, an extracted link graph, and a source ledger,\n  one line per document, sorted and content-sharded so\n  git itself diffs and merges it —\n  [`work/compare/index-format.compare.md`](work/compare/index-format.compare.md).\n- **Answers verify themselves.** Rank in the index, fetch the cited\n  documents live (through a version-keyed cache), re-score passages on the\n  fetched bytes, cite the fresh sha. (The refer plane is M4; M1's `ask`\n  cites straight from the committed index.)\n- **Laws:** $0 default · stdlib-only · byte-deterministic · offline by\n  default · one ADR per feature, every rule referenced.\n\n## The `.fux/` directory\n\nEverything fux puts in your repo lives here, and **every child is declared** —\nas `committed`, `derived`, or `acquired`\n([ADR-DOTFUX](docs/adr/0003_fux-directory.md)). `fux doctor` warns about\nanything that is not on this list.\n\n| entry | kind | what it is |\n|---|---|---|\n| `index/` | committed | the sharded JSONL index |\n| `sources/` | committed | the source lists — `dirs`, `urls` and `types`, one entry per line |\n| `fetchers/` | committed | **your** code (`http.py`, `cdp.py`) — written by `fux setup`, never rewritten |\n| `decoders/` | committed | **your** code, one module per format. **These copies are what run**, not the ones inside the installed package |\n| `enrich/` | committed | pinned enrichment text plus `queue.tsv` — committed, because a backlog is a team fact |\n| `tune.toml` | committed | **how** results are ordered — never what is indexed |\n| `output.toml` | committed | **how** a result is shown — never which documents come back |\n| `.fuxignore` | committed | what is **not** indexed, in `.gitignore`'s grammar |\n| `pii.toml` | committed | what is **redacted from the committed index, and only from it** |\n| `refusals.toml` | committed | what a **refusal** looks like here — the sign-in walls and error shells a server returns *instead of* the document |\n| `runtime/` | derived | the accelerator segments, the TTL fetch cache at `runtime/fetch-cache/`, the write lock (gitignored, `CACHEDIR.TAG`) |\n| `acquired/` | **acquired** | the bytes a fetch actually returned, for URLs whose line says `keep=true` |\n\n⚠ **`acquired/` is a third kind, and the distinction is load-bearing.** It is\ngitignored like `runtime/` and it is **not rebuildable** — a blob can only be\nre-*acquired*, and only while the source is still reachable and you are still\nsigned in to it. That is exactly why it is worth keeping: it is what lets a\ncitation be checked when the source cannot be reached at all.\n\n**Scaffolding has two moments.** Every `fux ingest` writes `.fux/README.md`\nand a narrow `.fux/.gitignore` (derived names only, never `*`) if they are\nmissing, and never touches them again — a fresh clone has to be correct before\na byte is written. `fux setup` is the one that writes *code*: the fetchers and\nthe source lists, explicitly, once. **Ingest never puts a fetcher in a repo\nthat only wanted an index.**\n\n`fux doctor` fails if the index has been git-ignored and warns about anything\nundeclared.\n\n## Reading order\n\n1. [`work/paper/the-fux-index-paper.md`](work/paper/the-fux-index-paper.md) — architecture + falsifiable predictions\n2. [`work/compare/index-format.compare.md`](work/compare/index-format.compare.md) — the committed format, measured\n3. [the ADR register](docs/adr/README.md) — milestones M0–M8\n4. [`archive/adr/0004_index-format.md`](archive/adr/0004_index-format.md) — the frozen M1 schema, named here for orientation only (archive is not evidence — see [`archive/README.md`](archive/README.md))\n5. [`../fux-playground/PLAYGROUND.md`](../fux-playground/PLAYGROUND.md) — a graded 10-doc corpus to try it on, in a **separate sibling repository** (clone it next to this one)\n6. [`work/WORKLOG.md`](work/WORKLOG.md) — the running build log\n\nLicense: MIT.\n",
  "bytes": 9395,
  "sha": "373770ea520faf94d65b297c2f3635baa9c153e38d3f8fe3133ca397772aa434",
  "repo_slug": "arpitarya/fux",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_arpitarya_fux_docs_index_md_43a6a511/readme"
}