# Homestead

An offline library of practical knowledge — first aid, water, food preservation,
power, repair, livestock — that stays searchable when the internet does not.

Everything runs locally: the documents sit on your disk, the embedding model
runs on your machine, and no query ever leaves it. It ships with an **MCP
server**, so Claude or any other MCP-speaking assistant can search the library
and file new documents into it.

```
$ homestead search "how do I treat a deep cut"

Wilderness First Aid Curriculum and Doctrine Guidelines  [first-aid]
    Control bleeding with direct pressure. Apply a gloved hand and firm,
    steady pressure directly over the wound for at least ten minutes...
```

## Install

```bash
pip install 'homestead-library[all]'   # the machine that hosts the library
homestead install                 # choose your shelves, pull the documents in
```

`homestead install` asks what you want on your shelves, downloads it from the
original publishers, and builds the search index:

```
What would you like on your shelves?
  1) Essentials  --  9 documents, ~66 MB
     Keeping people alive and fed when the power is out: first aid, water,
     food preservation, emergency preparedness.
  2) Growing & keeping food  --  8 documents, ~90 MB
  3) Building & fixing  --  5 documents, ~75 MB
  4) Everything  --  22 documents, ~200 MB
  5) Choose shelf by shelf
```

Then start it:

```bash
homestead serve                   # http://127.0.0.1:8021
```

### Where the documents come from

This project ships a **catalog, not a corpus**. Nothing is redistributed here.
Every entry in [`shelves.toml`](src/homestead/catalog/shelves.toml) points at
the publisher's own copy — mostly US federal agencies (FEMA, CDC, NOAA, USDA,
the armed services), university extension services, and open-licence
publishers like Hesperian and the FAO. The catalog records the licence for each
one.

That keeps the repo small, keeps sources current, and keeps the licensing
honest. It also means links rot: if a download fails, the installer says so,
and a catalog fix is a welcome pull request.

## Using it from an AI assistant

The MCP server is dependency-free and starts instantly, so it can live on a
different machine from the library if you like.

**Claude Code**
```bash
claude mcp add homestead -- homestead-mcp
```

**Hermes**
```bash
hermes mcp add homestead --command "$(command -v homestead-mcp)"
```

