@fux-engine/reader 0.0.0-stage → 4.0.1

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# fux-engine — the Node read plane
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read a [fux](https://github.com/arpitarya/fux) index from Node. **The command
+is `fux`; the package is `fux-engine`** — `fux` was taken on npm in 2016.
+
+> **This file ships twice**, on purpose: it is the npm package's page, and
+> `fux setup` vendors it into your repository at `.fux/node/README.md`. So it is
+> written for whoever finds it, in either place.
+
+## Run it
+
+**In a repository that has a fux index, always through the shim:**
+
+```console
+$ .fux/fux find rollback
+$ .fux/fux ask "how do we roll back a release" --band
+$ .fux/fux answer "retry policy" --json
+```
+
+🔴 **`.fux/fux` is the one entry point that is correct in every shape**, which
+is why it is the only one documented. It resolves the reader in three rungs —
+the vendored bundle, then `.fux/node/node_modules/.bin/fux`, then every
+ancestor's `node_modules/.bin/fux` — because npm and Yarn hoist that binary to
+the workspace root and **pnpm and bun do not**. Naming a path instead would be
+right for half the ecosystem and silently wrong for the other half.
+
+**Without a repository, or to try it:**
+
+```console
+$ npx fux-engine --version
+```
+
+**As a library:**
+
+```js
+import { open } from 'fux-engine'
+const ix = await open('.')
+await ix.find('rollback', { top: 5 })
+```
+
+## What is in `.fux/node/`
+
+`fux setup` writes one of two shapes, and it detects which:
+
+| | what is there | offline | how it runs |
+|---|---|---|---|
+| **the default** | `fux.mjs` (one generated file) · `package.json` · `mcp-tools.json` · this file | **yes** — nothing to install | `.fux/fux …` |
+| **a monorepo** | `package.json` only, declaring `fux-engine@<version>` | after an install | `.fux/fux …`, once your package manager has run |
+
+In the monorepo shape `.fux/node` is declared as a **workspace member** in your
+root manifest — `fux setup` adds that one line, says so, and never adds it
+twice. Run your package manager's `install` afterwards; `fux doctor` tells you
+if you have not.
+
+🔴 **`fux.mjs` is GENERATED. Do not edit it.** It is rebuilt from fux's sources
+at publish time and overwritten whenever the engine version changes. To see what
+it does, read `node/fux.mjs` and `node/src/**` in the fux repository at the
+matching tag — or regenerate it and compare bytes:
+
+```console
+$ python -m fux.store.nodebundle node node/dist
+```
+
+## What it is
+
+A fux index is a small, plain-text index committed to git — statistics about
+your documents, never the documents. Python writes it; **Python or Node reads
+it, and the two are held byte-equal by a differential law.**
+
+- **Zero dependencies, and no build step *for you*.** There is no
+  `dependencies` key in the published `package.json` at all. Fux's own release
+  pipeline has a bundler; nobody running `fux setup` does, and nothing is
+  compiled on your machine.
+- **One artefact, not a module tree.** What lands in your repository is one
+  generated file, so a fux upgrade is a one-file diff and a tampered reader is
+  detectable by rebuilding it. Before 2026-09-12 it was 47 of fux's own `.mjs`
+  files in your tree; `fux setup` deletes them when it upgrades you.
+- **It never fetches, and it writes one thing: the derived plane.** `fux
+  build` rebuilds the gitignored `.fux/runtime/` from the committed index,
+  byte-identical to Python's build, under the same write lock, and `--fast`
+  then answers from it. `ingest`, `add`, `enrich` and every other write verb
+  belongs to Python fux, and typing one here tells you so rather than saying
+  *unknown command*.
+- **Same answers as Python.** Same ids, same order, same locators, same band;
+  scores equal after `round(9)`, which is the sort key's own resolution.
+- **Two things it deliberately does not do.** It cannot read a document that
+  needs a decoder (a `.pdf`, a `.xlsx`, your own `.fux/decoders/*.py`), so
+  `answer` **declines** to cite one rather than quoting line numbers into text
+  the index never held; and it never touches the network.
+
+## Two `fux` commands on one PATH
+
+Python's `fux-engine` installs a `fux` too, with a **different verb set**.
+`--version` names the runtime, so no bug report is ever ambiguous:
+
+```console
+$ fux --version
+fux 2.0.0 (node 24.13.0)
+```
+
+`fux doctor` (Python's) reports when a Node `fux` sits earlier on your PATH.
+
+## Verbs
+
+`find` · `ask` · `answer` · `explain` · `graph` · `path` · `mcp`
+
+`fux mcp` serves the index over the Model Context Protocol on stdio —
+`fux_search`, `fux_passage`, `fux_related` — so an agent can query it with no
+glue. `verify`, `--why`, `--receipt` and `--journal` have no Node twin; they are
+Python's.

package/mcp-tools.json

@@ -0,0 +1,66 @@
+{
+  "_comment": "The MCP tool descriptions, the authored text for node/src/verbs/mcp.mjs, held equal to src/fux/mcp.py's literal by tests/test_mcp.py. A description is what an agent reads to decide whether to call a tool, so two hand-maintained copies would drift into two products wearing one name. {{TOP}} is substituted with the connection's resolved [mcp] top.",
+  "tools": [
+    {
+      "name": "fux_search",
+      "description": "Search the committed index for documents relevant to a natural-language question. Returns ranked documents with content hashes and the headings that match your query -- section-level, not line-level; call fux_passage for the lines. This is the call to make first for any 'where is X' or 'why did we decide Y' question about this repository. READ THE `confidence` BLOCK BEFORE USING THE RESULTS. If `confidence.answerable` is false, do not answer from these results at all -- say what was searched and stop. If `confidence.band` is 'partial', answer but name every term in `confidence.missing`: those are words from the question that appear in no document here. If it is 'weak', the ranking could not separate the top hits -- that is a SIGNAL and not a refusal (`answerable` stays true): read the near-tied candidates and judge, and if neither answers, say the documents do not say and report what was searched rather than a conclusion. The payload also carries `related`: documents that NO query word matched, returned because the ranked results above LINK to them, each with the `route` it was reached by. They are not matches and must never be cited as one -- read a related document with fux_passage before you use it, and say that you followed a link to it rather than found it.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "A natural-language question."
+          },
+          "k": {
+            "type": "integer",
+            "description": "Maximum results (default {{TOP}}; this repository's .fux/output.toml may set a different default under [mcp]).",
+            "default": "{{TOP}}"
+          },
+          "expand": {
+            "type": "string",
+            "description": "OPTIONAL. Words you expect the document to use, when they differ from the question's. Scored at a lower weight than the question's own terms, and a document matching ONLY these is never returned. Use it after a search comes back `partial` with a non-empty `missing`: re-search with the vocabulary the corpus would use for the missing term."
+          }
+        },
+        "required": [
+          "query"
+        ]
+      }
+    },
+    {
+      "name": "fux_passage",
+      "description": "Read the verbatim text of a cited span, addressed as returned by fux_search. Use this instead of reading a whole file when you already have a citation: it returns only the cited lines and the hash they were read at, as `path`, `line_start`, `line_end`, `sha` and `text`.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "line_start": {
+            "type": "integer"
+          },
+          "line_end": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "path"
+        ]
+      }
+    },
+    {
+      "name": "fux_related",
+      "description": "The neighbourhood around a document: what it links to, what links to it, what it supersedes or is superseded by, and whether it is archived. Use when a result raises 'what else was decided with this?' It returns `path`, `title`, `archived`, `superseded`, `outbound` and `inbound`.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "path"
+        ]
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@fux-engine/reader",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.1",
+  "description": "Read a fux index from Node. Ranked, cited answers from a small index committed to git — no server, no model, no Python.",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "fux": "./fux.mjs"
+  },
+  "exports": {
+    ".": "./fux.mjs"
+  },
+  "files": [
+    "fux.mjs",
+    "mcp-tools.json",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arpitarya/fux.git"
+  },
+  "homepage": "https://github.com/arpitarya/fux#readme",
+  "bugs": {
+    "url": "https://github.com/arpitarya/fux/issues"
+  },
+  "keywords": [
+    "knowledge",
+    "documentation",
+    "search",
+    "index",
+    "bm25",
+    "adr",
+    "runbook"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  }
+}