# AgentNet v0.1.50 Setup Usability Implementation Plan

> Execute in the existing `feat/v0150-usability` worktree. Keep the released strict request/plan/apply interfaces; guided mode must only orchestrate them.

**Goal:** One request-free server command and one server-origin-only laptop command, resumable within bounded deadlines, ending in the existing authenticated C0 communication proof.

**Affected requirements:** ID-006, COM-001, COM-002, COM-009, AVL-003, AVL-005, AVL-006, UX-001, UX-002, SEC-003, SEC-005, OPS-003, OPS-006.

**Fail closed:** Unsupported marker, ambiguous prerequisite discovery, changed plan digest, stale/revoked enrollment, deadline expiry, or uncertain communication result returns a typed blocker and preserves resumable state. No authority comes from CLI/discovery fields.

## Task 1: Guided laptop defaults and discovery

**Files:** `src/agentnet/cli.py`, `tests/cli/test_guided_join.py`, `tests/conformance/test_npm_package.py`

- Add red tests proving `join guided --server <origin>` parses without domain/harness/name.
- Fetch strict public readiness/discovery metadata and derive only domain/profile configuration.
- Detect harness from explicit override or measured launcher environment/process; fail on ambiguity rather than guessing.
- Derive a bounded hostname display proposal and preserve owner-only default paths.
- Keep all explicit options as overrides.

## Task 2: Guided laptop activation and C0 proof

**Files:** `src/agentnet/cli.py`, `tests/cli/test_guided_join.py`, focused C0/bootstrap tests

- Extend the existing guided state schema with resumable activation keys/stage.
- After enrollment, run existing bootstrap-plan begin/status/complete and C0 start/status/complete APIs with the same identity.
- Open the exact approval URL through the selected browser mode; poll with one 300-second total monotonic deadline.
- Return success only for the existing `COMPLETED_C0_ROUND_TRIP` terminal fact; never infer from HTTP success.
- Preserve exact idempotency on rerun and add timeout/terminal mismatch tests.

## Task 3: Request-free guided server orchestration

**Files:** `src/agentnet/operations/server_setup.py`, `src/agentnet/cli.py`, `tests/operations/test_server_setup.py`, `tests/operations/test_server_setup_recovery.py`

- Add red CLI tests for `server-agent setup --apply --start` with no request/digest.
- Reconstruct upgrade inputs from the exact managed marker/config/environment state.
- For fresh hosts, accept exactly one unambiguous standard root-only prerequisite set; otherwise emit `missing_external_prerequisite` with the missing owner-selected values. Do not invent TLS, DNS, IdP clients, or secrets.
- Generate an ephemeral strict `ServerSetupRequest`, run existing preflight/plan, render a concise plan, obtain one confirmation, then apply that exact digest.
- Add a 600-second monotonic deadline and stable phase/blocker progress on stderr; keep final JSON on stdout.

## Task 4: Direct supported upgrade

**Files:** `src/agentnet/operations/server_setup.py`, `tests/operations/test_server_setup_recovery.py`

- Accept direct package transitions from realized v0.1.45–v0.1.49 markers to v0.1.50.
- Reuse the current target runtime's schema migrator and exact source marker/unit validation; do not require intermediate npm installs.
- Prove unsupported/pre-lifecycle sources still fail closed and crash recovery does not repeat a committed mutation.

## Task 5: Installed two-machine release gate

**Files:** `.github/workflows/server-setup-e2e.yml`, `scripts/ci/` focused runner, package inclusion tests

- Build candidate npm bytes once and install those bytes into two isolated Ubuntu 24.04 guests.
- Provision only external prerequisites outside AgentNet; run the same public request-free server and server-origin-only laptop commands inside guests.
- Assert deadlines, one browser-equivalent journey, exact C0 roundtrip terminal fact, no duplicate event/receipt, and teardown residue absence.
- Keep the hermetic result honestly scoped; no external WebAuthn/OIDC or production-gate promotion.

## Task 6: Documentation and complete verification

**Files:** `README.md`, `docs/implementation-guide.md`, `docs/ARCHITECTURE.md`, `docs/SCHEMAS_INTERFACES.md`, `REQUIREMENTS_STATUS.md`, `docs/GATE_EVIDENCE.md`, release manifests/evidence only from fresh runs

- Replace the multi-command operator path with the two public commands and exact prerequisite/blocker wording.
- Run focused setup/join tests, installed two-machine smoke, full `npm run check`, `scripts/verify_release.py`, and `agentnet verify`.
- Rebuild deterministic artifacts, bind honest evidence, commit/push, and verify GitHub CI before declaring v0.1.50 ready.