Config loading, doctor diagnostics, JSON output, comprehensive tests + docs

[cognis-digital]

Motivation

uncensored-fleet shipped a clean CLI and harness, but three gaps limited real-world use:

1. The README documented overriding slots in fleet.yaml, yet the loader for that file did not
   exist — resolve() only ever returned the built-in defaults, so the documented config was inert.
2. There was no way to check a machine before pulling gigabytes of GGUFs and hitting a missing
   llama-server, a full disk, or the wrong Python.
3. Test coverage was a 5-test smoke layer; core behavior (downloads, process management, the agent
   loop, the feed ingester) was unverified, and CI ran a single Python on one OS with no lint.

This PR closes all three, adds machine-readable output, and brings the docs up to the actual code —
additively, with no change to any existing command, entry point, or default behavior.

What changed

Tests & CI

• +97 tests (5 → 102, all green). New suites with real assertions on real behavior:
  • test_models.py — registry invariants, unique ports, deep-copy isolation, override merge, conflict symmetry.
  • test_config.py — scalar coercion, the minimal YAML parser, fleet.yaml → resolve() wiring, $FLEET_CONFIG.
  • test_download.py — model_path, the 3-tier fallback chain (lib → cli → direct), skip-existing, mmproj fetch, direct-URL shape, all-fail error path.
  • test_serve.py — state round-trip, status rows, teardown (single/all/dead-PID), launch guards (missing binary, missing model), PID recording, VRAM-conflict eviction.
  • test_harness.py — tool exec (read/write/bash/unknown/error/truncation), the OpenAI wire shape + port override, and the agent loop (FINAL / TOOL-then-FINAL / plain / max-steps / recall).
  • test_memory.py — sqlite fallback remember/recall, ordering, limits, engram-absent path.
  • test_connect_map.py — map_record defaults/passthrough/stripping (no optional deps needed).
  • test_doctor.py — each check plus the aggregate report and renderer.
  • test_livesearch.py — URL building, RFC-822/ISO-8601 date parsing, RSS/Atom parsing, DDG redirect extraction, harvest de-dupe/recency, CLI modes.
  • test_cli.py — dispatch for every subcommand, --json, override threading, exit codes.
• CI overhaul (.github/workflows/ci.yml): a lint job (ruff, error-level E9,F — pyflakes + syntax, no style churn) gates a test matrix across Python 3.10/3.11/3.12/3.13 on Ubuntu plus a macOS and a Windows runner; PYTHONUTF8=1 for the test job.
• pyproject.toml: ruff>=0.5 added to the dev extra; [tool.ruff], [tool.ruff.lint] (select E9,F), and [tool.pytest.ini_options] configured.

Features

• fleet/config.py — real fleet.yaml overrides. load_overrides() reads the documented
  slots: mapping and returns a dict suitable for resolve(). Uses PyYAML when installed, else a
  small dependency-free parser for the documented subset (with int/float/bool/null coercion).
  Honors $FLEET_CONFIG. With no file present it returns {}, so the configured path is identical
  to the previous default path. The CLI now threads overrides through resolve, pull, up,
  status, run, and agent (the underlying functions already accepted an overrides argument —
  they just were never fed one).
• fleet/doctor.py — fleet doctor. Read-only, side-effect-free diagnostics: Python version
  (hard check), llama-server on PATH, free disk on the models volume, and which slots are
  downloaded / serving (soft advisories). fleet doctor --json emits a structured report and the
  command exits non-zero only on a hard failure.
• JSON output: fleet models --json and fleet status --json for jq/dashboards.

Docs

• README: new Diagnose, Configuration (with an environment-variable table), JSON
  output, and FAQ sections; refreshed embedded --help and added a doctor example block;
  Contents nav + deep-doc links updated.
• New: docs/ARCHITECTURE.md (component map, data flows, design principles),
  docs/USAGE.md (task-oriented CLI + Python API tour), ROADMAP.md (near/mid/long-term).
• examples/help.txt regenerated to include doctor.

Refactor & hygiene

• Docstring + typing clarification on models.resolve() (no behavior change).
• Removed a dead sys import (download.py) and an unused st local (serve.py).
• Added .gitignore and untracked the committed __pycache__ bytecode (build artifacts only —
  no source or functionality removed).

Test results

102 passed
ruff: All checks passed  (--select E9,F)

Run locally:

pip install -e ".[dev]"
PYTHONUTF8=1 python -m pytest -q
ruff check --select E9,F fleet livesearch.py tests

New usage examples

# Check the box before pulling models
fleet doctor
fleet doctor --json | jq '.checks[] | select(.ok==false)'

# Machine-readable fleet state
fleet models --json | jq '.coding.port'
fleet status --json | jq '.[] | select(.state=="UP") | .slot'

# fleet.yaml — now actually applied by every subcommand
slots:
  uncensored:
    repo: your-org/your-abliterated-gguf
    file: model-Q5_K_M.gguf
    port: 8774
    ctx: 32768
  coding:
    port: 8801

Backward compatibility

Additive only. No existing subcommand, flag, entry point (fleet, uncensored-fleet-emit), or
default behavior was removed or changed. resolve() with no arguments still returns the built-in
defaults; a repo without a fleet.yaml behaves exactly as before. New flags (--json) and the new
doctor command are strictly additive.

Checklist

• New tests are meaningful (real assertions, error paths, edge cases) — 97 added, 102 total.
• Full suite green; lint green.
• CI installs deps and runs lint + tests on push/PR across OS/Python matrix.
• Docs accurate to the code (no invented features).
• No files or public functionality removed; additive only.
• pip install -e . verified.