From 62e2bad5e82879aac33b6aa964ae78d109e1225f Mon Sep 17 00:00:00 2001 From: znerol2 <6800371+znerol2@users.noreply.github.com> Date: Wed, 21 Oct 2026 08:52:12 +0200 Subject: [PATCH 1/3] docs(agents): slim the agent files to the umbrella pattern AGENTS.md now carries the repo guidance in 60 lines or fewer. CLAUDE.md and QWEN.md keep the generated working-model block and point to AGENTS.md. The boot steps send agents to the umbrella status digest and the pinned operator notes issue. Signed-off-by: znerol2 <6800371+znerol2@users.noreply.github.com> --- AGENTS.md | 41 +++++++++++++++++++++++++++++++++++------ CLAUDE.md | 52 +++------------------------------------------------- QWEN.md | 44 ++------------------------------------------ 3 files changed, 40 insertions(+), 97 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f576ead..9264e0d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,9 +1,39 @@ -# AGENTS — dmf-init +# AGENTS.md — dmf-init -Day-0 stateless init/bootstrap container for the DMF Platform (React + FastAPI). See README.md and CLAUDE.md for repo specifics; cross-repo context — -status, decisions, plans — lives in the -[dmfdeploy umbrella repo](https://github.com/dmfdeploy/dmfdeploy), checked out -as a sibling directory of this repo. +The Day-0, stateless init and bootstrap container of the dmfdeploy platform +(React, FastAPI). A localhost-only web UI wraps `dmf-env`'s `init-wizard.sh +--non-interactive` and `bin/` scripts to take a cluster from zero to verified, +with passphrase-wrapped backup and restore, so you can delete the container +afterward. Design: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). +Canonical spec: the [DMF Init Bootstrap Container Plan](https://github.com/dmfdeploy/dmfdeploy/blob/45eb326e973b10e0b52deef290981ceac9bcf5bd/docs/plans/DMF%20Init%20Bootstrap%20Container%20Plan%202026-06-02.md). + +## Boot steps + +In the umbrella repo ([dmfdeploy/dmfdeploy](https://github.com/dmfdeploy/dmfdeploy), +a sibling checkout), run `git pull` and `bin/generate-status.sh`, then read +`STATUS.digest.local.md` and skim `docs/decisions/INDEX.md`. Before you stop, +record shared-state changes in the pinned [Operator notes issue](https://github.com/dmfdeploy/dmfdeploy/issues/618). + +## Build and test + +- Python 3.12+: `pip install .[dev]`, then `ruff check .` and `pytest`. Backup + and restore tests need `age` and `rclone`. +- Frontend: `cd frontend && npm ci && npm run build`. +- Image: `docker build -t dmf-init:ci .` (run modes: `README.md`). + +## Rules that are easy to miss + +- Wrap the `dmf-env` bash; never reimplement it. The answers file is the shared + CLI and web contract, and generated secrets stay inside the wizard. +- Keep the container stateless: tmpfs scratch only; never persist env state or + secrets to the host or to this repo. Keep tracked files public-safe: no IPs, + operator identity or credentials. +- Expose the web UI on loopback only, and keep the single-use launch token. + The container binds `0.0.0.0` inside its own namespace, so loopback safety + comes from publishing with `-p 127.0.0.1:…`. Never publish on a non-loopback + host interface. +- The UI serves `http://localhost` by default, already a secure context. Enable + HTTPS (`DMF_TLS_ENABLED=true`) only for non-localhost access. ## Working model (mandatory) @@ -26,4 +56,3 @@ in the umbrella repo. The three rules that matter mid-task: liveness; plan frontmatter = design state; ADRs = decisions (RFC in Discussions first); STATUS.md = committed notes; STATUS.local.md = live repo snapshot. - diff --git a/CLAUDE.md b/CLAUDE.md index 35bd60a..0730540 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,6 @@ -# dmf-init +# CLAUDE.md — dmf-init + +Project guidance for every agent lives in [AGENTS.md](AGENTS.md). Read it first. ## Working model (mandatory) @@ -21,51 +23,3 @@ in the umbrella repo. The three rules that matter mid-task: liveness; plan frontmatter = design state; ADRs = decisions (RFC in Discussions first); STATUS.md = committed notes; STATUS.local.md = live repo snapshot. - -## DMF Platform context — read first - -This repo is a component of the **DMF Platform**, an umbrella workspace -checked out alongside this repo. Operators set `$DMFDEPLOY_UMBRELLA` to its -local path. Cross-cutting state (status, decisions, plans, skills) lives -there, not here. - -Before any non-trivial change in this repo: - -```bash -cd "$DMFDEPLOY_UMBRELLA" -git fetch && git pull -bin/generate-status.sh --no-fetch # refreshes STATUS.md -``` - -Then read in order: -1. `dmfdeploy/STATUS.md` — what's happening across all repos right now -2. `dmfdeploy/CLAUDE.md` — full boot ritual + workspace map -3. `dmfdeploy/docs/decisions/INDEX.md` — ADRs applicable to your task -4. The most recent file under `dmfdeploy/docs/handoffs/` - -If you change cross-repo state, update the `` section of -`dmfdeploy/STATUS.md` before ending the session. - ---- - -**Day-0 stateless init & bootstrap container.** A localhost-only web UI -(React + FastAPI, served over HTTPS for a secure context) that wraps `dmf-env`'s -`init-wizard.sh --non-interactive` and `bin/` scripts to take a cluster from zero -to verified, plus a passphrase-wrapped backup/restore lifecycle delivered as -browser downloads (restore via file upload) so the container can be deleted after -commissioning. - -Canonical spec: `dmfdeploy/docs/plans/DMF Init Bootstrap Container Plan 2026-06-02.md`. - -Non-negotiables specific to this repo: -- **Wrap, don't reimplement** the `dmf-env` bash. The answers-file is the shared - CLI/web contract; generated secrets stay wizard-internal. -- **Stateless**: tmpfs scratch only; never persist env state or secrets to the - host or to this repo. -- **Public-safe**: no IPs, operator identity, or credentials in tracked files. -- **Loopback-only exposure**; single-use launch token. The container binds - `0.0.0.0` *inside its namespace* (so `docker run -p 127.0.0.1:8000:8000` works - with no flags) — loopback safety is the `-p 127.0.0.1:…` publish, never a - non-loopback host interface. Served as **http://localhost** by default (already - a secure context, no cert warning); HTTPS is opt-in (`DMF_TLS_ENABLED=true`) - for non-localhost access. diff --git a/QWEN.md b/QWEN.md index cd30824..f7542f6 100644 --- a/QWEN.md +++ b/QWEN.md @@ -1,5 +1,7 @@ # QWEN.md — dmf-init +Project guidance for every agent lives in [AGENTS.md](AGENTS.md). Read it first. + ## Working model (mandatory) @@ -21,45 +23,3 @@ in the umbrella repo. The three rules that matter mid-task: liveness; plan frontmatter = design state; ADRs = decisions (RFC in Discussions first); STATUS.md = committed notes; STATUS.local.md = live repo snapshot. - -## DMF Platform context — read first - -This repo is a component of the **DMF Platform**, an umbrella workspace -checked out alongside this repo. Operators set `$DMFDEPLOY_UMBRELLA` to its -local path. Cross-cutting state (status, decisions, plans, skills) lives -there, not here. - -Before any non-trivial change in this repo: - -```bash -cd "$DMFDEPLOY_UMBRELLA" -git fetch && git pull -bin/generate-status.sh --no-fetch # refreshes STATUS.md -``` - -Then read in order: -1. `dmfdeploy/STATUS.md` — what's happening across all repos right now -2. `dmfdeploy/QWEN.md` — full boot ritual + skills index + Qwen-specific rules -3. `dmfdeploy/docs/decisions/INDEX.md` — ADRs applicable to your task -4. The most recent file under `dmfdeploy/docs/handoffs/` - -If you change cross-repo state, update the `` section of -`dmfdeploy/STATUS.md` before ending the session. - ---- - -**Day-0 stateless init & bootstrap container.** A localhost-only web UI -(React + FastAPI) that wraps `dmf-env`'s `init-wizard.sh --non-interactive` and -`bin/` scripts to take a cluster from zero to verified, plus a -passphrase-wrapped dual-remote backup/restore lifecycle so the container can be -deleted after commissioning. - -Canonical spec: `dmfdeploy/docs/plans/DMF Init Bootstrap Container Plan 2026-06-02.md`. - -Non-negotiables specific to this repo: -- **Wrap, don't reimplement** the `dmf-env` bash. The answers-file is the shared - CLI/web contract; generated secrets stay wizard-internal. -- **Stateless**: tmpfs scratch only; never persist env state or secrets to the - host or to this repo. -- **Public-safe**: no IPs, operator identity, or credentials in tracked files. -- **Loopback-only** web bind; single-use launch token. From 80b30bc767ebfd52716c61bb53aa5a94bbbcb79a Mon Sep 17 00:00:00 2001 From: znerol2 <6800371+znerol2@users.noreply.github.com> Date: Wed, 21 Oct 2026 08:52:12 +0200 Subject: [PATCH 2/3] docs(contributing): link the dmfdeploy/dmfdeploy umbrella repo The quick start and licence sections named an umbrella repo that does not exist. They now link the real one. Signed-off-by: znerol2 <6800371+znerol2@users.noreply.github.com> --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5f29917..b97ddc4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ and is never a contribution path.) ## Quick start -1. Read the platform overview in the **dmf-platform** umbrella repo +1. Read the platform overview in the [dmfdeploy/dmfdeploy](https://github.com/dmfdeploy/dmfdeploy) umbrella repo (`docs/architecture/DMF Platform Plan.md`) and apply any relevant ADRs from `docs/decisions/INDEX.md`. 2. Fork or branch, make your change on a topic branch, open a PR against `main`. @@ -87,5 +87,6 @@ See [`SECURITY.md`](SECURITY.md). **Do not** open a public issue for a vulnerabi ## License & spec Contributions are licensed under [Apache 2.0](LICENSE). The canonical governance -model is **ADR-0041 — DMF Release and Contribution Model** in the dmf-platform +model is **ADR-0041 — DMF Release and Contribution Model** in the +[dmfdeploy/dmfdeploy](https://github.com/dmfdeploy/dmfdeploy) umbrella repo (`docs/decisions/`). From a0757aaabb6eb3a1b37caaa042ecbdb941960e63 Mon Sep 17 00:00:00 2001 From: znerol2 <6800371+znerol2@users.noreply.github.com> Date: Wed, 21 Oct 2026 08:52:12 +0200 Subject: [PATCH 3/3] docs(links): pin umbrella plan links to a permalink These references point at umbrella plan files that are about to move to the archive. A permalink at a fixed commit keeps them resolving. Signed-off-by: znerol2 <6800371+znerol2@users.noreply.github.com> --- README.md | 2 +- docs/ARCHITECTURE.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index faedacf..9aee0be 100644 --- a/README.md +++ b/README.md @@ -162,7 +162,7 @@ docker logs --tail 3 # copy the fresh open http://localhost:80 ``` Canonical spec: -[`DMF Init Bootstrap Container Plan 2026-06-02`](https://github.com/dmfdeploy/dmfdeploy/blob/main/docs/plans/DMF%20Init%20Bootstrap%20Container%20Plan%202026-06-02.md). +[`DMF Init Bootstrap Container Plan 2026-06-02`](https://github.com/dmfdeploy/dmfdeploy/blob/45eb326e973b10e0b52deef290981ceac9bcf5bd/docs/plans/DMF%20Init%20Bootstrap%20Container%20Plan%202026-06-02.md). ### Target node diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index abecd80..41c9a42 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,7 +1,7 @@ # dmf-init — architecture (scaffold) > Canonical spec: -> [`DMF Init Bootstrap Container Plan 2026-06-02`](https://github.com/dmfdeploy/dmfdeploy/blob/main/docs/plans/DMF%20Init%20Bootstrap%20Container%20Plan%202026-06-02.md) +> [`DMF Init Bootstrap Container Plan 2026-06-02`](https://github.com/dmfdeploy/dmfdeploy/blob/45eb326e973b10e0b52deef290981ceac9bcf5bd/docs/plans/DMF%20Init%20Bootstrap%20Container%20Plan%202026-06-02.md) > in the umbrella. This file is a short orientation; the plan is authoritative. ## One-paragraph summary