**Claude Desktop** — add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "homestead": {
      "command": "homestead-mcp",
      "env": { "HOMESTEAD_URL": "http://127.0.0.1:8021" }
    }
  }
}
```

**Query tools** — talk to a running library:

| Tool | What it does |
|---|---|
| `homestead_search` | Semantic search; returns documents with verbatim passages |
| `homestead_add` | Import a file, wait for indexing, report the result |
| `homestead_categories` | List shelves, with counts and safety cautions |
| `homestead_docs` | List documents, optionally by shelf |
| `homestead_health` | Is the library up, and how much is in it |

**Lifecycle tools** — set a library up from nothing, no shell required:

| Tool | What it does |
|---|---|
| `homestead_status` | Is this machine ready? Returns a check per component and a `next` field naming the one thing to fix |
| `homestead_catalog` | What can be installed: packs, shelves, sources, licences, sizes |
| `homestead_install` | Download and index chosen shelves. Returns a job id immediately |
| `homestead_index_build` | Rebuild the index from documents already present |
| `homestead_job` | Poll an install or index job to completion |

MCP tools are read at client start-up, so **restart your assistant's session**
after adding the server.

## For agents

This is built to be installed and driven by agents, not just people.

**Nothing blocks.** Installing takes minutes and the first index build downloads
a ~2 GB model, so `homestead_install` returns a job id straight away and you
poll `homestead_job` until `status` is `done` or `error`.

**Start with `homestead_status`.** It works with nothing running and no corpus
on disk, and every failing check carries its own `remedy`. The top-level `next`
field is the single command to run:

```json
{
  "ready": false,
  "checks": {
    "corpus":     {"ok": false, "documents": 0, "remedy": "homestead install --pack essentials --yes"},
    "index":      {"ok": false, "remedy": "homestead index"},
    "embeddings": {"ok": true,  "remedy": null},
    "server":     {"ok": false, "remedy": "homestead serve"}
  },
  "next": "homestead install --pack essentials --yes"
}
```

**From a shell,** every command takes `--json`, and errors carry the fix:

```bash
homestead doctor --json            # same object as homestead_status
homestead install --list --json    # the whole catalog, with licences
homestead bootstrap --pack essentials --json    # install + index, one step
homestead search "water purification" --json
homestead --url http://other-host:8021 search "..."   # target another library
```

`homestead install` never prompts when stdin is not a terminal. Without a
selection it exits `2` and tells you which flags would have worked, rather than
guessing or hanging:

```json
{
  "ok": false,
  "error": "no shelves selected and stdin is not a terminal",
  "remedy": "homestead install --pack essentials --yes --json",
  "valid_packs": ["essentials", "growing", "fixing", "everything"]
}
```

Downloads are idempotent — a finished file is never re-fetched, so re-running
an install is safe and cheap.

## Commands

```
homestead install          choose shelves and download them
homestead install --list   show the catalog and its licences
homestead index            (re)build the search index
homestead serve            run the library server (loopback only)
homestead serve --host 0.0.0.0   share it on your network
homestead search QUERY     search from the terminal
homestead add FILE -c soil add a document of your own
homestead bootstrap        install + index in one step (unattended)
homestead paths            where everything lives
homestead doctor           check the installation (--json for agents)
```

## Where things live

Defaults follow the XDG spec; every path is overridable.

| Path | Holds | Override |
|---|---|---|
| `~/.local/share/homestead/corpus` | downloaded documents | `HOMESTEAD_CORPUS` |
| `~/.local/share/homestead/index` | the vector index | `HOMESTEAD_INDEX` |
| `~/.local/share/homestead/library` | documents you added | `HOMESTEAD_LIBRARY` |
| `~/.local/share/homestead/models` | the embedding model | `HOMESTEAD_MODEL` |

Set `HOMESTEAD_HOME` to move all of it at once.

### Local shelves

A library grows shelves the packaged catalog knows nothing about. Declare them
in `site.toml` (in `HOMESTEAD_HOME`, or set `HOMESTEAD_SITE_CONFIG`) rather than
forking:

```toml
[[category]]
slug  = "boatbuilding"
label = "Boatbuilding"
icon  = "~"
match = "boats"        # any corpus path containing this lands on this shelf
```

## How it works

Documents are split into overlapping ~1200-character passages and embedded with
[BAAI/bge-m3](https://huggingface.co/BAAI/bge-m3) locally. Search embeds the
query and takes a cosine top-k, grouped by document. For PDFs the server keeps a
chunk → page map, so an answer can tell you the page to turn to.

The corpus index is read-only. Anything you add later goes into a separate
overlay that is searched alongside it, so adding documents can never corrupt the
base index — and deleting the overlay loses only your additions.

## A word on trust

This is reference material, gathered for the situation where better help is not
available. It is not medical, legal, or engineering advice. Two shelves carry
explicit cautions the software will show you — **foraging** (misidentification
kills) and **food preservation** (follow current USDA process times, not the
ones in century-old cookbooks). Semantic search has no idea a 1918 canning time
has since been proven dangerous. Read accordingly.

## Security

**The server binds `127.0.0.1` by default** and has no authentication. That
combination is safe: nothing off your machine can reach it.

To use the library from a phone or another computer, bind wider:

```bash
homestead serve --host 0.0.0.0        # or set HOMESTEAD_HOST
```

Now anyone who can reach that port can read your whole library *and add
documents to it*, so do this only on a network you trust — a home LAN, or
better, a private network like Tailscale. Loopback and Tailscale peers are
always trusted; other clients are challenged with Basic Auth **if** you set
credentials (`.auth.env`, or `HOMESTEAD_AUTH_USER` / `HOMESTEAD_AUTH_PASS`).
With none set there is no challenge at all. The server warns you on startup
when it is bound beyond loopback without credentials.

## Contributing

Adding a source to the catalog is the most useful contribution. It must be free
to download from the publisher, correctly licensed, and recorded with its real
licence in `shelves.toml`. See the notes at the top of that file.

## Installing

```bash
pip install homestead-library              # CLI + MCP server, no dependencies
pip install 'homestead-library[server]'    # + embeddings, to host a library
pip install 'homestead-library[all]'       # + Stack Exchange dump support
```

The command is `homestead`; the MCP server is `homestead-mcp`.

## Licence

MIT. The documents the installer downloads carry their own licences, recorded
per-entry in the catalog. The Stack Exchange corpora are CC BY-SA 4.0 —
attribution belongs to Stack Exchange and the individual authors.