sam/dev_arc_aws
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update HANDOFF/README for handoff: mesh gate shipped, Docker UX work, no feature queued

Browse source 
Corrects the stale 'mesh gate not built' framing (it shipped across 4 commits, all merged) and documents the Docker setup-script hint + Help page expansion done this session. Leaves a clear next-task list for the picking-up agent: decide on merging claude/youthful-cerf-ibvxfb, then check with the user for the next priority.
This commit is contained in:
Claude 2026-06-21 08:30:00 +00:00
parent 36a79abe94
commit 5703f93027
No known key found for this signature in database
2 changed files with 24 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
HANDOFF.md
View file

@ -1,6 +1,6 @@
# ArchNest — Handoff Notes
Status snapshot as of **2026-06-20**. Written so a fresh AI session (or human) can pick this up with zero prior context. Branch names rotate every session — always run `git branch --show-current` and work on a fresh feature branch off `main` (recent branches have used a `kiro/<feature>` naming pattern).
Status snapshot as of **2026-06-21**. Written so a fresh AI session (or human) can pick this up with zero prior context. Branch names rotate every session — always run `git branch --show-current` and work on a fresh feature branch off `main` (recent branches have used a `kiro/<feature>` or `claude/<feature>` naming pattern).
## TL;DR
@ -12,8 +12,17 @@ Since then, **Docker container visibility/management was expanded** (shipped, de
- **Persistent SSH terminal sessions** (PR #30) — terminals stay connected across in-app page navigation.
- **Docker-over-SSH management** + **Docker push-agent monitoring** (PR #31) — see the "Docker: three ways" section below.
### → NEXT TASK for the picking-up agent: the **Mesh Prerequisite Gate**
This is **designed but NOT built**. Full design + the 4 open decisions are in **`docs/mesh-prerequisite-gate.md`** — read it first. It requires a NetBird mesh to be configured/tested/verified before the rest of the app can be configured. **The hard part is lockout-safety** (a failed mesh test must never lock the admin out). **Do not start coding until the user answers DECIDE A–D in that doc** (escape-hatch behavior, what "verified" means, member behavior, and crucially whether to default the gate OFF so it doesn't immediately gate the live production instance). Use `AskUserQuestion`.
**The Mesh Prerequisite Gate is now built and shipped** (no longer the open task): NetBird-mesh-required-before-config, with universal CIDR-based verification (not NetBird-specific), a routed-mesh/VPC-peering reachability fallback, and a dedicated "Mesh" section in Settings to configure/test it. Defaults OFF, so it does not lock the live instance. Commits: `46d95fc` (gate), `0409159` (universal CIDR check), `800072f` (routed-mesh fallback), `4a4a5a0` (Settings UI) — all merged to `main`.
Most recently (this session, real user dogfooding rather than a planned feature): walked the user through replacing a broken/insecure Docker-TCP-API integration attempt with a working **SSH Host** integration to a real VM ("Portainer VM," running Portainer + a test container), confirmed Docker-over-SSH container management works end to end, and added supporting UX:
- **Docker setup-script hint in Settings** (commit `628187b`, branch `claude/youthful-cerf-ibvxfb`, **pushed but NOT YET merged to `main`** — user explicitly deferred merging once already; revisit with the user before merging) — when editing a Docker (`type: 'docker'`) integration's `baseUrl`, Settings now renders a copyable systemd-override + `curl` verification script scoped to that exact host/port, so users don't have to hand-derive the remote-API-enablement steps themselves.
- **Help page expansion** (commit `36a79ab`, same branch, pushed) — every page entry in `src/pages/Help.tsx` now has at least one real-world example callout (icon + optional label + scenario text), plus a "New here? Start in this order" quick-start card above the grid, aimed at first-time users who don't yet know which page does what.
### → NEXT TASK for the picking-up agent
No new feature is queued. Pick up from here:
1. **Decide with the user whether to merge `claude/youthful-cerf-ibvxfb` into `main`.** It contains the Docker setup-script hint (`628187b`) and the Help page expansion (`36a79ab`), both already build-clean (`npm run build` passes). Nothing else is blocking it.
2. **Ask the user if removing the unused Docker API integration (the one superseded by the SSH Host setup) is done** — this was a live-instance UI action on their end, not something done via this repo's code.
3. Otherwise, check with the user for the next priority — there is no pending design doc or half-built feature waiting right now (mesh gate and Docker UX work above are both fully shipped or ready-to-merge).
## Standing rules (read before doing anything)
@ -66,6 +75,9 @@ See `TERMIX_MIGRATION.md` for the phase-by-phase record of the original feature
11. **Settings UX fixes** — secret fields show a "· saved" indicator instead of appearing blank/deleted after reload (`secretKeys: string[]` on the integration serializer); SSH host cards default-collapsed if already configured; SSH private-key/cert fields support file upload to avoid paste corruption.
12. **Persistent terminal sessions** (PR #30) — SSH terminal tabs/panes stay connected when you navigate to other pages and back. See `src/lib/TerminalSessionContext.tsx`.
13. **Docker-over-SSH + agent monitoring** (PR #31) — two new ways to see/manage Docker without exposing the Engine TCP socket. See "Docker: three ways" below.
14. **Mesh Prerequisite Gate** (`46d95fc`, `0409159`, `800072f`, `4a4a5a0`) — requires a verified mesh network (universal CIDR check, not NetBird-specific, with a routed-mesh/VPC-peering fallback) before the app can be configured; defaults OFF; configurable/testable from a dedicated Settings → Mesh section.
15. **Docker integration setup-script hint** (`628187b`, on `claude/youthful-cerf-ibvxfb`, not yet merged) — Settings shows a host-specific systemd-override + curl script when configuring a Docker (`type: 'docker'`) integration's `baseUrl`, so enabling the remote Engine API doesn't require looking up the steps elsewhere.
16. **Help page expansion** (`36a79ab`, same branch) — quick-start ordering card + real-world example callouts per page, for first-time users.
## Docker: three ways (PR #31)
@ -122,6 +134,6 @@ Moved to **`ROADMAP.md`** ("Known non-blocking stubs"). Summary: the Infrastruct
1. Read this file, then `ROADMAP.md` (deferred/tiered work), then `docs/` (subsystem design docs — `docker-agent-monitoring.md`, `mesh-prerequisite-gate.md`), then `TERMIX_MIGRATION.md` for feature-level history, then skim `git log --oneline -30`.
2. Frontend: prefer `npm run build` (`tsc -b && vite build`) over a plain `tsc --noEmit` (stricter, catches more). Backend: `npx tsc --noEmit -p .` from `backend/`. Both must pass before any commit.
3. **The next planned feature is the Mesh Prerequisite Gate** — designed in `docs/mesh-prerequisite-gate.md`, NOT built. It has open decisions (A–D) that **must be answered by the user before coding** (especially DECIDE D: defaulting the gate OFF so it doesn't lock the live production instance). Auth Phases 1-3 are done; Phase 4 SSO is a deferred paid AWS add-on (`ROADMAP.md`).
3. **The Mesh Prerequisite Gate is built and shipped** (Settings → Mesh; defaults OFF). **There is no other planned feature queued right now** — check the "→ NEXT TASK" section above first (merge decision on `claude/youthful-cerf-ibvxfb`), then ask the user for the next priority. Auth Phases 1-3 are done; Phase 4 SSO is a deferred paid AWS add-on (`ROADMAP.md`).
4. If asked to add a feature, follow existing patterns: integration adapters in `backend/src/integrations/`, SSH-backed engines in `backend/src/ssh/`, one route file per feature in `backend/src/routes/`, one `api.ts` entry + page component per frontend feature. Subsystem-level work gets a `docs/` design doc first.
5. For anything ambiguous in scope, use `AskUserQuestion` rather than guessing — that's how the auth phases, the Docker agent tiering, and the mesh-gate decisions were all scoped.

15
README.md
View file

@ -30,15 +30,16 @@ backend routes are built and working — there is no pending/on-hold page.
Auth is feature-complete for self-hosted (Phases 1-3: user menu wiring,
password/sessions/login-log, multi-user roles with a 10-seat cap); Phase 4
(Authentik SSO) is **deferred to a paid AWS add-on** — see `ROADMAP.md`.
Recently shipped: persistent terminal sessions across navigation, and Docker
Recently shipped: persistent terminal sessions across navigation, Docker
container visibility/management three ways (Engine TCP API, `docker` CLI over
SSH, and a read-only push agent — see `docs/docker-agent-monitoring.md`).
SSH, and a read-only push agent — see `docs/docker-agent-monitoring.md`), and
the **Mesh Prerequisite Gate** — a universal CIDR-based mesh-verification
requirement (with a routed-mesh/VPC-peering fallback, not NetBird-specific),
configurable from Settings → Mesh and defaulting OFF so it can't lock the live
instance.
The **next planned feature is the Mesh Prerequisite Gate** — requiring a
verified NetBird mesh before the app can be configured. It is **designed but
not built** (`docs/mesh-prerequisite-gate.md`) and has open decisions that need
the user's sign-off before coding (notably defaulting it OFF so it can't lock
the live instance). See `HANDOFF.md` for where to resume.
There is no feature currently in progress. See `HANDOFF.md` for the latest
status and next steps.
If you're a fresh AI session: read this file, then `HANDOFF.md` (current
task state + standing workflow rules), then `design-decisions.md` (visual