docs: point onboarding at the dashboard; drop 3 phantom keys from the seeded default (#147)

* fix(entrypoint): drop three phantom history keys from the seeded default

The config written on first boot -- what EVERY fresh Docker install starts
from -- seeded three keys that do not exist on HistoryConfig and are
silently discarded on load:

    auto_cleanup: true
    cleanup_interval_hours: 24
    max_age_days: 30

HistoryConfig has only `database`, `max_messages_per_user`, and
`conversation_timeout`.

To be precise about the impact: history cleanup DOES work -- cleanup_expired()
is wired at main.py:237 and _prune_history() honours max_messages_per_user.
What never existed is the time-based retention model these keys describe (a
30-day age cutoff on a 24h interval). An operator setting max_age_days: 90
expecting 90-day retention was silently ignored.

Not implemented here -- whether time-based retention should exist is a
product decision, not a cleanup. This only stops the default config
promising it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: point onboarding at the dashboard, not the legacy example config

The documented setup path was `cp config.example.yaml config.yaml`, but that
file is ~40% incomplete: of the 20 top-level Config fields it covers 15,
omitting coverage (the universal bbox), danger_zones, generic_sources,
meshcore_context, commands, and the current notification model
(toggles/destinations/region_routes). Its own notifications header still says
the schema "will be replaced in v0.3 by the 8-toggle model" -- which shipped
long ago. Anyone following the project's own instructions landed on a
degraded surface with no signal a richer config existed.

It is also read by NOTHING at runtime: docker-entrypoint.sh sets
MESHAI_CONFIG=/data/config.yaml and writes its own inline default on first
boot. The Dockerfile still COPYs config.example.yaml into the image, so it is
kept and now labelled reference-only rather than a starting point.

- README: Docker quick-start seeds itself; configure via the dashboard. The
  pip path still uses config.example.yaml (nothing seeds one there) but now
  carries an honest note that it is a minimal bootstrap, not a reference.
  Adds an Advanced section for the split /data/config/ layout and the
  migrate_config_v03 path into it.
- docker-compose.yml: the comment claimed config lives at /data/config.yaml
  as though that were the only layout; corrected to describe both, and note
  secrets live in /data/secrets/.env.
- Dockerfile: document why config.example.yaml is still shipped.

Not done deliberately: config.example.yaml is NOT expanded to cover all 20
sections. A second hand-maintained schema is what caused this drift; the
dashboard is the authoritative surface. The legacy single-file loader is
untouched and still fully supported.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(readme): move dashboard-first onboarding rewrite to root README

work/README.md is about to become a symlink to root README.md on
docs/single-readme. Retarget the Docker/dashboard-first quick start
and config.example.yaml honesty note added in be867d23 from
work/README.md to root README.md, adapted to the root file's own
Quick start structure (cd meshai/work, /work/-prefixed curl URLs), so
none of it is silently dropped when that symlink lands.

---------

Co-authored-by: Matt Johnson <mj@k7zvx.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

README.md

@@ -52,25 +52,43 @@ Everything is driven from the web UI, organized into **General**, **Meshtastic**
 
 ## Quick start
 
-```bash
+The dashboard is the primary way to configure MeshAI — connection, LLM backend, both transports, feeds, and routing. You shouldn't need to hand-edit YAML for a normal setup.
-git clone https://github.com/zvx-echo6/meshai.git
-cd meshai/work
-pip install -e .
-cp config.example.yaml config.yaml   # then edit config.yaml (or use the dashboard)
-meshai
-```
 
-Or with Docker:
+### Docker (recommended)
 
 ```bash
 mkdir -p meshai/data && cd meshai
 curl -O https://raw.githubusercontent.com/zvx-echo6/meshai/main/work/docker-compose.yml
-curl -o data/config.yaml https://raw.githubusercontent.com/zvx-echo6/meshai/main/work/config.example.yaml
-# edit data/config.yaml, then:
 docker compose up -d
 ```
 
-The dashboard comes up on `http://localhost:8080`.
+On first boot MeshAI writes a minimal starter config into the `meshai_data` volume (`/data/config.yaml`, plus an empty `/data/secrets/.env`) and starts the dashboard — nothing to pre-seed. Open **`http://localhost:8080`** and configure everything from there.
+
+As you save settings, MeshAI persists them back into `/data` as focused per-domain YAML files (`llm.yaml`, `meshtastic.yaml`, `notifications.yaml`, `env_feeds.yaml`, …) alongside `config.yaml` — the same multi-file config system MeshAI uses in production; the dashboard is the intended way to drive it. API keys and other secrets you enter in the dashboard are written only to `/data/secrets/.env`, never into the YAML.
+
+### From source (pip)
+
+```bash
+git clone https://github.com/zvx-echo6/meshai.git
+cd meshai/work
+pip install -e .
+cp config.example.yaml config.yaml   # minimal starting point, not exhaustive — see note below
+meshai
+```
+
+Unlike Docker, `meshai` won't create a config file for you — it needs one to exist before it will start. `config.example.yaml` bootstraps the basics (connection, LLM backend, bot behavior); once it's running, open `http://localhost:8080` and use the dashboard for everything else.
+
+> **Note on `config.example.yaml`:** it documents the legacy single-file schema and is no longer complete — it predates `coverage`, `danger_zones`, `generic_sources`, `meshcore_context`, `commands`, and the current 8-family notification-routing model (`notifications.toggles` / `destinations` / `region_routes`). The legacy single-file loader still works and is fully supported, but the dashboard — backed by the full config schema — is the authoritative way to reach every setting. Don't treat this file as a complete reference.
+
+### Advanced: the split `/data/config/` layout
+
+Production and multi-operator deployments typically move to a fully split config directory — `/data/config/config.yaml` plus one file per domain, `local.yaml` for operator-identifying values, and `!include` orchestration — instead of the single flat file above. MeshAI loads this layout automatically whenever it's present. To convert an existing single-file install:
+
+```bash
+docker compose exec meshai python -m meshai.scripts.migrate_config_v03
+```
+
+This backs up the original `config.yaml`, splits it into `/data/config/`, extracts secrets to `/data/secrets/.env`, and verifies the new layout loads identically before finishing — restart the container afterward to pick it up. It's optional: the dashboard is fully functional against either layout. (Templates for building a split layout from scratch also ship in the repo's `work/config/` directory: `local.yaml.example`, `.env.example`.)
 
 ---
 

