Add NixOS module, update docs and flake for host integration

- Restore nixosModules.default in flake.nix with hardened systemd
  service (DynamicUser, EnvironmentFile, sandbox options)
- Update flake.lock to current nixos-unstable
- Rewrite AGENTS.md for new agentic sessions with architecture notes
- Rewrite README.md with NixOS install, OpenClaw setup, and agent guide

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ChrisLAS

AGENTS.md

@@ -2,57 +2,135 @@
 
 This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
 
-## Quick Reference
+## What This Project Is
+
+FreshRSS MCP server using **Streamable HTTP** transport, designed for the **OpenClaw** gateway's `openclaw-mcp-bridge` plugin. It wraps the FreshRSS Google Reader API and exposes 10 MCP tools for RSS feed management.
+
+**Transport**: Streamable HTTP (POST to `/mcp`) -- NOT stdio. The OpenClaw MCP bridge discovers tools via HTTP POST with JSON-RPC 2.0, not by spawning a subprocess.
+
+**Runtime**: Python 3.12+, managed by `uv`. Deployed on NixOS as a systemd service.
+
+## Project Layout
 
-```bash
-bd ready # Find available work
-bd show <id> # View issue details
-bd update <id> --status in_progress # Claim work
-bd close <id> # Complete work
-bd sync # Sync with git
 ```
+freshrss-mcp/
+  pyproject.toml          # uv/PEP 621 — entry point: freshrss-mcp
+  uv.lock                 # Committed lockfile
+  .python-version         # 3.13
+  flake.nix               # Dev shell + NixOS module (systemd service)
+  src/freshrss_mcp/
+    server.py             # FastMCP entry point (streamable-http transport)
+    tools.py              # 10 MCP tool definitions with error boundaries
+    client.py             # FreshRSS Google Reader API client (async, httpx)
+    config.py             # pydantic-settings config from env vars
+    models.py             # Article and Feed dataclasses
+  tests/                  # 67 unit tests
+    test_config.py        # Config validation, defaults, secret masking
+    test_client.py        # Auth, feeds, articles, ID extraction, edge cases
+    test_tools.py         # Every tool happy path + error boundary
+    test_models.py        # Serialization, construction, mutability
+```
+
+## Key Architecture Decisions
 
-## Project Overview
+1. **Lazy authentication**: `client.py` calls `_ensure_authenticated()` before every API method. No need to pre-auth at startup.
 
-FreshRSS MCP server using **Streamable HTTP** transport for OpenClaw integration.
+2. **Error boundaries**: Every tool in `tools.py` catches all exceptions and returns `"Error: ..."` strings. MCP protocol never sees uncaught exceptions.
 
-**Key files:**
-- `src/freshrss_mcp/server.py` — Entry point, FastMCP with streamable-http
-- `src/freshrss_mcp/tools.py` — All MCP tool definitions
-- `src/freshrss_mcp/client.py` — FreshRSS Google Reader API client
-- `src/freshrss_mcp/config.py` — pydantic-settings config from env vars
-- `tests/` — 67 tests across config, client, tools, and models
+3. **pydantic-settings**: `config.py` uses `BaseSettings` with `SecretStr` for the password. Missing env vars produce clear validation errors at startup.
+
+4. **Single client instance**: `FreshRSSClient` is created once in `server.py` and shared across all tool calls. No per-call client creation.
+
+5. **No version pins**: `pyproject.toml` has no version constraints on dependencies, per the MCP build spec.
+
+## How to Run
 
-**Running:**
 ```bash
-uv sync && uv run pytest -v    # test
-uv run freshrss-mcp             # start server
+# Dev
+uv sync && uv run pytest -v
+
+# Start server (needs env vars)
+export FRESHRSS_URL="https://freshrss.trailertrash.io"
+export FRESHRSS_USERNAME="chrisf"
+export FRESHRSS_PASSWORD="..."
+export MCP_SERVER_PORT=8765
+uv run freshrss-mcp
+
+# Server binds to http://127.0.0.1:8765/mcp
 ```
 
-**Transport:** Streamable HTTP (not stdio). OpenClaw's `openclaw-mcp-bridge` plugin connects via HTTP POST to `/mcp`.
+## NixOS Integration
+
+The flake exports `nixosModules.default`. Host config (rvbee) at `/home/chrisf/build/config`:
+
+```nix
+# In flake.nix inputs:
+freshrss-mcp.url = "github:ChrisLAS/freshrss-mcp";
+freshrss-mcp.inputs.nixpkgs.follows = "nixpkgs";
+
+# In rvbee modules:
+freshrss-mcp.nixosModules.default
+
+# In services config:
+services.freshrss-mcp-server = {
+  enable = true;
+  freshRssUrl = "https://freshrss.trailertrash.io";
+  username = "chrisf";
+  passwordFile = "/home/chrisf/.config/secrets/freshrss-mcp";
+  port = 3005;
+  host = "0.0.0.0";
+};
+```
+
+The password file must be an env file: `FRESHRSS_PASSWORD=<value>`.
+
+## OpenClaw Bridge Config
+
+The server is consumed by the `openclaw-mcp-bridge` plugin in `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-mcp-bridge": {
+        "config": {
+          "servers": [
+            {
+              "name": "FreshRSS",
+              "url": "http://127.0.0.1:3005",
+              "prefix": "freshrss"
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+Tools appear as: `freshrss_list_feeds`, `freshrss_get_unread_articles`, etc.
+
+## Quick Reference
+
+```bash
+bd ready          # Find available work
+bd show <id>      # View issue details
+bd update <id> --status in_progress  # Claim work
+bd close <id>     # Complete work
+bd sync           # Sync with git
+```
 
 ## Landing the Plane (Session Completion)
 
-**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
-
-**MANDATORY WORKFLOW:**
-
-1. **File issues for remaining work** - Create issues for anything that needs follow-up
-2. **Run quality gates** (if code changed) - Tests, linters, builds
-3. **Update issue status** - Close finished work, update in-progress items
-4. **PUSH TO REMOTE** - This is MANDATORY:
- ```bash
- git pull --rebase
- bd sync
- git push
- git status # MUST show "up to date with origin"
- ```
-5. **Clean up** - Clear stashes, prune remote branches
-6. **Verify** - All changes committed AND pushed
-7. **Hand off** - Provide context for next session
-
-**CRITICAL RULES:**
-- Work is NOT complete until `git push` succeeds
-- NEVER stop before pushing - that leaves work stranded locally
-- NEVER say "ready to push when you are" - YOU must push
-- If push fails, resolve and retry until it succeeds
+When ending a session, you MUST:
+
+1. File issues for remaining work
+2. Run quality gates: `uv run pytest -v` and `ruff check src/ tests/`
+3. Update issue status via `bd close`
+4. Push to remote:
+   ```bash
+   git pull --rebase && bd sync && git push
+   git status  # MUST show "up to date with origin"
+   ```
+
+Work is NOT complete until `git push` succeeds.