init

AGENTS.md

@@ -5,6 +5,8 @@ Auto-generated from feature plans. Last updated: 2026-01-30
 ## Active Technologies
 - Python 3.12 + MCP server library (Python, JSON-RPC/stdin transport), click for CLI entrypoint, pytest + coverage for tests, ruff/black for lint/format (002-mcp-server)
 - None (in-memory tool definitions; filesystem access for repo interactions) (002-mcp-server)
+- Nix (flakes; nixpkgs 25.11) + nixpkgs, flake-parts, sops-nix (003-vps-image-migration)
+- N/A (configuration repo) (003-vps-image-migration)
 
 - Documentation set (AI-facing constitution and playbooks) in Markdown (001-ai-docs)
 
@@ -26,9 +28,10 @@ specs/001-ai-docs/       # Planning artifacts (plan, research, tasks, data model
 - Keep language business-level and technology-agnostic in AI-facing docs.
 
 ## Recent Changes
-- 002-mcp-server: Added Python 3.12 + MCP server library (Python, JSON-RPC/stdin transport), click for CLI entrypoint, pytest + coverage for tests, ruff/black for lint/format
+- 003-vps-image-migration: Added Nix (flakes; nixpkgs 25.11) + nixpkgs, flake-parts, sops-nix
+- 003-vps-image-migration: Added [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
+- 003-vps-image-migration: Added Nix (flakes; nixpkgs 25.11) + nixpkgs, flake-parts, sops-nix
 
-- 001-ai-docs: Documentation-focused stack; added docs/ for constitution/playbooks and specs/001-ai-docs/ for planning outputs.
 
 <!-- MANUAL ADDITIONS START -->
 <!-- MANUAL ADDITIONS END -->

specs/003-vps-image-migration/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: VPS Image Migration
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: February 3, 2026
+**Feature**: /home/jawz/Development/NixOS/specs/003-vps-image-migration/spec.md
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All checklist items pass based on the current spec.

specs/003-vps-image-migration/contracts/README.md

@@ -0,0 +1,3 @@
+# API Contracts
+
+This feature does not introduce or modify any external HTTP or RPC APIs. Operator actions (image build, provisioning, secrets enrollment, rebuild trigger) are performed via existing infrastructure workflows, so no API schema is required.

specs/003-vps-image-migration/data-model.md

@@ -0,0 +1,49 @@
+# Data Model: VPS Image Migration
+
+## Host Profile
+
+- **Purpose**: Defines a named system configuration (e.g., vps).
+- **Key fields**:
+  - `name` (string, unique)
+  - `target_environment` (string, e.g., Linode)
+  - `services_required` (list of service identifiers)
+  - `secrets_required` (list of secret identifiers)
+
+## Image Artifact
+
+- **Purpose**: Represents a build output used to provision a VPS.
+- **Key fields**:
+  - `image_type` (string, Linode-compatible)
+  - `build_reference` (string, build timestamp or revision)
+  - `host_profile` (reference to Host Profile)
+
+## Bootstrap Secret Material
+
+- **Purpose**: Material required to unlock secrets on the host.
+- **Key fields**:
+  - `bootstrap_method` (enum: generated-on-host)
+  - `recipient_public_key` (string)
+  - `enrollment_status` (enum: pending, enrolled)
+
+## Deployment Target
+
+- **Purpose**: The environment where the image is launched.
+- **Key fields**:
+  - `provider` (string)
+  - `region` (string)
+  - `instance_id` (string)
+
+## Rebuild Trigger
+
+- **Purpose**: Represents an authorized rebuild action for the VPS.
+- **Key fields**:
+  - `actor` (string)
+  - `requested_at` (datetime)
+  - `status` (enum: queued, running, succeeded, failed)
+
+## Relationships
+
+- Host Profile 1..* Image Artifact
+- Host Profile 1..* Bootstrap Secret Material
+- Deployment Target 1..1 Image Artifact
+- Rebuild Trigger *..1 Host Profile

specs/003-vps-image-migration/plan.md

@@ -0,0 +1,58 @@
+# Implementation Plan: VPS Image Migration
+
+**Branch**: `003-vps-image-migration` | **Date**: February 3, 2026 | **Spec**: /home/jawz/Development/NixOS/specs/003-vps-image-migration/spec.md
+**Input**: Feature specification from `/specs/003-vps-image-migration/spec.md`
+
+## Summary
+
+Migrate image building away from the deprecated generator to the upstream NixOS image workflow, add a new vps host that produces a Linode-compatible image, and implement a secure two-phase secrets bootstrap that requires re-encryption after the host generates its own key. Provide a repeatable remote rebuild workflow limited to explicitly authorized operator machines.
+
+## Technical Context
+
+**Language/Version**: Nix (flakes; nixpkgs 25.11)  
+**Primary Dependencies**: nixpkgs, flake-parts, sops-nix  
+**Storage**: N/A (configuration repo)  
+**Testing**: Manual validation (image build, boot, network, secret availability, rebuild)  
+**Target Platform**: NixOS image for Linode VPS  
+**Project Type**: Infrastructure configuration (single repo)  
+**Performance Goals**: N/A  
+**Constraints**: No regressions for existing hosts; secrets must remain secure; first boot must be reachable for enrollment; rebuilds restricted to authorized operator machines  
+**Scale/Scope**: Small number of hosts, single vps target
+
+## Constitution Check
+
+No enforceable principles are defined in the current constitution file (placeholders only). Gate passes by default.
+Post-design re-check: no changes; still pass.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/003-vps-image-migration/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+└── tasks.md
+```
+
+### Source Code (repository root)
+
+```text
+flake.nix
+parts/
+hosts/
+modules/
+secrets/
+scripts/
+config/
+environments/
+```
+
+**Structure Decision**: Use the existing Nix flake layout with host definitions in `hosts/`, shared logic in `modules/`, and flake assembly in `parts/`.
+
+## Complexity Tracking
+
+No constitution violations to track.

specs/003-vps-image-migration/quickstart.md

@@ -0,0 +1,14 @@
+# Quickstart: VPS Image Migration
+
+## Goal
+
+Provision a Linode-compatible VPS image, bootstrap secrets securely, and enable remote rebuilds.
+
+## Steps
+
+1. Build the vps image from the repository and confirm a Linode-compatible artifact is produced.
+2. Provision a VPS from the image and verify network connectivity and remote access.
+3. On first boot, allow the host to generate its own secrets bootstrap key material.
+4. Enroll the host by adding its public key as a secrets recipient and re-encrypt required secrets.
+5. Trigger a rebuild from an explicitly authorized operator machine to apply secrets and confirm core services start successfully.
+6. Validate the remote rebuild workflow from an explicitly authorized operator machine.

specs/003-vps-image-migration/research.md

@@ -0,0 +1,16 @@
+# Research: VPS Image Migration
+
+## Decision 1: Replace deprecated image generator usage
+
+- **Decision**: Use NixOS's built-in image building workflow (`nixos-rebuild build-image`) for Linode-compatible images.
+- **Rationale**: The NixOS manual documents `nixos-rebuild build-image` and lists Linode as a supported image target via `image.modules`, indicating the upstream path for image generation.
+- **Alternatives considered**:
+  - Keep using nixos-generators (rejected due to deprecation and upstream migration).
+
+## Decision 2: Secure-first secrets bootstrap for vps
+
+- **Decision**: Use a two-phase bootstrap where the vps generates its own age key on first boot, then the host public key is added as a recipient and secrets are re-encrypted before the second deploy.
+- **Rationale**: sops-nix supports generating an age key when missing and can use SSH host keys to derive age identities; this avoids embedding private keys in the image or repository.
+- **Alternatives considered**:
+  - Bake a static age key into the image (rejected for security risk).
+  - Ship a fixed SSH host key in the image (rejected for key reuse across hosts).

specs/003-vps-image-migration/spec.md

@@ -0,0 +1,103 @@
+# Feature Specification: VPS Image Migration
+
+**Feature Branch**: `003-vps-image-migration`  
+**Created**: February 3, 2026  
+**Status**: Draft  
+**Input**: User description: "Remove deprecated image generator usage, add a new vps host that builds a Linode image, ensure first-boot secrets are available, and support remote rebuilds for ongoing changes."
+
+## Clarifications
+
+### Session 2026-02-03
+
+- Q: Who is allowed to trigger remote rebuilds? → A: Only explicitly authorized operator machines.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Provision a VPS Image (Priority: P1)
+
+As an operator, I want to build a Linode-compatible image for the new vps host so I can provision a replacement VPS that boots with network connectivity and remote access.
+
+**Why this priority**: This is the core migration outcome; without a working image, the VPS replacement cannot proceed.
+
+**Independent Test**: Can be fully tested by building the image, launching a Linode instance from it, and confirming network and remote access.
+
+**Acceptance Scenarios**:
+
+1. **Given** a clean repository state, **When** I build the vps image, **Then** the build completes and produces a Linode-compatible image artifact.
+2. **Given** a Linode instance created from the vps image, **When** it boots, **Then** it has working network connectivity and remote access is available.
+
+---
+
+### User Story 2 - Secrets Available After Enrollment (Priority: P2)
+
+As an operator, I want the vps to generate its own secrets key on first boot and then make required secrets available after enrollment so core services can start securely.
+
+**Why this priority**: The VPS must remain secure; services should start only after the host is enrolled and secrets are re-encrypted for it.
+
+**Independent Test**: Can be fully tested by provisioning from the image, enrolling the host key, and verifying required secrets become available after the follow-up deployment.
+
+**Acceptance Scenarios**:
+
+1. **Given** a freshly provisioned vps instance, **When** the system completes its first boot, **Then** it generates host-specific bootstrap key material and remains reachable for enrollment.
+2. **Given** the host key is enrolled and secrets are re-encrypted, **When** a follow-up deployment runs, **Then** required secrets become available to services.
+
+---
+
+### User Story 3 - Remote Rebuild Workflow (Priority: P3)
+
+As an operator, I want to trigger rebuilds of the vps host from any authorized system so updates (such as firewall changes) can be applied consistently.
+
+**Why this priority**: Ongoing updates are essential for operations and security, and should not depend on a single workstation.
+
+**Independent Test**: Can be fully tested by triggering a rebuild from a separate authorized system and verifying the changes apply on the VPS.
+
+**Acceptance Scenarios**:
+
+1. **Given** an explicitly authorized operator machine, **When** a rebuild is triggered, **Then** the vps host updates successfully and reflects the new configuration.
+
+---
+
+### Edge Cases
+
+- What happens when the vps image build completes but the artifact is not compatible with the target environment?
+- How does the system handle first-boot secret access when bootstrap material is missing or corrupted?
+- What happens when a remote rebuild is triggered but the VPS is unreachable?
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The system MUST stop using any deprecated image-generation dependency currently used for host images.
+- **FR-002**: The system MUST define a new vps host configuration that produces a Linode-compatible image artifact.
+- **FR-003**: A VPS provisioned from the image MUST boot with working network connectivity and remote access enabled.
+- **FR-004**: The system MUST support a secure, two-phase bootstrap where the host generates key material on first boot and secrets become available after enrollment and re-deploy.
+- **FR-005**: The system MUST provide a documented, repeatable way for explicitly authorized operator machines to trigger remote rebuilds of the vps host.
+- **FR-006**: Existing hosts and images MUST continue to build and operate without regression after the migration.
+
+### Key Entities *(include if feature involves data)*
+
+- **Host Profile**: A named system configuration (e.g., vps) that defines the target environment behavior.
+- **Image Artifact**: A deployable disk image produced from the host profile.
+- **Bootstrap Secret Material**: Data required to unlock or access secrets on first boot.
+- **Deployment Target**: The infrastructure environment where the image is launched.
+- **Rebuild Trigger**: An authorized action that initiates a configuration update on the VPS.
+
+## Assumptions
+
+- The vps host can generate bootstrap key material on first boot and is reachable for enrollment.
+- Operators already have a secure, authorized path for remote access to the VPS.
+- The Linode environment can accept and boot the produced image artifact.
+
+## Dependencies
+
+- Access to the target environment needed to validate image compatibility and boot behavior.
+- Existing secrets management process and data required for the vps host.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: A Linode instance provisioned from the vps image is reachable via remote access within 10 minutes of first boot in at least 95% of test provisions.
+- **SC-002**: Required secrets for core services are available after enrollment and follow-up deployment in 100% of test provisions.
+- **SC-003**: Existing host builds complete without new failures after the deprecated dependency is removed.
+- **SC-004**: Remote rebuilds apply a configuration change to the vps host within 15 minutes in at least 90% of test runs.

specs/003-vps-image-migration/tasks.md

@@ -0,0 +1,151 @@
+---
+
+description: "Task list for VPS Image Migration"
+---
+
+# Tasks: VPS Image Migration
+
+**Input**: Design documents from `/specs/003-vps-image-migration/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: Not requested.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and validation setup
+
+- [ ] T001 Review current image generation usage in `flake.nix` and `parts/packages.nix` and note all nixos-generators references
+- [ ] T002 [P] Review host structure in `hosts/` to mirror patterns for the new `hosts/vps/configuration.nix`
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Remove deprecated generator and ensure existing outputs are preserved
+
+- [ ] T003 Update `parts/packages.nix` to build `emacs-vm` from nixpkgs/NixOS outputs (remove nixos-generators usage)
+- [ ] T004 Remove nixos-generators input from `flake.nix`
+- [ ] T005 Update `flake.lock` to drop nixos-generators entries
+- [ ] T006 STOP: Ask user to validate `emacs-vm` build works without nixos-generators (confirm before proceeding) (reference `parts/packages.nix`)
+
+**Checkpoint**: Foundation ready after user confirmation
+
+---
+
+## Phase 3: User Story 1 - Provision a VPS Image (Priority: P1) 🎯 MVP
+
+**Goal**: Define a new vps host and produce a Linode-compatible image artifact
+
+**Independent Test**: Build the vps image, launch a Linode instance from it, verify network connectivity and remote access
+
+### Implementation for User Story 1
+
+- [ ] T007 [US1] Create `hosts/vps/configuration.nix` with base imports and minimal networking/remote access enablement
+- [ ] T008 [US1] Register vps host in `parts/hosts.nix` using existing `createConfig` pattern
+- [ ] T009 [US1] Add a Linode image build output for vps in `parts/packages.nix` using the upstream NixOS image workflow
+- [ ] T010 [US1] Document the vps host entry and image artifact location in `docs/reference/index.md`
+- [ ] T011 [US1] Add a manual validation checklist entry for vps boot connectivity and remote access in `specs/003-vps-image-migration/quickstart.md`
+
+**Checkpoint**: vps image builds and can boot with connectivity
+
+---
+
+## Phase 4: User Story 2 - Secrets Available After Enrollment (Priority: P2)
+
+**Goal**: Secure two-phase secrets bootstrap and enrollment workflow
+
+**Independent Test**: Boot vps, generate host key, enroll key, re-encrypt secrets, redeploy, verify secrets available
+
+### Implementation for User Story 2
+
+- [ ] T012 [US2] Set secure host posture for vps in `hosts/vps/configuration.nix` (secureHost enabled, secrets gated)
+- [ ] T013 [US2] Add vps-specific sops-nix bootstrap settings in `hosts/vps/configuration.nix` (generate key on first boot; no baked key)
+- [ ] T014 [US2] Document the enrollment and re-encryption steps in `docs/playbooks/enroll-vps.md`
+- [ ] T015 [US2] Update secrets guidance to reference the vps enrollment flow in `docs/constitution.md`
+
+**Checkpoint**: vps can boot without secrets, then unlocks secrets after enrollment and redeploy
+
+---
+
+## Phase 5: User Story 3 - Remote Rebuild Workflow (Priority: P3)
+
+**Goal**: Provide a documented, repeatable remote rebuild process
+
+**Independent Test**: Trigger a rebuild from an explicitly authorized operator machine and verify applied config changes
+
+### Implementation for User Story 3
+
+- [ ] T016 [US3] Add a rebuild helper script in `scripts/rebuild-vps.sh` with clear inputs and safety checks
+- [ ] T017 [US3] Document remote rebuild usage and prerequisites (explicitly authorized operator machines only) in `docs/playbooks/vps-rebuild.md`
+
+**Checkpoint**: remote rebuild flow is repeatable and documented
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: Final consistency checks and documentation polish
+
+- [ ] T018 [P] Ensure vps host is referenced in any host inventories or indexes in `docs/reference/index.md`
+- [ ] T019 Validate quickstart steps still match implementation in `specs/003-vps-image-migration/quickstart.md`
+- [ ] T020 Validate existing host/image builds after migration (document results in `specs/003-vps-image-migration/quickstart.md`)
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: Depend on Foundational completion and user validation at T006
+- **Polish (Final Phase)**: Depends on desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Starts after Phase 2 and user validation at T006
+- **User Story 2 (P2)**: Starts after Phase 2 and user validation at T006; depends on vps host existing (T007/T008)
+- **User Story 3 (P3)**: Starts after Phase 2 and user validation at T006; can be done in parallel with US2
+
+### Parallel Opportunities
+
+- T002 can run in parallel with T001
+- T018 and T019 can run in parallel in the Polish phase
+- After T006, US2 and US3 can proceed in parallel once US1 host scaffolding exists
+
+---
+
+## Parallel Example: User Story 2
+
+```bash
+Task: "Set secure host posture for vps in hosts/vps/configuration.nix"
+Task: "Document the enrollment and re-encryption steps in docs/playbooks/enroll-vps.md"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational
+3. Pause at T006 for user validation of emacs-vm
+4. Complete Phase 3: User Story 1
+5. Stop and validate the image boot and connectivity
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → user validates emacs-vm
+2. Add User Story 1 → validate image build/boot
+3. Add User Story 2 → validate secrets enrollment flow
+4. Add User Story 3 → validate remote rebuild workflow
+5. Polish and doc consistency checks