work/Dockerfile

@@ -72,6 +72,10 @@ COPY --chown=meshai:meshai meshai/ ./meshai/
 COPY --from=frontend --chown=meshai:meshai /build/meshai/dashboard/static/ ./meshai/dashboard/static/
 COPY --chown=meshai:meshai pyproject.toml .
 COPY --chown=meshai:meshai README.md .
+# Reference only: docker-entrypoint.sh writes its own minimal default to
+# /data/config.yaml on first boot and does NOT read this file. It's shipped
+# for local/pip installs and anyone who wants the legacy single-file schema
+# on hand inside the container (e.g. via `docker compose exec`).
 COPY --chown=meshai:meshai config.example.yaml .
 COPY --chown=meshai:meshai docker-entrypoint.sh .
 

work/docker-compose.yml

@@ -6,10 +6,17 @@
 #
 # Dashboard: http://localhost:8080
 #
-# Config is stored in the meshai_data volume at /data/config.yaml
+# Config lives in the meshai_data volume. On first boot MeshAI writes a
+# starter single file at /data/config.yaml (that's the legacy fallback
+# layout, not the primary one) plus an empty /data/secrets/.env; configure
+# everything from the dashboard from there. MeshAI also supports a fully
+# split /data/config/ directory (config.yaml + one file per domain) and
+# prefers it automatically when present -- see README's "Advanced" section
+# for the migration path. Secrets always live in /data/secrets/.env, never
+# in the YAML.
 #
 # For serial connection (USB), uncomment the devices section below
-# For TCP connection, edit config.yaml or use the dashboard
+# For TCP connection, use the dashboard (or edit the YAML directly)
 
 services:
   meshai:

work/docker-entrypoint.sh

@@ -34,9 +34,6 @@ history:
   database: /data/conversations.db
   max_messages_per_user: 50
   conversation_timeout: 86400
-  auto_cleanup: true
-  cleanup_interval_hours: 24
-  max_age_days: 30
 
 memory:
   enabled: true