remo-cli 4.2.0__tar.gz → 4.3.1__tar.gz

remo_cli-4.3.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "4.3.1"
+}

{remo_cli-4.2.0 → remo_cli-4.3.1}/AGENTS.md

@@ -31,6 +31,7 @@ Principles I, IV, and VIII are machine-enforced — see [Quality Gates](#quality
 - `core/registry.py`: stdlib `json` (format), `fcntl` (advisory locking via a `registry.lock` sidecar), `os.replace` (atomic writes). No new runtime deps. Setup API mirror payload moved to v2 (`contracts/mirror-payload-v2.md`) with a `payload_versions` capability handshake; an upgraded service still accepts v1 payloads. (015-registry-v2)
 - `core/reconcile.py`: provider-agnostic sync-reconcile engine (`SyncScope`, `DiscoveredHost`, `ProbeResult`, `build_plan` (pure), `render_plan`, the consent gate, `apply_plan` via the existing `mutate_registry()`, and the `run_sync` driver). No new runtime deps — stdlib only, built on `core/registry.py`/`core/output.py` as-is. (016-sync-reconcile)
 - `core/web_adopt.py` is now the single unified push engine (`run_push`; `run_adopt` is a thin deprecated alias) — first push adopts, later pushes re-sync, plus best-effort `remo-web@` revocation on removal, `--force` full re-authorization, and multi-workstation flap detection against the service's mirror-generation marker. `core/web_drift.py`: new stdlib-only offline registry-vs-push-cache diff (`diff_registry_against_cache`, `select_deployment`, `render_drift`) powering `remo web status` and the shared `out_of_date_notice()`/`emit_out_of_date_notice()` post-mutation nudge (importable without the `web` extra). Push cache bumped to `cache_version: 3` (`~/.config/remo/web-service.json`: per-deployment `{mirror_generation, instances}`, each instance retaining a non-secret connection tuple for revocation). Service side: `web/api/setup.py` writes/serves a `web-identity/mirror-meta.json` marker (generation + last-push descriptor) additively on `/setup/{status,registry}`; `web/state.py` mode detection fixed so a personal `~/.ssh/id_*` no longer forces `mount_configured` (non-writable `REMO_HOME` is the authoritative signal) with a new `REMO_WEB_MODE` override in `web/config.py`. No new runtime deps; no registry schema change. (017-web-adopt-simplify)
+- No new runtime deps and no registry schema change. `ansible/ssh_configure.yml` is the first playbook to plumb an SSH **port** at all (`ansible_port` appeared nowhere in the repo before) and the first to take an identity from the registry rather than hardcoding `~/.ssh/id_rsa`; both arrive as namespaced `remo_ssh_*` extra-vars so no `ansible_*` name is ever emitted at extra-var precedence. `core/known_hosts.py` gains `guard_added_ssh_host_only`; `core/web_adopt.py` gains `known_hosts_lookup_key` and a `port=` parameter on `scan_and_verify_host_key`. Host key checking is inherited from `ansible.cfg` (disabled repo-wide) — a play-level override is impossible, since `ssh_common_args` is appended after `ssh_args` and ssh honours the first occurrence. (022-configure-added-hosts)
 - No new runtime deps or registry schema change. `pyproject.toml`'s existing `hcloud`/`boto3`/`httpx2` entries gained consumer-attribution comments; `tests/unit/test_docs_structure.py` is a new stdlib-only pytest module (parses the structure diagram below, no new dependency). (019-hygiene-deps-docs)
 - No new runtime deps; no registry schema change (the `host_user`/`node_user` JSON keys already matched the new flag spellings). Superseded for Proxmox by the `--node-user` → `--host-user` rename: both host-scoped providers now spell the node/host login `--host-user`/`host_user` on the CLI, in the provider kwargs and in `registry.json`; `core/registry.py` still reads a legacy `proxmox.node_user` key so pre-rename registries load unchanged and migrate on the next write. `core/provider_registry.py` gains `ArgumentSpec` (positional-argument metadata) and `CommandSpec.target`; `ProviderDescriptor.update_options` is replaced by `upgrade_options`/`resize_dimensions`/`resize_options`/`tag_options`/`host_commands`. `cli/providers/factory.py` gains `_build_upgrade`/`_build_resize`/`_build_tag`/`_build_host_group` (dropping `_build_update` and flat-mounted `bootstrap`). (021-cli-plane-separation)
 
@@ -48,7 +49,7 @@ src/remo_cli/              # Python CLI package (src layout, hatchling build)
 │   ├── main.py            # Root CLI group; mounts one group per remo_cli.core.provider_registry.all_descriptors()
 │   ├── shell.py           # remo shell — registry-dispatched update_entry() (delegates to upgrade()); prompt names the exact `remo <type> upgrade <name>` it will run; unknown type/ssh handled explicitly (no silent no-op)
 │   ├── cp.py              # remo cp
-│   ├── added.py           # remo add / remo remove — provider-neutral SSH host registration (feature 014)
+│   ├── added.py           # remo add / remo remove / remo configure — provider-neutral SSH host registration (014) and configure (022)
 │   ├── web.py             # remo web {serve,check,push,status,adopt} — serve/check lazy-import remo_cli.web.* (NFR-008); push/status/adopt use core/web_adopt + core/web_drift only (adopt is a deprecated alias for push)
 │   └── providers/
 │       └── factory.py     # build_provider_group(descriptor) generates create/destroy/upgrade/resize/list/info/sync/snapshot for every provider, plus tag (iff supports_managed_marker) and a host subgroup (iff host_commands non-empty) — the four hand-written per-provider CLI modules are gone
@@ -61,7 +62,7 @@ src/remo_cli/              # Python CLI package (src layout, hatchling build)
 │   ├── hetzner_descriptor.py  # metadata-only ProviderDescriptor declaration, no SDK imports
 │   ├── aws_descriptor.py      # metadata-only ProviderDescriptor declaration, no SDK imports
 │   ├── proxmox_descriptor.py  # metadata-only ProviderDescriptor declaration, no SDK imports
-│   ├── added.py            # Business logic for remo add / remo remove — provider-neutral SSH host registration (feature 014)
+│   ├── added.py            # Business logic for remo add / remo remove / remo configure — registration (014) + generic configure play (022)
 │   └── builtin.py         # registers the four built-in descriptors; lazily auto-imported by provider_registry on first lookup
 ├── core/                  # Shared utilities (no provider knowledge)
 │   ├── config.py          # REMO_HOME, paths, read-only registry accessor
@@ -133,6 +134,9 @@ ansible/                   # Ansible playbooks (invoked by Python via subprocess
 │       └── templates/
 │           └── remo-host.sh.j2   # Versioned `remo-host` command (capabilities/sessions/attach)
 ├── incus_bootstrap.yml
+├── ssh_configure.yml      # Generic configure play for `remo add` hosts (022): maps remo_ssh_*
+│                          #   -> ansible_port/ansible_ssh_private_key_file, binds remo_user to the
+│                          #   registered account, reuses tasks/configure_dev_tools.yml
 └── requirements.yml
 
 scripts/                   # Repo-root utility scripts (not part of the installed package)
@@ -315,9 +319,9 @@ checking nothing.
 - Ansible 2.14+ / YAML: Follow standard conventions plus Constitution principles
 
 ## Recent Changes
+- 022-configure-added-hosts: Made manually-added SSH hosts first-class by giving them the one thing `remo add` (014) never did — a configure path. New provider-neutral `remo configure NAME` runs a new generic `ansible/ssh_configure.yml` against a registry `type="ssh"` entry, so an added host finally gets `remo-host`/zellij/`project-launch` and stops sitting in the `remo web` rail permanently badged `no_remo_host` with zero session targets. **No refactor of the four provider plays**: the role list was already shared via `tasks/configure_dev_tools.yml`, so a fifth playbook inherits the whole toolchain — the change is purely additive. The new play is two plays: a `localhost` play that asserts (never defaults) `remo_ssh_host`/`remo_ssh_user`/`remo_ssh_port` and `add_host`s them onto `ansible_host`/`ansible_user`/`ansible_port`/`ansible_ssh_private_key_file`, then a play targeting that named group (NOT `hosts: all`, which would pick up `inventory/hosts.yml`'s `hetzner_server` and whose zero-host case exits rc 0 — a silent false success). Four decisions the tests pin, each defending a *silent* failure: the identity is `| default(omit)`, never `'~/.ssh/id_rsa'` (aws_configure.yml's anti-pattern — a path default offers the WRONG key); it is paired with an explicit `-o IdentitiesOnly=yes`, which ansible-core does not add for `private_key_file` (without it a busy agent hits MaxAuthTries and dies "Too many authentication failures" while the passed key is never tried); both `raw` pre-flight probes (python3, `sudo -n true`) set `become: false`, since `ansible.cfg` sets `become = True` globally and a sudo probe run THROUGH sudo proves nothing; and `remo_user` is bound to `remo_ssh_user` rather than `group_vars/all.yml`'s `"remo"` — everything `user_setup` installs lands in `/home/{{ remo_user }}/.local/bin` and discovery logs in as the REGISTERED user, so the default would install `remo-host` into a second account and leave the console still reporting `no_remo_host` after a "successful" configure (it also skips the UID-1000 displacement, which only fires when 1000's holder is someone else). Root is refused (UID-1000 pin), the prompt defaults to no, and remo never reboots a host it did not provision — it reports via the task NAME, since `_filter_line` suppresses `debug` bodies. `core/known_hosts.py` gains `guard_added_ssh_host_only`, the mirror of `guard_not_added_ssh_host`: a provider host is refused naming `remo <type> upgrade NAME`, because the five configure plays are not interchangeable and a mis-target would succeed while configuring wrongly. **Bug fix in the same change** (`core/web_adopt.py`): `remo web push` hardcoded port 22 in `scan_and_verify_host_key`'s `ssh-keyscan` and `_lookup_trusted_keys`' `ssh-keygen -F`, so an added host on another port was reported `skipped/unreachable` — `authorize_service_key` never ran — with a remediation blaming a host that was reachable, or, worse, a different machine answering on 22 had its keys pushed. New `known_hosts_lookup_key()` follows OpenSSH's record form (bare for 22, `[host]:port` otherwise; verified against the real binary — neither direction is forgiving), and `-p` is omitted for 22 so every provider host's argv is byte-identical. `providers/added.py`'s `_reject_unsafe_field` now also rejects Jinja delimiters (registry values become extra-vars, which Ansible templates on the CONTROL NODE), re-checked on the configure read path so pre-existing entries are covered. `web/discovery.py`'s `no_remo_host` remediation now names the real command per host type instead of "re-run configure", which for an added host pointed at nothing. No registry schema change; no new runtime deps.
 - 021-cli-plane-separation: Split the three-intent `remo <provider> update` verb into three single-intent verbs — `upgrade` (in-instance configure play only, zero provider-side writes, SC-001), `resize` (resource change only — the factory rejects a dimensionless invocation with a `PreconditionError` listing that provider's dimension flags, before dispatching to the provider), and `tag` (managed-marker write only, generated iff `supports_managed_marker`; read-before-write no-op when already tagged, `OperationFailedError` — not `create`'s warn-and-continue — on write failure, SC-002) — and moved `bootstrap` off the flat instance plane into a new descriptor-driven `host` subgroup (`remo {incus,proxmox} host bootstrap`, generated iff `host_commands` is non-empty; `CommandSpec` gained a `target: ArgumentSpec | None` field so host commands take the host positionally — incus optional/defaults to localhost, proxmox required). `core/provider_registry.py`: `ProviderDescriptor.update_options` removed, replaced by `upgrade_options`/`resize_dimensions`/`resize_options`/`tag_options`/`host_commands`; new `ArgumentSpec` dataclass. `cli/providers/factory.py`: `_build_update` replaced by `_build_upgrade`/`_build_resize`/`_build_tag`/`_build_host_group`; `_instance_argument` grew a `param` kwarg so the new verbs take `NAME` positionally (matching the provider impl's `name` kwarg) while `create`/`destroy`/`info` keep `--name`; `_resolve_entry_for_destroy`'s user-hint lookup is now descriptor-driven (reads `kwargs` under the `registry_fields` JSON key ending in `_user`) instead of a `"user"` literal. Every provider module split `update()` into `upgrade()`/`resize()`/`tag()` (marker-supporting providers only) reusing existing private helpers unchanged; `update_entry()` (the `remo shell` tools-update path) now delegates to `upgrade()`. Renamed `--user` → `--host-user` (incus) / `--node-user` (proxmox) everywhere it appears (`remo add --user`, a different flag, is unchanged). Made every printed remedy truthful (SC-003): the registry-migration tagging notice and `sync`'s "Mark permanently:" line now recommend `tag` (previously wrongly recommended `sync`/`update`, which never wrote the marker); `remo shell`'s version-mismatch prompt now names the exact `remo <type> upgrade <name>` command it will run. Breaking change, no shim, no registry schema change: `remo <type> update`, flat `bootstrap`, and the old `--user` spelling are all Click "unknown command"/"no such option" errors post-change. FakeProvider's descriptor gained `upgrade_options`/`resize_dimensions`/`tag_options`/one `host_commands` entry, proving the full new surface is descriptor-only (SC-005).
 - 020-openapi-type-generation: Made the FastAPI service the machine-checked source of truth for every shape the browser console consumes, and made drift a build failure with an actionable message — three moves, in dependency order. **(1) Contract completeness, declaration-only** (not one serialized byte moves): `web/api/hosts.py` annotates `InstanceOut.status`/`SessionTargetOut.zellij_state`/`devcontainer_running` with the existing closed domain enums (dropping the `.value` unwrapping — a `str`-Enum serializes identically) and adds `KnownProviderType(str, Enum)` (`incus`/`hetzner`/`aws`/`proxmox`, fixed to the built-in set per FR-004a — never derived from the live `provider_registry`, so a third-party provider install can't perturb the artifact) typed `KnownProviderType | str` (`anyOf[$ref, string]`, keeping the wire field open); new `ErrorEnvelope`/`HealthResponse`/`ReadinessResponse`/`MintPairingResponse`/`DetailResponse` response models declare what four previously-untyped routes (`/health`, `/ready`, `/pairing/mint`, `POST /terminals`) already return, with the `{"error": {...}}` envelope declared only on routes that actually return it (never on `pairing.py`, whose 403 is `{"detail": ...}`). **(2) Generate and consume**: new stdlib `scripts/export_openapi.py` exports `frontend/src/api/generated/openapi.json` (`create_app().openapi()`, `sort_keys=True` + trailing newline for byte-reproducibility) and `terminal-frames.json` (a new `web/frames.py`: six Pydantic control-frame models + `InboundFrame`/`OutboundFrame` discriminated unions, wrapped via `TypeAdapter(...).json_schema()` in a `{protocol: "remo-terminal.v1", frame_version: 1, ...}` envelope that versions independently of the REST contract); `openapi-typescript` v7 (exact-pinned frontend devDependency) generates `schema.d.ts`, and a small synthetic-OpenAPI wrapper (`frontend/scripts/generate-frame-types.mjs`) generates `terminal-frames.d.ts` (openapi-typescript itself only accepts genuine OpenAPI documents). `web/api/terminals.py`'s five ad-hoc `{"v": 1, ...}` WS control-frame dict literals are gone, replaced by typed `frames.py` model construction/validation — `_handle_control`'s silent-drop behavior for malformed JSON, non-object payloads, and unknown frame types is preserved exactly (the one place this refactor could have changed runtime behavior; dedicated tests cover it). `frontend/src/api/client.ts` replaced ~12 hand-declared service-shaped interfaces with `components["schemas"][...]` aliases (console-owned shapes — `ApiError`, `ServiceStatus`, the forward-auth re-auth path — stay hand-written); `frontend/src/components/providerMeta.ts` now keys a `Record<InstanceStatus | KnownProviderType, ...>` off the generated unions, so a new enum member is a compile error at the presentation mapping while an off-union runtime value still renders via a preserved fallback (FR-013a — deleting that fallback to "achieve exhaustiveness" is explicitly wrong). **(3) Gate it**: three drift checks modeled on `tests/unit/test_docs_structure.py`'s established shape (name the artifact, group findings by kind, close with the exact regeneration command and a dependency-bump note) — `tests/unit/test_schema_drift.py` (REST + frame freshness against the live Python app, `test` CI job) and `frontend/scripts/check-types-fresh.mjs` (regenerated `.d.ts` vs. checked-in, `frontend` CI job) — fail, never skip, and never write a tracked file. New `docs/maintaining-generated-types.md` documents the four generated artifacts (never hand-edited; internal build input, no external compatibility promise, FR-029) and how to read a failure. No registry schema change; no new service runtime dependency.
-- 019-hygiene-deps-docs: Repository hygiene pass across dependencies, dead code, and documentation — no behavior change except one deliberate CLI break. Annotated every dependency whose necessity isn't visible from `src/remo_cli/` imports alone (`hcloud`/`boto3` in `pyproject.toml` now name their real consumers — the Ansible `hetzner.hcloud`/`amazon.aws`/`community.aws` collections — and stay unconditional pending issue #94; the `httpx2` dev-extra comment clarifies it's a real pydantic package, not a typo) and annotated two currently-unreachable missing-boto3 code paths in `providers/aws.py` rather than deleting them. Removed the phantom `remo init` command from every doc surface (README, docs/aws.md, install.sh, CONTRIBUTING.md) — Ansible collections install automatically on first provider command via `core/ansible_runner.py::_ensure_collections`. Corrected this file's structure diagram, Commands, and Active Technologies sections to match the real tree (removed two phantom entries, documented 13 previously-undocumented modules, dropped two nonexistent `--extra` install commands) and rewrote `AGENTS.md`, which had described an unrelated project. Added `tests/unit/test_docs_structure.py`, a new CI-gating pytest module (stdlib-only, no new dependency) that parses both files' structure diagrams and fails the build on drift, naming the offending paths; `docs/maintaining-claude-md.md` documents the fix procedure. Deleted the dead `providers/proxmox.py::_parse_pct_json` (zero call sites) and its orphaned `import json`. Consolidated all four of `providers/hetzner.py`'s hand-rolled `urllib.request.Request` call sites onto the module's existing `_hetzner_api()` helper, preserving each site's distinct raise-vs-swallow/timeout/message-text contract exactly (`tests/unit/providers/test_hetzner_http.py` characterizes and pins the behavior). **Breaking change**: removed the `--yes`/`-y` flag from `remo <provider> create` on all four providers — it never had any effect (creation has no confirmation prompt); `--yes` is unchanged on `destroy`, `sync`, `snapshot restore`, `snapshot delete`, and `remo remove`.
 Only the newest three entries live here — `update-agent-context.sh` discards the rest on every run. The complete history is archived in [`docs/feature-history.md`](docs/feature-history.md); move displaced entries there rather than letting the generator drop them.
 
 

{remo_cli-4.2.0 → remo_cli-4.3.1}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [4.3.1](https://github.com/get2knowio/remo/compare/v4.3.0...v4.3.1) (2026-08-05)
+
+
+### Bug Fixes
+
+* three defects found while building `remo configure` ([#144](https://github.com/get2knowio/remo/issues/144)) ([608a914](https://github.com/get2knowio/remo/commit/608a9146560b9e1bf0e45811ce76a0c517dafa45))
+
+## [4.3.0](https://github.com/get2knowio/remo/compare/v4.2.0...v4.3.0) (2026-08-05)
+
+
+### Features
+
+* **cli:** configure manually-added SSH hosts with `remo configure` ([#143](https://github.com/get2knowio/remo/issues/143)) ([4a34f70](https://github.com/get2knowio/remo/commit/4a34f70674f9afd85f92529ac119cc97a015f3a0))
+
+
+### Bug Fixes
+
+* **web:** stop three light themes printing invisible text ([#141](https://github.com/get2knowio/remo/issues/141)) ([a1c2bea](https://github.com/get2knowio/remo/commit/a1c2bea06c13503fe6c623f2f18483c862c20b46))
+
 ## [4.2.0](https://github.com/get2knowio/remo/compare/v4.1.0...v4.2.0) (2026-08-05)
 
 

{remo_cli-4.2.0 → remo_cli-4.3.1}/CLAUDE.md

@@ -31,6 +31,7 @@ Principles I, IV, and VIII are machine-enforced — see [Quality Gates](#quality
 - `core/registry.py`: stdlib `json` (format), `fcntl` (advisory locking via a `registry.lock` sidecar), `os.replace` (atomic writes). No new runtime deps. Setup API mirror payload moved to v2 (`contracts/mirror-payload-v2.md`) with a `payload_versions` capability handshake; an upgraded service still accepts v1 payloads. (015-registry-v2)
 - `core/reconcile.py`: provider-agnostic sync-reconcile engine (`SyncScope`, `DiscoveredHost`, `ProbeResult`, `build_plan` (pure), `render_plan`, the consent gate, `apply_plan` via the existing `mutate_registry()`, and the `run_sync` driver). No new runtime deps — stdlib only, built on `core/registry.py`/`core/output.py` as-is. (016-sync-reconcile)
 - `core/web_adopt.py` is now the single unified push engine (`run_push`; `run_adopt` is a thin deprecated alias) — first push adopts, later pushes re-sync, plus best-effort `remo-web@` revocation on removal, `--force` full re-authorization, and multi-workstation flap detection against the service's mirror-generation marker. `core/web_drift.py`: new stdlib-only offline registry-vs-push-cache diff (`diff_registry_against_cache`, `select_deployment`, `render_drift`) powering `remo web status` and the shared `out_of_date_notice()`/`emit_out_of_date_notice()` post-mutation nudge (importable without the `web` extra). Push cache bumped to `cache_version: 3` (`~/.config/remo/web-service.json`: per-deployment `{mirror_generation, instances}`, each instance retaining a non-secret connection tuple for revocation). Service side: `web/api/setup.py` writes/serves a `web-identity/mirror-meta.json` marker (generation + last-push descriptor) additively on `/setup/{status,registry}`; `web/state.py` mode detection fixed so a personal `~/.ssh/id_*` no longer forces `mount_configured` (non-writable `REMO_HOME` is the authoritative signal) with a new `REMO_WEB_MODE` override in `web/config.py`. No new runtime deps; no registry schema change. (017-web-adopt-simplify)
+- No new runtime deps and no registry schema change. `ansible/ssh_configure.yml` is the first playbook to plumb an SSH **port** at all (`ansible_port` appeared nowhere in the repo before) and the first to take an identity from the registry rather than hardcoding `~/.ssh/id_rsa`; both arrive as namespaced `remo_ssh_*` extra-vars so no `ansible_*` name is ever emitted at extra-var precedence. `core/known_hosts.py` gains `guard_added_ssh_host_only`; `core/web_adopt.py` gains `known_hosts_lookup_key` and a `port=` parameter on `scan_and_verify_host_key`. Host key checking is inherited from `ansible.cfg` (disabled repo-wide) — a play-level override is impossible, since `ssh_common_args` is appended after `ssh_args` and ssh honours the first occurrence. (022-configure-added-hosts)
 - No new runtime deps or registry schema change. `pyproject.toml`'s existing `hcloud`/`boto3`/`httpx2` entries gained consumer-attribution comments; `tests/unit/test_docs_structure.py` is a new stdlib-only pytest module (parses the structure diagram below, no new dependency). (019-hygiene-deps-docs)
 - No new runtime deps; no registry schema change (the `host_user`/`node_user` JSON keys already matched the new flag spellings). Superseded for Proxmox by the `--node-user` → `--host-user` rename: both host-scoped providers now spell the node/host login `--host-user`/`host_user` on the CLI, in the provider kwargs and in `registry.json`; `core/registry.py` still reads a legacy `proxmox.node_user` key so pre-rename registries load unchanged and migrate on the next write. `core/provider_registry.py` gains `ArgumentSpec` (positional-argument metadata) and `CommandSpec.target`; `ProviderDescriptor.update_options` is replaced by `upgrade_options`/`resize_dimensions`/`resize_options`/`tag_options`/`host_commands`. `cli/providers/factory.py` gains `_build_upgrade`/`_build_resize`/`_build_tag`/`_build_host_group` (dropping `_build_update` and flat-mounted `bootstrap`). (021-cli-plane-separation)
 
@@ -48,7 +49,7 @@ src/remo_cli/              # Python CLI package (src layout, hatchling build)
 │   ├── main.py            # Root CLI group; mounts one group per remo_cli.core.provider_registry.all_descriptors()
 │   ├── shell.py           # remo shell — registry-dispatched update_entry() (delegates to upgrade()); prompt names the exact `remo <type> upgrade <name>` it will run; unknown type/ssh handled explicitly (no silent no-op)
 │   ├── cp.py              # remo cp
-│   ├── added.py           # remo add / remo remove — provider-neutral SSH host registration (feature 014)
+│   ├── added.py           # remo add / remo remove / remo configure — provider-neutral SSH host registration (014) and configure (022)
 │   ├── web.py             # remo web {serve,check,push,status,adopt} — serve/check lazy-import remo_cli.web.* (NFR-008); push/status/adopt use core/web_adopt + core/web_drift only (adopt is a deprecated alias for push)
 │   └── providers/
 │       └── factory.py     # build_provider_group(descriptor) generates create/destroy/upgrade/resize/list/info/sync/snapshot for every provider, plus tag (iff supports_managed_marker) and a host subgroup (iff host_commands non-empty) — the four hand-written per-provider CLI modules are gone
@@ -61,7 +62,7 @@ src/remo_cli/              # Python CLI package (src layout, hatchling build)
 │   ├── hetzner_descriptor.py  # metadata-only ProviderDescriptor declaration, no SDK imports
 │   ├── aws_descriptor.py      # metadata-only ProviderDescriptor declaration, no SDK imports
 │   ├── proxmox_descriptor.py  # metadata-only ProviderDescriptor declaration, no SDK imports
-│   ├── added.py            # Business logic for remo add / remo remove — provider-neutral SSH host registration (feature 014)
+│   ├── added.py            # Business logic for remo add / remo remove / remo configure — registration (014) + generic configure play (022)
 │   └── builtin.py         # registers the four built-in descriptors; lazily auto-imported by provider_registry on first lookup
 ├── core/                  # Shared utilities (no provider knowledge)
 │   ├── config.py          # REMO_HOME, paths, read-only registry accessor
@@ -134,6 +135,9 @@ ansible/                   # Ansible playbooks (invoked by Python via subprocess
 │       └── templates/
 │           └── remo-host.sh.j2   # Versioned `remo-host` command (capabilities/sessions/attach)
 ├── incus_bootstrap.yml
+├── ssh_configure.yml      # Generic configure play for `remo add` hosts (022): maps remo_ssh_*
+│                          #   -> ansible_port/ansible_ssh_private_key_file, binds remo_user to the
+│                          #   registered account, reuses tasks/configure_dev_tools.yml
 └── requirements.yml
 
 scripts/                   # Repo-root utility scripts (not part of the installed package)
@@ -316,9 +320,9 @@ checking nothing.
 - Ansible 2.14+ / YAML: Follow standard conventions plus Constitution principles
 
 ## Recent Changes
+- 022-configure-added-hosts: Made manually-added SSH hosts first-class by giving them the one thing `remo add` (014) never did — a configure path. New provider-neutral `remo configure NAME` runs a new generic `ansible/ssh_configure.yml` against a registry `type="ssh"` entry, so an added host finally gets `remo-host`/zellij/`project-launch` and stops sitting in the `remo web` rail permanently badged `no_remo_host` with zero session targets. **No refactor of the four provider plays**: the role list was already shared via `tasks/configure_dev_tools.yml`, so a fifth playbook inherits the whole toolchain — the change is purely additive. The new play is two plays: a `localhost` play that asserts (never defaults) `remo_ssh_host`/`remo_ssh_user`/`remo_ssh_port` and `add_host`s them onto `ansible_host`/`ansible_user`/`ansible_port`/`ansible_ssh_private_key_file`, then a play targeting that named group (NOT `hosts: all`, which would pick up `inventory/hosts.yml`'s `hetzner_server` and whose zero-host case exits rc 0 — a silent false success). Four decisions the tests pin, each defending a *silent* failure: the identity is `| default(omit)`, never `'~/.ssh/id_rsa'` (aws_configure.yml's anti-pattern — a path default offers the WRONG key); it is paired with an explicit `-o IdentitiesOnly=yes`, which ansible-core does not add for `private_key_file` (without it a busy agent hits MaxAuthTries and dies "Too many authentication failures" while the passed key is never tried); both `raw` pre-flight probes (python3, `sudo -n true`) set `become: false`, since `ansible.cfg` sets `become = True` globally and a sudo probe run THROUGH sudo proves nothing; and `remo_user` is bound to `remo_ssh_user` rather than `group_vars/all.yml`'s `"remo"` — everything `user_setup` installs lands in `/home/{{ remo_user }}/.local/bin` and discovery logs in as the REGISTERED user, so the default would install `remo-host` into a second account and leave the console still reporting `no_remo_host` after a "successful" configure (it also skips the UID-1000 displacement, which only fires when 1000's holder is someone else). Root is refused (UID-1000 pin), the prompt defaults to no, and remo never reboots a host it did not provision — it reports via the task NAME, since `_filter_line` suppresses `debug` bodies. `core/known_hosts.py` gains `guard_added_ssh_host_only`, the mirror of `guard_not_added_ssh_host`: a provider host is refused naming `remo <type> upgrade NAME`, because the five configure plays are not interchangeable and a mis-target would succeed while configuring wrongly. **Bug fix in the same change** (`core/web_adopt.py`): `remo web push` hardcoded port 22 in `scan_and_verify_host_key`'s `ssh-keyscan` and `_lookup_trusted_keys`' `ssh-keygen -F`, so an added host on another port was reported `skipped/unreachable` — `authorize_service_key` never ran — with a remediation blaming a host that was reachable, or, worse, a different machine answering on 22 had its keys pushed. New `known_hosts_lookup_key()` follows OpenSSH's record form (bare for 22, `[host]:port` otherwise; verified against the real binary — neither direction is forgiving), and `-p` is omitted for 22 so every provider host's argv is byte-identical. `providers/added.py`'s `_reject_unsafe_field` now also rejects Jinja delimiters (registry values become extra-vars, which Ansible templates on the CONTROL NODE), re-checked on the configure read path so pre-existing entries are covered. `web/discovery.py`'s `no_remo_host` remediation now names the real command per host type instead of "re-run configure", which for an added host pointed at nothing. No registry schema change; no new runtime deps.
 - 021-cli-plane-separation: Split the three-intent `remo <provider> update` verb into three single-intent verbs — `upgrade` (in-instance configure play only, zero provider-side writes, SC-001), `resize` (resource change only — the factory rejects a dimensionless invocation with a `PreconditionError` listing that provider's dimension flags, before dispatching to the provider), and `tag` (managed-marker write only, generated iff `supports_managed_marker`; read-before-write no-op when already tagged, `OperationFailedError` — not `create`'s warn-and-continue — on write failure, SC-002) — and moved `bootstrap` off the flat instance plane into a new descriptor-driven `host` subgroup (`remo {incus,proxmox} host bootstrap`, generated iff `host_commands` is non-empty; `CommandSpec` gained a `target: ArgumentSpec | None` field so host commands take the host positionally — incus optional/defaults to localhost, proxmox required). `core/provider_registry.py`: `ProviderDescriptor.update_options` removed, replaced by `upgrade_options`/`resize_dimensions`/`resize_options`/`tag_options`/`host_commands`; new `ArgumentSpec` dataclass. `cli/providers/factory.py`: `_build_update` replaced by `_build_upgrade`/`_build_resize`/`_build_tag`/`_build_host_group`; `_instance_argument` grew a `param` kwarg so the new verbs take `NAME` positionally (matching the provider impl's `name` kwarg) while `create`/`destroy`/`info` keep `--name`; `_resolve_entry_for_destroy`'s user-hint lookup is now descriptor-driven (reads `kwargs` under the `registry_fields` JSON key ending in `_user`) instead of a `"user"` literal. Every provider module split `update()` into `upgrade()`/`resize()`/`tag()` (marker-supporting providers only) reusing existing private helpers unchanged; `update_entry()` (the `remo shell` tools-update path) now delegates to `upgrade()`. Renamed `--user` → `--host-user` (incus) / `--node-user` (proxmox) everywhere it appears (`remo add --user`, a different flag, is unchanged). Made every printed remedy truthful (SC-003): the registry-migration tagging notice and `sync`'s "Mark permanently:" line now recommend `tag` (previously wrongly recommended `sync`/`update`, which never wrote the marker); `remo shell`'s version-mismatch prompt now names the exact `remo <type> upgrade <name>` command it will run. Breaking change, no shim, no registry schema change: `remo <type> update`, flat `bootstrap`, and the old `--user` spelling are all Click "unknown command"/"no such option" errors post-change. FakeProvider's descriptor gained `upgrade_options`/`resize_dimensions`/`tag_options`/one `host_commands` entry, proving the full new surface is descriptor-only (SC-005).
 - 020-openapi-type-generation: Made the FastAPI service the machine-checked source of truth for every shape the browser console consumes, and made drift a build failure with an actionable message — three moves, in dependency order. **(1) Contract completeness, declaration-only** (not one serialized byte moves): `web/api/hosts.py` annotates `InstanceOut.status`/`SessionTargetOut.zellij_state`/`devcontainer_running` with the existing closed domain enums (dropping the `.value` unwrapping — a `str`-Enum serializes identically) and adds `KnownProviderType(str, Enum)` (`incus`/`hetzner`/`aws`/`proxmox`, fixed to the built-in set per FR-004a — never derived from the live `provider_registry`, so a third-party provider install can't perturb the artifact) typed `KnownProviderType | str` (`anyOf[$ref, string]`, keeping the wire field open); new `ErrorEnvelope`/`HealthResponse`/`ReadinessResponse`/`MintPairingResponse`/`DetailResponse` response models declare what four previously-untyped routes (`/health`, `/ready`, `/pairing/mint`, `POST /terminals`) already return, with the `{"error": {...}}` envelope declared only on routes that actually return it (never on `pairing.py`, whose 403 is `{"detail": ...}`). **(2) Generate and consume**: new stdlib `scripts/export_openapi.py` exports `frontend/src/api/generated/openapi.json` (`create_app().openapi()`, `sort_keys=True` + trailing newline for byte-reproducibility) and `terminal-frames.json` (a new `web/frames.py`: six Pydantic control-frame models + `InboundFrame`/`OutboundFrame` discriminated unions, wrapped via `TypeAdapter(...).json_schema()` in a `{protocol: "remo-terminal.v1", frame_version: 1, ...}` envelope that versions independently of the REST contract); `openapi-typescript` v7 (exact-pinned frontend devDependency) generates `schema.d.ts`, and a small synthetic-OpenAPI wrapper (`frontend/scripts/generate-frame-types.mjs`) generates `terminal-frames.d.ts` (openapi-typescript itself only accepts genuine OpenAPI documents). `web/api/terminals.py`'s five ad-hoc `{"v": 1, ...}` WS control-frame dict literals are gone, replaced by typed `frames.py` model construction/validation — `_handle_control`'s silent-drop behavior for malformed JSON, non-object payloads, and unknown frame types is preserved exactly (the one place this refactor could have changed runtime behavior; dedicated tests cover it). `frontend/src/api/client.ts` replaced ~12 hand-declared service-shaped interfaces with `components["schemas"][...]` aliases (console-owned shapes — `ApiError`, `ServiceStatus`, the forward-auth re-auth path — stay hand-written); `frontend/src/components/providerMeta.ts` now keys a `Record<InstanceStatus | KnownProviderType, ...>` off the generated unions, so a new enum member is a compile error at the presentation mapping while an off-union runtime value still renders via a preserved fallback (FR-013a — deleting that fallback to "achieve exhaustiveness" is explicitly wrong). **(3) Gate it**: three drift checks modeled on `tests/unit/test_docs_structure.py`'s established shape (name the artifact, group findings by kind, close with the exact regeneration command and a dependency-bump note) — `tests/unit/test_schema_drift.py` (REST + frame freshness against the live Python app, `test` CI job) and `frontend/scripts/check-types-fresh.mjs` (regenerated `.d.ts` vs. checked-in, `frontend` CI job) — fail, never skip, and never write a tracked file. New `docs/maintaining-generated-types.md` documents the four generated artifacts (never hand-edited; internal build input, no external compatibility promise, FR-029) and how to read a failure. No registry schema change; no new service runtime dependency.
-- 019-hygiene-deps-docs: Repository hygiene pass across dependencies, dead code, and documentation — no behavior change except one deliberate CLI break. Annotated every dependency whose necessity isn't visible from `src/remo_cli/` imports alone (`hcloud`/`boto3` in `pyproject.toml` now name their real consumers — the Ansible `hetzner.hcloud`/`amazon.aws`/`community.aws` collections — and stay unconditional pending issue #94; the `httpx2` dev-extra comment clarifies it's a real pydantic package, not a typo) and annotated two currently-unreachable missing-boto3 code paths in `providers/aws.py` rather than deleting them. Removed the phantom `remo init` command from every doc surface (README, docs/aws.md, install.sh, CONTRIBUTING.md) — Ansible collections install automatically on first provider command via `core/ansible_runner.py::_ensure_collections`. Corrected this file's structure diagram, Commands, and Active Technologies sections to match the real tree (removed two phantom entries, documented 13 previously-undocumented modules, dropped two nonexistent `--extra` install commands) and rewrote `AGENTS.md`, which had described an unrelated project. Added `tests/unit/test_docs_structure.py`, a new CI-gating pytest module (stdlib-only, no new dependency) that parses both files' structure diagrams and fails the build on drift, naming the offending paths; `docs/maintaining-claude-md.md` documents the fix procedure. Deleted the dead `providers/proxmox.py::_parse_pct_json` (zero call sites) and its orphaned `import json`. Consolidated all four of `providers/hetzner.py`'s hand-rolled `urllib.request.Request` call sites onto the module's existing `_hetzner_api()` helper, preserving each site's distinct raise-vs-swallow/timeout/message-text contract exactly (`tests/unit/providers/test_hetzner_http.py` characterizes and pins the behavior). **Breaking change**: removed the `--yes`/`-y` flag from `remo <provider> create` on all four providers — it never had any effect (creation has no confirmation prompt); `--yes` is unchanged on `destroy`, `sync`, `snapshot restore`, `snapshot delete`, and `remo remove`.
 Only the newest three entries live here — `update-agent-context.sh` discards the rest on every run. The complete history is archived in [`docs/feature-history.md`](docs/feature-history.md); move displaced entries there rather than letting the generator drop them.
 
 

{remo_cli-4.2.0 → remo_cli-4.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remo-cli
-Version: 4.2.0
+Version: 4.3.1
 Summary: Remote development environment CLI
 License-Expression: MIT
 License-File: LICENSE
@@ -286,11 +286,63 @@ as any other host.
 
 ```bash
 remo add mybox 10.0.0.5 --port 2222 --identity ~/.ssh/mybox_ed25519 --verify
+remo configure mybox                # install the dev tools (see below)
 remo shell mybox                    # open a shell over direct SSH
 remo cp ./deploy.sh mybox:/tmp/     # copy a file up
 remo remove mybox                   # deregister when you're done
 ```
 
+### Install the dev tools: `remo configure`
+
+`add` only *registers* a host — it installs nothing. Until you configure it, an
+added host has no `remo-host`, no zellij and no project launcher, so `remo web`
+lists it with an **"update req."** badge and no sessions you can open.
+
+```bash
+remo configure NAME [--only TOOL] [--skip TOOL] [--yes] [-v]
+```
+
+This runs the same Ansible play the providers use, so the host ends up with
+Docker, Node.js, zellij, fzf, the GitHub CLI, the devcontainers CLI and
+`remo-host`. It is idempotent — re-run it any time to refresh the tools, which
+is also how you update a host after upgrading `remo` itself.
+
+Two things worth knowing before the first run:
+
+- It configures **the account you registered** and grants that account
+  passwordless sudo. It also apt-upgrades the system. You are asked to confirm
+  (defaulting to *no*); `--yes` skips the prompt.
+- The host must be Debian/Ubuntu with `python3` and sudo available. Registering
+  as `root` is refused — the workspace account is pinned to UID 1000, which
+  would break the host.
+
+Unlike the provider `create` path, remo **never reboots** a host it did not
+provision; if package updates need one, it tells you and leaves the decision to
+you. For a provider-managed host use `remo <provider> upgrade NAME` instead —
+`remo configure` refuses those and names the right command.
+
+```bash
+remo configure mybox                # first-time setup, or refresh the tools
+remo configure mybox --skip docker  # everything except Docker
+remo web push                       # authorize the web service on it
+```
+
+#### Example: an OrbStack VM
+
+[`docs/examples/orbstack-cloud-init.yaml`](docs/examples/orbstack-cloud-init.yaml)
+prepares an [OrbStack](https://orbstack.dev) VM on a Mac so `remo add` and
+`remo configure` work first time:
+
+```bash
+orb create ubuntu remo-mbp -c docs/examples/orbstack-cloud-init.yaml
+```
+
+It installs only what Ansible needs to connect and hand over — `remo configure`
+does the rest. It deliberately creates no user: OrbStack already makes one named
+after your macOS account holding UID 1000, and registering *that* user is what
+puts `remo-host` in the home directory the web service logs into, while skipping
+`user_setup`'s UID-1000 reassignment entirely.
+
 `remo remove NAME [--yes]` deregisters an added host by deleting **only** the
 local registry entry — it makes no connection to and no change on the remote
 environment (unlike a provider `destroy`, which tears down infrastructure). It
@@ -323,6 +375,8 @@ remo add NAME [user@]host[:port]    # Register a single SSH host
 remo add NAME host --port 2222 --identity ~/.ssh/key   # Custom port + key
 remo add NAME host --verify         # Fail-closed SSH reachability check first
 remo add NAME host --user alice     # Override default SSH user (default: remo)
+remo configure NAME                 # Install/refresh the dev tools on an added host
+remo configure NAME --skip docker   # Skip a tool (repeatable; --only is the inverse)
 remo remove NAME [--yes]            # Deregister an added host (local-only)
 
 # Hetzner Cloud

{remo_cli-4.2.0 → remo_cli-4.3.1}/README.md

@@ -260,11 +260,63 @@ as any other host.
 
 ```bash
 remo add mybox 10.0.0.5 --port 2222 --identity ~/.ssh/mybox_ed25519 --verify
+remo configure mybox                # install the dev tools (see below)
 remo shell mybox                    # open a shell over direct SSH
 remo cp ./deploy.sh mybox:/tmp/     # copy a file up
 remo remove mybox                   # deregister when you're done
 ```
 
+### Install the dev tools: `remo configure`
+
+`add` only *registers* a host — it installs nothing. Until you configure it, an
+added host has no `remo-host`, no zellij and no project launcher, so `remo web`
+lists it with an **"update req."** badge and no sessions you can open.
+
+```bash
+remo configure NAME [--only TOOL] [--skip TOOL] [--yes] [-v]
+```
+
+This runs the same Ansible play the providers use, so the host ends up with
+Docker, Node.js, zellij, fzf, the GitHub CLI, the devcontainers CLI and
+`remo-host`. It is idempotent — re-run it any time to refresh the tools, which
+is also how you update a host after upgrading `remo` itself.
+
+Two things worth knowing before the first run:
+
+- It configures **the account you registered** and grants that account
+  passwordless sudo. It also apt-upgrades the system. You are asked to confirm
+  (defaulting to *no*); `--yes` skips the prompt.
+- The host must be Debian/Ubuntu with `python3` and sudo available. Registering
+  as `root` is refused — the workspace account is pinned to UID 1000, which
+  would break the host.
+
+Unlike the provider `create` path, remo **never reboots** a host it did not
+provision; if package updates need one, it tells you and leaves the decision to
+you. For a provider-managed host use `remo <provider> upgrade NAME` instead —
+`remo configure` refuses those and names the right command.
+
+```bash
+remo configure mybox                # first-time setup, or refresh the tools
+remo configure mybox --skip docker  # everything except Docker
+remo web push                       # authorize the web service on it
+```
+
+#### Example: an OrbStack VM
+
+[`docs/examples/orbstack-cloud-init.yaml`](docs/examples/orbstack-cloud-init.yaml)
+prepares an [OrbStack](https://orbstack.dev) VM on a Mac so `remo add` and
+`remo configure` work first time:
+
+```bash
+orb create ubuntu remo-mbp -c docs/examples/orbstack-cloud-init.yaml
+```
+
+It installs only what Ansible needs to connect and hand over — `remo configure`
+does the rest. It deliberately creates no user: OrbStack already makes one named
+after your macOS account holding UID 1000, and registering *that* user is what
+puts `remo-host` in the home directory the web service logs into, while skipping
+`user_setup`'s UID-1000 reassignment entirely.
+
 `remo remove NAME [--yes]` deregisters an added host by deleting **only** the
 local registry entry — it makes no connection to and no change on the remote
 environment (unlike a provider `destroy`, which tears down infrastructure). It
@@ -297,6 +349,8 @@ remo add NAME [user@]host[:port]    # Register a single SSH host
 remo add NAME host --port 2222 --identity ~/.ssh/key   # Custom port + key
 remo add NAME host --verify         # Fail-closed SSH reachability check first
 remo add NAME host --user alice     # Override default SSH user (default: remo)
+remo configure NAME                 # Install/refresh the dev tools on an added host
+remo configure NAME --skip docker   # Skip a tool (repeatable; --only is the inverse)
 remo remove NAME [--yes]            # Deregister an added host (local-only)
 
 # Hetzner Cloud

{remo_cli-4.2.0 → remo_cli-4.3.1}/ansible/roles/user_setup/tasks/main.yml

@@ -243,11 +243,25 @@
     - user_setup_cloud_keys.content | default('') | length > 0
 # --- end cloud-injected key bootstrap --------------------------------------
 
+# The docker group only exists if the `docker` role ran. Skipping that role
+# (`--skip docker`, or `configure_docker=false`) previously made the next task
+# fail outright with "Group docker does not exist", taking the whole configure
+# down after it had already changed the host — so `--skip docker` was, in
+# effect, not a supported option on any provider. Gate on the group rather than
+# on `configure_docker` so a host where Docker was installed by other means
+# (or by an earlier run) still gets the membership.
+- name: Check whether a docker group exists
+  ansible.builtin.command: getent group docker
+  register: user_setup_docker_group
+  changed_when: false
+  failed_when: false
+
 - name: Add remo user to docker group
   ansible.builtin.user:
     name: "{{ remo_user }}"
     groups: docker
     append: true
+  when: user_setup_docker_group.rc | default(1) == 0
 
 - name: Configure passwordless sudo for remo user
   ansible.builtin.lineinfile:

remo_cli-4.3.1/ansible/ssh_configure.yml

@@ -0,0 +1,240 @@
+---
+# Generic SSH Configure Playbook — install/refresh remo's dev tools on a host
+# that NO provider manages (registry type="ssh", registered via `remo add`).
+#
+# Caller: src/remo_cli/providers/added.py::configure  (`remo configure NAME`)
+#
+# Usage:
+#   ./run.sh ssh_configure.yml \
+#     -e remo_ssh_host=10.0.0.5 -e remo_ssh_user=remo -e remo_ssh_port=2222 \
+#     -e remo_ssh_identity=~/.ssh/k
+#
+# Required variables (the CLI ALWAYS passes all three; none is defaulted here on
+# purpose — a missing port must fail loudly, never quietly fall back to 22):
+#   remo_ssh_host: address of the registered host
+#   remo_ssh_user: SSH user, which is ALSO the account this play configures
+#   remo_ssh_port: SSH port
+#
+# Optional variables:
+#   remo_ssh_identity: private key path. `~` is expanded by the ssh connection
+#     plugin (os.path.expanduser), so no client-side expansion is needed.
+#   configure_docker / configure_user_setup / configure_nodejs /
+#   configure_devcontainers / configure_github_cli / configure_fzf /
+#   configure_zellij: per-tool toggles — see tasks/configure_dev_tools.yml
+#
+# Host key checking is INHERITED from ansible.cfg, which disables it repo-wide
+# (host_key_checking=False AND StrictHostKeyChecking=no in ssh_args). That is a
+# deliberate inheritance, not an oversight: ssh_common_args is appended AFTER
+# ssh_args and ssh honours the first occurrence of an option, so a play-level
+# override here would be silently ignored. Tightening it is a repo-wide change
+# to ansible.cfg across every playbook, not a per-play special case.
+
+- name: Build the inventory for the registered SSH host
+  hosts: localhost
+  connection: local
+  gather_facts: false
+  become: false
+
+  tasks:
+    - name: Validate the connection variables supplied by the CLI
+      ansible.builtin.assert:
+        that:
+          - remo_ssh_host is defined and (remo_ssh_host | string | length) > 0
+          - remo_ssh_user is defined and (remo_ssh_user | string | length) > 0
+          - remo_ssh_port is defined
+          - (remo_ssh_port | int) > 0
+          - (remo_ssh_port | int) < 65536
+        fail_msg: >-
+          ssh_configure.yml needs remo_ssh_host, remo_ssh_user and remo_ssh_port.
+          Run it through 'remo configure <name>' rather than directly.
+        quiet: true
+
+    - name: Refuse to reconfigure the root account
+      ansible.builtin.assert:
+        that:
+          - remo_ssh_user != 'root'
+        fail_msg: >-
+          remo configures the SSH user you registered as the workspace account,
+          and user_setup pins that account to UID 1000 — doing that to root
+          would break the host. Re-register with a normal user:
+          remo add <name> {{ remo_ssh_host | default('<host>') }} --user <user>
+        quiet: true
+
+    # Fixed, colon-free name: add_host runs its `name` through parse_address(),
+    # so an IP-with-port name would set ansible_ssh_port behind our back.
+    - name: Add the registered SSH host to the in-memory inventory
+      ansible.builtin.add_host:
+        name: remo_ssh_target
+        groups:
+          - remo_ssh_hosts
+        ansible_host: "{{ remo_ssh_host }}"
+        ansible_user: "{{ remo_ssh_user }}"
+        ansible_port: "{{ remo_ssh_port | int }}"
+        ansible_python_interpreter: /usr/bin/python3
+        # `omit`, NOT a '~/.ssh/id_rsa' fallback. "No identity stored" means
+        # "let ssh/agent resolve the key"; defaulting to a path here is exactly
+        # how aws_configure.yml can silently offer the WRONG key.
+        ansible_ssh_private_key_file: "{{ remo_ssh_identity | default(omit) }}"
+        # ansible-core emits `-o IdentityFile=` for private_key_file but NOT
+        # `-o IdentitiesOnly=yes` (that pairing exists only on the `private_key`
+        # branch of connection/ssh.py). Without this, ssh offers every agent key
+        # first and a busy agent hits MaxAuthTries — "Too many authentication
+        # failures" — while the key you passed is never tried. core/ssh.py pairs
+        # them for this exact reason; match it.
+        ansible_ssh_common_args: >-
+          {{ '-o IdentitiesOnly=yes'
+             if (remo_ssh_identity | default('') | length) > 0
+             else omit }}
+
+- name: Configure a manually-registered SSH host with development tools
+  hosts: remo_ssh_hosts
+  become: true
+  # Facts are gathered explicitly in pre_tasks, AFTER the interpreter probe: the
+  # implicit gather runs a Python module, so on a host with no python3 it fails
+  # first, with a message that never names the actual problem.
+  gather_facts: false
+
+  vars:
+    # The account remo configures IS the account you registered. Everything
+    # user_setup installs lands in /home/{{ remo_user }}/.local/bin — including
+    # remo-host, which `remo web` discovery invokes over SSH as the REGISTERED
+    # user. Inventing a second 'remo' user here would leave discovery reporting
+    # no_remo_host after a "successful" configure. For the default `remo add`
+    # user this is a no-op: remo_user is 'remo' either way. It also skips the
+    # UID-1000 displacement in user_setup, which only fires when the holder of
+    # UID 1000 is someone other than remo_user.
+    remo_user: "{{ remo_ssh_user }}"
+    # No cloud provider injected a key on this host, so there is nothing to
+    # bootstrap FROM — and root's authorized_keys on a machine remo does not own
+    # belongs to its owner, not to a workspace account (#121). With remo_user
+    # set above, the connecting user's own authorized_keys is already non-empty,
+    # so the first-contact gate would decline anyway; false makes it structural.
+    user_setup_bootstrap_cloud_keys: false
+
+  pre_tasks:
+    # `raw` needs no interpreter on the target, so it can diagnose the absence
+    # of one. `become: false` is mandatory on both probes: ansible.cfg sets
+    # become=True globally, so without it they run THROUGH sudo and prove
+    # nothing — the sudo probe would report success on a host where the user
+    # cannot in fact sudo, because the connection itself would have failed.
+    - name: Probe for a Python 3 interpreter
+      ansible.builtin.raw: command -v python3
+      become: false
+      register: remo_python_probe
+      changed_when: false
+      failed_when: false
+
+    - name: Fail with actionable guidance when the host has no Python 3
+      ansible.builtin.fail:
+        msg: >-
+          No python3 on {{ ansible_host }}:{{ ansible_port }} — Ansible needs a
+          Python 3 interpreter on the target. Install it and retry:
+          ssh -p {{ ansible_port }} {{ ansible_user }}@{{ ansible_host }}
+          'sudo apt-get update && sudo apt-get install -y python3'
+      when: (remo_python_probe.rc | default(1)) != 0
+
+    - name: Probe for passwordless sudo
+      ansible.builtin.raw: sudo -n true
+      become: false
+      register: remo_sudo_probe
+      changed_when: false
+      failed_when: false
+
+    - name: Fail with actionable guidance when the SSH user cannot sudo
+      ansible.builtin.fail:
+        msg: >-
+          '{{ ansible_user }}' cannot sudo without a password on
+          {{ ansible_host }}. remo installs packages and system services, so it
+          needs passwordless sudo. Grant it once, then retry:
+          echo '{{ ansible_user }} ALL=(ALL) NOPASSWD:ALL' | sudo tee
+          /etc/sudoers.d/{{ ansible_user }} && sudo chmod 440
+          /etc/sudoers.d/{{ ansible_user }}
+      when: (remo_sudo_probe.rc | default(1)) != 0
+
+    - name: Gather facts
+      ansible.builtin.setup:
+
+    - name: Fail on a non-apt host before any role starts changing it
+      ansible.builtin.assert:
+        that:
+          - ansible_os_family | default('') == 'Debian'
+        fail_msg: >-
+          {{ ansible_host }} runs {{ ansible_distribution | default('an unknown
+          distribution') }} {{ ansible_distribution_version | default('') }};
+          every remo role is apt-based (Ubuntu and Debian are supported).
+          Nothing was changed.
+        quiet: true
+
+    - name: Wait for apt to be ready
+      ansible.builtin.shell: |
+        while fuser /var/lib/dpkg/lock-frontend /var/lib/apt/lists/lock /var/cache/apt/archives/lock >/dev/null 2>&1; do
+          sleep 5
+        done
+      args:
+        executable: /bin/bash
+      register: apt_lock_result
+      changed_when: false
+      retries: 30
+      delay: 10
+      until: apt_lock_result.rc | default(1) == 0
+
+    # Unwedge apt before the first apt call: a sources line naming a keyring
+    # that no longer exists makes apt refuse to read ANY source list, which
+    # would fail the cache update below and leave the host unrepairable (#120).
+    - name: Repair apt sources referencing a missing keyring
+      ansible.builtin.include_tasks: tasks/repair_apt_sources.yml
+
+    - name: Update apt cache
+      ansible.builtin.apt:
+        update_cache: true
+        cache_valid_time: 3600
+
+    - name: Upgrade all packages
+      ansible.builtin.apt:
+        upgrade: dist
+        autoremove: true
+
+    - name: Check if reboot is required
+      ansible.builtin.stat:
+        path: /var/run/reboot-required
+      register: reboot_required_file
+
+  tasks:
+    - name: Configure dev tools
+      ansible.builtin.include_tasks: tasks/configure_dev_tools.yml
+
+  post_tasks:
+    # Deliberately NOT ansible.builtin.reboot: hetzner/aws reboot because remo
+    # created and solely owns those VMs. This host is the user's own machine and
+    # may be running their other work; remo has no API to bring it back, and no
+    # way to notice if it doesn't. Report and let them choose.
+    #
+    # The message lives in the task NAME, not the debug body: the non-verbose
+    # output filter (core/ansible_runner.py::_filter_line) suppresses debug msg
+    # bodies entirely but does print task names — and clears them on `skipping:`,
+    # so this line appears exactly when a reboot really is pending.
+    - name: "Reboot pending — remo did NOT reboot this host (it is yours, not remo-provisioned); run 'sudo reboot' when convenient"
+      ansible.builtin.debug:
+        msg: >-
+          Package updates need a reboot:
+          ssh -p {{ ansible_port }} {{ ansible_user }}@{{ ansible_host }} 'sudo reboot'
+      when: reboot_required_file.stat.exists | default(false)
+
+    - name: Display completion message
+      ansible.builtin.debug:
+        msg: |
+          Host configuration complete!
+
+          Configured account: {{ remo_user }}
+          Workspace:          {{ dev_workspace_dir }}
+
+          Installed:
+          - Docker (with docker-compose plugin)
+          - User '{{ remo_user }}' with sudo NOPASSWD access and docker group
+          - Node.js LTS (v{{ nodejs_version }})
+          - fzf, @devcontainers/cli, GitHub CLI (gh), Zellij
+          - remo-host, which is what makes this host appear in 'remo web'
+
+          Connect with:
+            remo shell
+            ssh -p {{ ansible_port }} {{ ansible_user }}@{{ ansible_host }}