diff --git a/API_SPEC.md b/API_SPEC.md
index 3be5447..3a7cd8f 100644
--- a/API_SPEC.md
+++ b/API_SPEC.md
@@ -1,55 +1,556 @@
 # Linux_Patch_API - API Specification Document
 
 ## API Overview
-[Describe API purpose and design philosophy]
+
+**Purpose:** Secure REST API for remote package and patch management on Linux systems
+
+**Design Philosophy:**
+- Pure REST architecture (resources as nouns, HTTP verbs for actions)
+- mTLS certificate-based authentication (no sessions)
+- Hybrid execution model (sync for quick ops, async for long ops)
+- Real-time status via WebSocket streaming
+- JSON request/response with standard envelope
+
+**Base Path:** `/api/v1/`
+**Protocol:** HTTPS (TLS 1.3 only)
+**Port:** 12443
+**Trailing Slashes:** Not required
+
+---
 
 ## Authentication
+
 ### Authentication Method
-- Type: [TBD - JWT/OAuth2/API Key]
-- Token Endpoint: [TBD]
-- Token Expiry: [TBD]
+- **Type:** mTLS Certificate-Based Authentication
+- **CA:** Internal self-hosted Certificate Authority
+- **Certificate Validity:** 1 year maximum
+- **Client Identity:** Unique certificate per client
+- **Session Management:** None (stateless)
+
+### Authorization
+- **Method:** IP Whitelist Enforcement
+- **Default:** Deny all (block unless explicitly allowed)
+- **Permissions:** Binary (whitelisted IP + valid cert = full access)
+- **No Granular Permissions:** All authenticated clients have full API access
+
+### Connection Requirements
+- Valid client certificate signed by internal CA
+- Client IP must be in whitelist configuration
+- TLS 1.3 only
+- Silent drop for non-compliant connections (no response)
+
+---
+
+## Standard Response Envelope
+
+All API responses use this standard structure:
+
+```json
+{
+  "success": true,
+  "request_id": "550e8400-e29b-41d4-a716-446655440000",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {},
+  "error": null
+}
+```
+
+### Fields:
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | boolean | true for successful requests, false for errors |
+| `request_id` | UUID | Unique identifier for request tracking/auditing |
+| `timestamp` | ISO 8601 | Server timestamp of response |
+| `data` | object | Response payload (null on error) |
+| `error` | object | Error details (null on success) |
+
+---
+
+## Error Response Format
+
+```json
+{
+  "success": false,
+  "request_id": "550e8400-e29b-41d4-a716-446655440000",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": null,
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable description",
+    "details": {},
+    "retryable": false
+  }
+}
+```
+
+### Error Codes:
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `AUTH_INVALID_CERT` | 401 | Certificate validation failed |
+| `AUTH_CERT_EXPIRED` | 401 | Certificate has expired |
+| `AUTHZ_IP_DENIED` | 403 | IP not in whitelist |
+| `PKG_NOT_FOUND` | 404 | Package not found |
+| `PKG_MANAGER_ERROR` | 500 | Package manager operation failed |
+| `JOB_NOT_FOUND` | 404 | Job ID not found |
+| `JOB_TIMEOUT` | 408 | Job exceeded 30-minute timeout |
+| `CONFIG_INVALID` | 400 | Configuration validation failed |
+| `SERVICE_UNHEALTHY` | 503 | Service not ready |
+
+---
 
 ## Endpoints
 
-### PATCH Management Endpoints
-#### GET /api/v1/patches
-[Describe endpoint]
+### Package Management Endpoints
 
-#### POST /api/v1/patches/apply
-[Describe endpoint]
+#### POST /api/v1/packages
 
-#### GET /api/v1/patches/status/{id}
-[Describe endpoint]
+**Description:** Install one or more packages (async operation)
 
-### Software Management Endpoints
-#### GET /api/v1/software
-[Describe endpoint]
+**Request Body:**
+```json
+{
+  "packages": [
+    {
+      "name": "nginx",
+      "version": "1.24.0-1"
+    }
+  ],
+  "options": {
+    "force": false,
+    "no_recommends": true
+  }
+}
+```
 
-#### POST /api/v1/software/install
-[Describe endpoint]
-
-#### POST /api/v1/software/remove
-[Describe endpoint]
-
-### System Endpoints
-#### GET /api/v1/system/status
-[Describe endpoint]
-
-#### GET /api/v1/system/logs
-[Describe endpoint]
-
-## Request/Response Formats
-### Standard Response Structure
-[Define response schema]
-
-### Error Response Format
-[Define error response schema]
-
-## Rate Limiting
-[Define rate limits]
-
-## Versioning Strategy
-[API versioning approach]
+**Response (202 Accepted):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "job_id": "uuid",
+    "status": "pending",
+    "operation": "install",
+    "packages": ["nginx"]
+  },
+  "error": null
+}
+```
 
 ---
+
+#### GET /api/v1/packages
+
+**Description:** List installed packages with filtering and sorting
+
+**Query Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Filter by package name (supports wildcard `*`) |
+| `status` | string | Filter: `installed`, `upgradable`, `available` |
+| `upgradable` | boolean | `true` to show only upgradable packages |
+| `sort` | string | Sort field: `name`, `version`, `status` (default: `name`) |
+| `order` | string | Sort order: `asc`, `desc` (default: `asc`) |
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "packages": [
+      {
+        "name": "nginx",
+        "version": "1.24.0-1",
+        "status": "installed",
+        "upgradable": true,
+        "latest_version": "1.25.0-1",
+        "description": "High performance web server",
+        "dependencies": ["libc6", "libssl3"],
+        "reverse_dependencies": ["nginx-core"]
+      }
+    ],
+    "total": 1
+  },
+  "error": null
+}
+```
+
+---
+
+#### GET /api/v1/packages/{name}
+
+**Description:** Get details of a specific package
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "name": "nginx",
+    "version": "1.24.0-1",
+    "status": "installed",
+    "upgradable": true,
+    "latest_version": "1.25.0-1",
+    "description": "High performance web server",
+    "dependencies": ["libc6", "libssl3"],
+    "reverse_dependencies": ["nginx-core"],
+    "install_date": "2026-01-15T10:30:00Z",
+    "size_installed": "2.5 MB"
+  },
+  "error": null
+}
+```
+
+---
+
+#### PUT /api/v1/packages/{name}
+
+**Description:** Update a specific package (async operation)
+
+**Response (202 Accepted):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "job_id": "uuid",
+    "status": "pending",
+    "operation": "update",
+    "package": "nginx"
+  },
+  "error": null
+}
+```
+
+---
+
+#### DELETE /api/v1/packages/{name}
+
+**Description:** Remove a package (async operation)
+
+**Response (202 Accepted):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "job_id": "uuid",
+    "status": "pending",
+    "operation": "remove",
+    "package": "nginx"
+  },
+  "error": null
+}
+```
+
+---
+
+### Patch Management Endpoints
+
+#### GET /api/v1/patches
+
+**Description:** List available updates/patches
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "patches": [
+      {
+        "name": "linux-kernel",
+        "current_version": "5.15.0-91",
+        "available_version": "5.15.0-92",
+        "severity": "critical",
+        "description": "Security update for kernel vulnerabilities",
+        "cve_ids": ["CVE-2024-1234"],
+        "requires_reboot": true
+      }
+    ],
+    "total": 1,
+    "security_updates": 1,
+    "requires_reboot": true
+  },
+  "error": null
+}
+```
+
+---
+
+#### POST /api/v1/patches/apply
+
+**Description:** Apply all or specific patches (async operation)
+
+**Request Body:**
+```json
+{
+  "packages": ["linux-kernel", "libc6"],  // optional, all if omitted
+  "reboot": true,                         // optional, auto-reboot after patching
+  "reboot_delay_seconds": 60              // optional, delay before reboot
+}
+```
+
+**Response (202 Accepted):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "job_id": "uuid",
+    "status": "pending",
+    "operation": "patch_apply",
+    "packages_count": 2,
+    "reboot_scheduled": true
+  },
+  "error": null
+}
+```
+
+---
+
+### System Endpoints
+
+#### GET /api/v1/system/info
+
+**Description:** Get system information
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "hostname": "server01",
+    "os": "Ubuntu",
+    "os_version": "22.04 LTS",
+    "kernel": "5.15.0-91-generic",
+    "architecture": "x86_64",
+    "last_update_check": "2026-04-09T12:00:00Z",
+    "last_update_apply": "2026-04-01T03:00:00Z",
+    "pending_reboot": false
+  },
+  "error": null
+}
+```
+
+---
+
+#### GET /api/v1/health
+
+**Description:** Health check endpoint
+
+**Response (200 OK - Healthy):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "status": "healthy",
+    "uptime_seconds": 12345,
+    "version": "0.0.1"
+  },
+  "error": null
+}
+```
+
+**Response (503 - Unhealthy):**
+```json
+{
+  "success": false,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": null,
+  "error": {
+    "code": "SERVICE_UNHEALTHY",
+    "message": "Service not ready",
+    "details": {},
+    "retryable": true
+  }
+}
+```
+
+---
+
+#### POST /api/v1/system/reboot
+
+**Description:** Reboot the system (async operation)
+
+**Request Body:**
+```json
+{
+  "delay_seconds": 0,   // optional, immediate if omitted
+  "force": false        // optional, skip pending job checks
+}
+```
+
+**Response (202 Accepted):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "job_id": "uuid",
+    "status": "pending",
+    "operation": "reboot",
+    "scheduled_at": "2026-04-09T13:04:02Z"
+  },
+  "error": null
+}
+```
+
+---
+
+### Job Management Endpoints
+
+#### GET /api/v1/jobs
+
+**Description:** List all jobs with optional filtering
+
+**Query Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `status` | string | Filter: `pending`, `running`, `completed`, `failed`, `cancelled` |
+| `limit` | integer | Max results (default: 50, no pagination beyond limit) |
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "jobs": [
+      {
+        "job_id": "uuid",
+        "operation": "install",
+        "status": "completed",
+        "created_at": "2026-04-09T13:00:00Z",
+        "completed_at": "2026-04-09T13:02:00Z",
+        "packages": ["nginx"]
+      }
+    ],
+    "total": 1
+  },
+  "error": null
+}
+```
+
+---
+
+#### GET /api/v1/jobs/{id}
+
+**Description:** Get specific job status
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "job_id": "uuid",
+    "operation": "install",
+    "status": "running",
+    "progress": 45,
+    "message": "Downloading package...",
+    "created_at": "2026-04-09T13:00:00Z",
+    "completed_at": null,
+    "packages": ["nginx"],
+    "logs": ["Starting installation...", "Resolving dependencies..."]
+  },
+  "error": null
+}
+```
+
+---
+
+#### POST /api/v1/jobs/{id}/rollback
+
+**Description:** Rollback a completed/failed job (async, exclusive mode)
+
+**Response (202 Accepted):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "job_id": "uuid-rollback",
+    "status": "pending",
+    "operation": "rollback",
+    "original_job_id": "uuid",
+    "exclusive_mode": true
+  },
+  "error": null
+}
+```
+
+---
+
+#### WebSocket: /api/v1/ws/jobs
+
+**Description:** Real-time job status streaming
+
+**Connection:** Upgrade HTTP connection with mTLS
+
+**Client → Server (subscribe):**
+```json
+{
+  "action": "subscribe",
+  "job_id": "uuid"  // optional, omit for all jobs
+}
+```
+
+**Server → Client (status update):**
+```json
+{
+  "event": "job_status",
+  "job_id": "uuid",
+  "status": "running",
+  "progress": 45,
+  "message": "Installing package...",
+  "timestamp": "2026-04-09T13:04:02Z"
+}
+```
+
+**Server → Client (job complete):**
+```json
+{
+  "event": "job_complete",
+  "job_id": "uuid",
+  "status": "completed",
+  "progress": 100,
+  "message": "Installation complete",
+  "timestamp": "2026-04-09T13:04:02Z"
+}
+---
+
+## Rate Limiting
+
+**Not Required:** Internal network only with strict IP whitelist
+
+---
+
+## Versioning Strategy
+
+- **Method:** URL Path Versioning (`/api/v1/`)
+- **Backward Compatibility:** Breaking changes require new major version
+- **Deprecation:** Old versions supported for 6 months after new version release
+- **Current Version:** v1
+
+---
+
 *Following kiro spec-driven development standards*
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 293e232..8d19acf 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -1,36 +1,290 @@
 # Linux_Patch_API - Architecture Document
 
 ## System Overview
-[High-level system architecture description]
 
-## Component Architecture
-### Core Components
-[List and describe core components]
+The Linux_Patch_API is a secure, single-host API service that enables remote package and patch management on Linux systems. Each instance runs as a systemd service on the managed host, providing a REST API over mTLS with strict IP whitelist enforcement.
 
-### External Integrations
-[Describe external system integrations]
-
-## Technology Stack
-### Backend
-- Language: [TBD]
-- Framework: [TBD]
-- Database: [TBD]
-
-### Frontend (if applicable)
-- Framework: [TBD]
-
-### Infrastructure
-- Container: [TBD]
-- Orchestration: [TBD]
-
-## Security Architecture
-[Security layers and controls]
-
-## Data Flow
-[Describe data flow through the system]
-
-## API Design Principles
-[REST/gRPC/GraphQL design decisions]
+**Architecture Type:** Agent Per Host (Option B)  
+**Deployment:** One instance per managed Linux host  
+**Network:** Internal network only (no internet exposure)
 
 ---
+
+## Component Architecture
+
+### Core Components
+
+1. **API Layer (Actix-web/Axum)**
+   - HTTP/HTTPS endpoint handling
+   - mTLS termination
+   - IP whitelist enforcement
+   - Request routing
+   - WebSocket support for real-time job status
+
+2. **Authentication Layer**
+   - Certificate validation (mTLS)
+   - Client identity extraction from certificate
+   - No session management (stateless, cert-based auth only)
+
+3. **Authorization Layer**
+   - IP whitelist checking (deny by default)
+   - No permission validation (whitelisted IP + valid cert = full access)
+
+4. **Job Manager**
+   - Async job queue for long-running operations
+   - Job status tracking with persistent storage
+   - WebSocket broadcast for real-time status updates
+   - 30-minute timeout enforcement
+   - Job cleanup and expiration
+
+5. **Package Manager Backend (Pluggable)**
+   - apt/dpkg adapter (Debian/Ubuntu - primary)
+   - dnf/yum adapter (RHEL/CentOS/Fedora)
+   - apk adapter (Alpine)
+   - pacman adapter (Arch)
+   - Distribution detection and adapter selection
+
+6. **Audit Logger**
+   - systemd journal integration (primary)
+   - Optional remote syslog server
+   - Local file fallback (`/var/log/linux_patch_api/`)
+   - 30-day retention with daily rotation and gzip compression
+
+7. **Configuration Manager**
+   - YAML config file watcher (`/etc/linux_patch_api/config.yaml`)
+   - Auto-reload on file change
+   - Config validation before reload (prevents service downtime)
+   - Runtime settings access for all components
+
+### External Integrations
+
+- **Package Managers:** apt, dnf, yum, apk, pacman (via system commands)
+- **systemd:** Service management and journal logging
+- **Internal CA:** Certificate validation against self-hosted CA
+- **Remote Syslog:** Optional external log aggregation
+
+---
+
+## Technology Stack
+
+### Backend
+- **Language:** Rust
+- **Framework:** Actix-web or Axum
+- **Database:** None (file-based job storage)
+- **mTLS:** Rust TLS library (rustls or native-tls)
+
+### Infrastructure
+- **Service Manager:** systemd
+- **Configuration:** YAML
+- **Logging:** systemd journal + optional syslog
+
+### Deployment
+- **Package Format:** Native Linux packages (deb, rpm, apk, pkg.tar.zst)
+- **Distribution:** Via target system package manager (apt, dnf, apk, pacman)
+- **Installation:** Package installs binary, systemd service, and default config structure
+- **Updates:** Handled through system package manager
+
+---
+
+## Security Architecture
+
+### Authentication
+- mTLS certificate-based authentication (required)
+- Internal self-hosted CA
+- Unique client certificates (1-year validity)
+- Silent drop for non-mTLS connections
+
+### Authorization
+- IP whitelist enforcement (block all by default)
+- No granular permissions (binary access: allowed or denied)
+- Whitelisted IP + valid cert = full API access
+
+### Process Security (systemd Hardening)
+- **User:** root (required for package management)
+- **NoNewPrivileges:** true (prevent privilege escalation)
+- **ProtectSystem:** strict (read-only filesystem except allowed paths)
+- **ProtectHome:** true (no access to /home, /root, /run/user)
+- **PrivateTmp:** true (isolated /tmp)
+- **SystemCallFilter:** Restrict to required syscalls only (application whitelist)
+- **RestrictAddressFamilies:** AF_INET, AF_INET6, AF_UNIX (network restrictions)
+- **CapabilityBoundingSet:** CAP_NET_BIND_SERVICE, CAP_SYS_ADMIN (minimal capabilities)
+
+### Data Security
+- All communications encrypted via TLS
+- Certificates stored securely with restricted permissions
+- Audit logging of all operations
+
+### Certificate Storage (Option A: Separate Files)
+
+```
+/etc/linux_patch_api/certs/
+├── ca.pem       (644) - CA certificate
+├── server.pem   (644) - Server certificate
+└── server.key   (600) - Server private key (restricted)
+```
+
+**Rationale:**
+- Tighter permissions on private key only (600)
+- Easier certificate rotation (replace cert without touching key)
+- Standard practice for TLS deployments
+- No extraction overhead
+---
+
+## File System Layout
+
+```
+/etc/linux_patch_api/
+├── config.yaml          # Main configuration
+├── whitelist.yaml       # IP whitelist
+└── certs/
+    ├── ca.pem          # CA certificate (or server.p12)
+    ├── server.pem      # Server certificate
+    └── server.key      # Server private key
+
+/var/lib/linux_patch_api/
+├── jobs/               # Job storage (cleared on restart)
+└── state/              # Runtime state
+
+/var/log/linux_patch_api/
+└── audit.log           # Local audit log fallback
+
+/usr/bin/linux-patch-api  # Binary location
+/etc/systemd/system/linux-patch-api.service  # Systemd service
+```
+---
+
+## Data Flow
+
+### Synchronous Request Flow (Quick Operations):
+
+```
+Client → [mTLS Handshake] → [IP Whitelist Check] → [API Layer]
+         ↓
+    [Auth: Cert Valid?] → No → Silent Drop
+         ↓ Yes
+    [Authz: IP Allowed?] → No → Silent Drop
+         ↓ Yes
+    [Route to Handler] → [Execute Package Op] → [Log to Audit]
+         ↓
+    [Return JSON Response] ← Client
+```
+
+### Asynchronous Request Flow (Long Operations):
+
+```
+Client → [mTLS + IP Check] → [API Layer] → [Create Job] → [Return Job ID]
+                                           ↓
+                                    [Job Manager Queue]
+                                           ↓
+                                    [Package Manager Backend]
+                                           ↓
+                                    [Update Job Status] → [WebSocket Broadcast]
+                                           ↓
+                                    [Job Complete/Timeout]
+                                           ↓
+                                    [Log to Audit]
+```
+
+### Job Status Endpoint Flow:
+
+```
+Client → [mTLS + IP Check] → [API Layer] → [GET /jobs/{id}]
+                                           ↓
+                                    [Query Job Storage]
+                                           ↓
+                                    [Return Job Status JSON]
+```
+
+### Configuration Reload Flow:
+
+```
+[Config File Changed] → [File Watcher Detects]
+         ↓
+    [Validate New Config] → Invalid → [Log Error, Keep Old Config]
+         ↓ Valid
+    [Swap Config in Memory] → [Notify Components] → [Log Reload Event]
+```
+
+### Certificate Renewal Flow:
+
+```
+[Cert File Updated] → [File Watcher Detects]
+         ↓
+    [Validate Certificate Chain] → Invalid → [Log Error, Keep Old Certs]
+         ↓ Valid
+    [Reload TLS Context] → [New Connections Use New Certs] → [Log Reload Event]
+```
+
+### Rollback Execution Flow (Exclusive):
+
+```
+[Rollback Triggered] → [Set Exclusive Mode] → [Reject New Requests]
+         ↓
+    [Execute Rollback Operations] → [Log Each Step]
+         ↓
+    [Rollback Complete] → [Clear Exclusive Mode] → [Accept New Requests]
+```
+
+### Key Behaviors:
+
+- Failed jobs are cleared on service restart (no persistence)
+- Rollback execution is exclusive - no new requests accepted until complete
+- Certificate renewal follows same validation pattern as config reload
+- Status endpoint available (GET /jobs/{id}) in addition to WebSocket for job monitoring
+
+---
+
+## API Design Principles
+
+- Pure REST (resources as nouns, HTTP verbs for actions)
+- JSON request/response with standard envelope
+- Hybrid execution model (sync for quick ops, async for long ops)
+- WebSocket for real-time job status streaming
+- GET /jobs/{id} endpoint for job status polling
+
+---
+
+## Network Configuration
+
+- **Bind Address:** 0.0.0.0 (all interfaces)
+- **Port:** 12443 (HTTPS/mTLS)
+- **Protocol:** TLS 1.3 only
+- **Firewall:** Host-level firewall should restrict inbound to whitelisted IPs only
+
+---
+
+## Health Checks
+
+### Endpoint: GET /health
+
+**Purpose:** General service status check
+
+**Response (200 OK - Healthy):**
+```json
+{
+  "success": true,
+  "request_id": "uuid",
+  "timestamp": "2026-04-09T13:04:02Z",
+  "data": {
+    "status": "healthy",
+    "uptime_seconds": 12345,
+    "version": "0.0.1"
+  },
+  "error": null
+}
+```
+
+**Health Check Criteria:**
+- Service is listening on port 12443
+- mTLS is configured and valid
+- Config file is loaded and valid
+- Package manager backend is accessible
+
+**NOT Required:**
+- Metrics collection
+- Alerting integration
+- Prometheus/Grafana endpoints
+
+---
+
 *Following kiro spec-driven development standards*
diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md
index 543c49e..e3aafd8 100644
--- a/REQUIREMENTS.md
+++ b/REQUIREMENTS.md
@@ -1,43 +1,168 @@
 # Linux_Patch_API - Requirements Document
 
 ## Functional Requirements
-### FR-001: Remote Patch Management
-[Define patch management requirements]
 
-### FR-002: Software Installation/Removal
-[Define software package management requirements]
+### FR-001: Package Management Endpoints
 
-### FR-003: Authentication & Authorization
-[Define auth requirements]
+| ID | Endpoint | Method | Description | Sync/Async |
+|----|----------|--------|-------------|------------|
+| FR-001.1 | `/packages` | GET | List installed packages with filtering (name, version, status, upgradable) | Sync |
+| FR-001.2 | `/packages/{name}` | GET | Get specific package details | Sync |
+| FR-001.3 | `/packages` | POST | Install package(s) with optional version pinning | Async |
+| FR-001.4 | `/packages/{name}` | PUT | Update specific package | Async |
+| FR-001.5 | `/packages/{name}` | DELETE | Remove package | Async |
 
-### FR-004: Audit Logging
-[Define logging requirements]
+### FR-002: Patch Management Endpoints
 
-## Non-Functional Requirements
-### NFR-001: Security
-[Security requirements]
+| ID | Endpoint | Method | Description | Sync/Async |
+|----|----------|--------|-------------|------------|
+| FR-002.1 | `/patches` | GET | List available updates/patches | Sync |
+| FR-002.2 | `/patches/apply` | POST | Apply all or specific patches | Async |
 
-### NFR-002: Performance
-[Performance requirements]
+### FR-003: System Endpoints
 
-### NFR-003: Availability
-[Availability requirements]
+| ID | Endpoint | Method | Description | Sync/Async |
+|----|----------|--------|-------------|------------|
+| FR-003.1 | `/system/info` | GET | Get system information (OS version, kernel, last update time) | Sync |
+| FR-003.2 | `/health` | GET | Health check endpoint | Sync |
+| FR-003.3 | `/jobs/{id}` | GET | Get specific job status | Sync |
+| FR-003.4 | `/jobs` | GET | List all jobs (with optional status filter) | Sync |
 
-### NFR-004: Scalability
-[Scalability requirements]
+### FR-004: Job Management Endpoints
 
-## User Stories
-[List user stories with acceptance criteria]
+| ID | Endpoint | Method | Description | Sync/Async |
+|----|----------|--------|-------------|------------|
+| FR-004.1 | `/jobs/{id}/rollback` | POST | Rollback a completed/failed job | Async (Exclusive) |
 
-## Technical Requirements
-### System Requirements
-- OS: [TBD]
-- Memory: [TBD]
-- Storage: [TBD]
+### FR-005: Authentication & Authorization
 
-### Network Requirements
-- Ports: [TBD]
-- Protocols: [TBD]
+- mTLS certificate validation (required for all endpoints)
+- IP whitelist enforcement (deny by default, allow listed only)
+- No session management (stateless, cert-based auth)
+- No granular permissions (whitelisted IP + valid cert = full access)
+
+### FR-006: Audit Logging
+
+- Log all API requests with client cert ID, endpoint, method, timestamp
+- Log all package operations (package name, version, action)
+- Log authentication events (success/failure, cert validation)
+- Log IP whitelist denials (blocked connection attempts)
+- Log configuration changes (whitelist updates, cert renewals)
+- Log system changes made by the API
 
 ---
+## Non-Functional Requirements
+
+### NFR-001: Security
+
+- **Authentication:** mTLS certificate-based (TLS 1.3 only)
+- **Authorization:** IP whitelist enforcement (block all by default)
+- **Certificate Validity:** 1-year maximum, unique per client
+- **Subprocess Restriction:** SystemCallFilter to limit allowed syscalls
+- **Error Handling:** Silent drop for non-mTLS connections, detailed errors for authenticated clients
+- **Data Encryption:** All communications encrypted via TLS
+
+### NFR-002: Performance
+
+- **Quick Operations:** < 5 seconds response time (GET endpoints)
+- **Long Operations:** Async with job tracking, max 30-minute timeout
+- **Concurrent Jobs:** Configurable limit (default: 5)
+- **WebSocket:** Real-time status updates for async jobs
+
+### NFR-003: Availability
+
+- **Service Type:** systemd service with automatic restart on failure
+- **Config Reload:** Auto-reload on config file change (validated before apply)
+- **Certificate Reload:** Auto-reload on cert file change (validated before apply)
+- **Health Check:** GET /health endpoint for monitoring
+
+### NFR-004: Scalability
+
+- **Architecture:** Single instance per host (Agent Per Host model)
+- **No Central Coordination:** Each host operates independently
+- **Package Manager:** Pluggable backend for multi-distribution support
+
+### NFR-005: Reliability
+
+- **Job Persistence:** Jobs stored in memory/file, cleared on restart
+- **Rollback:** Exclusive mode during rollback (no new requests accepted)
+- **Batch Operations:** Best-effort (not atomic)
+- **Idempotency:** Operations should be idempotent where possible
+
+---
+
+## User Stories
+
+### US-001: System Administrator - Install Package
+**As a** system administrator  
+**I want to** install a package remotely via API  
+**So that** I can manage software without SSH access  
+
+**Acceptance Criteria:**
+- POST /packages with package name returns job ID
+- Job status available via GET /jobs/{id} and WebSocket
+- Audit log records the installation
+- Rollback available if installation fails
+
+### US-002: System Administrator - Apply Security Patches
+**As a** system administrator  
+**I want to** apply all available security patches  
+**So that** the system stays secure  
+
+**Acceptance Criteria:**
+- GET /patches shows available updates
+- POST /patches/apply initiates patching
+- Real-time status via WebSocket
+- All operations logged to audit
+
+### US-003: System Administrator - Check System Status
+**As a** system administrator  
+**I want to** check system health and package status  
+**So that** I can monitor the system  
+
+**Acceptance Criteria:**
+- GET /health returns service status
+- GET /system/info returns OS details
+- GET /packages returns installed packages
+- All queries require valid mTLS cert
+
+### US-004: System Administrator - Remove Package
+**As a** system administrator  
+**I want to** remove an unwanted package  
+**So that** I can clean up the system  
+
+**Acceptance Criteria:**
+- DELETE /packages/{name} returns job ID
+- Job tracks removal progress
+- Audit log records the removal
+- Rollback available if needed
+
+---
+
+## Technical Requirements
+
+### System Requirements
+
+- **OS:** Linux (Debian/Ubuntu primary, RHEL/CentOS/Fedora, Alpine, Arch supported)
+- **Memory:** Minimum 256MB RAM, recommended 512MB
+- **Storage:** Minimum 100MB for binary and config, plus job storage
+- **CPU:** Any modern x86_64 or ARM64 processor
+- **Privileges:** Root access required (for package management)
+
+### Network Requirements
+
+- **Port:** 12443 (TCP)
+- **Protocol:** TLS 1.3 only
+- **Bind Address:** 0.0.0.0 (all interfaces)
+- **Firewall:** Host-level firewall to restrict inbound to whitelisted IPs
+
+### Dependencies
+
+- **Runtime:** None (compiled Rust binary)
+- **Package Managers:** apt/dpkg, dnf/yum, apk, or pacman (at least one required)
+- **systemd:** For service management
+- **Certificates:** Valid mTLS certificates from internal CA
+
+---
+
 *Following kiro spec-driven development standards*
diff --git a/ROADMAP.md b/ROADMAP.md
index 48ec692..1b2c900 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,57 +1,203 @@
 # Linux_Patch_API - Development Roadmap
 
+## Project Timeline Overview
+
+**Start Date:** 2026-04-09  
+**Target Production:** 2026-07-17  
+**Total Duration:** 14 weeks (Aggressive timeline)  
+**Phase Strategy:** Sequential (no overlap)
+
+---
+
 ## Project Phases
 
-### Phase 1: Foundation
-**Target Date:** [TBD]  
-**Status:** Not Started
+### Phase 0: Rust Project Scaffolding
+**Duration:** 3 days  
+**Target Date:** 2026-04-09 to 2026-04-12  
+**Status:** Ready to Start
 
-- [ ] Complete all specification documents
-- [ ] Set up development environment
-- [ ] Initialize git repository
-- [ ] Configure CI/CD pipeline
-- [ ] Establish security baseline
-
-### Phase 2: Core API Development
-**Target Date:** [TBD]  
-**Status:** Not Started
-
-- [ ] Implement authentication system
-- [ ] Build patch management endpoints
-- [ ] Build software management endpoints
-- [ ] Implement audit logging
-- [ ] Unit test coverage >80%
-
-### Phase 3: Security Hardening
-**Target Date:** [TBD]  
-**Status:** Not Started
-
-- [ ] Penetration testing
-- [ ] Security audit
-- [ ] Implement rate limiting
-- [ ] Complete threat model validation
-- [ ] Compliance review
-
-### Phase 4: Production Readiness
-**Target Date:** [TBD]  
-**Status:** Not Started
-
-- [ ] Performance optimization
-- [ ] Documentation completion
-- [ ] Deployment automation
-- [ ] Monitoring and alerting
-- [ ] User acceptance testing
-
-## Milestones
-| Milestone | Description | Target Date |
-|-----------|-------------|-------------|
-| M1 | Spec completion | [TBD] |
-| M2 | Alpha release | [TBD] |
-| M3 | Beta release | [TBD] |
-| M4 | Production release | [TBD] |
-
-## Risk Register
-[List identified risks and mitigation strategies]
+- [ ] Initialize Rust project with Cargo
+- [ ] Set up project structure (src/, tests/, configs/)
+- [ ] Configure Cargo.toml with dependencies (actix-web, tokio, openssl, serde, etc.)
+- [ ] Set up Clippy and rustfmt for code quality
+- [ ] Create initial module structure (api, auth, jobs, packages, config, logging)
+- [ ] Configure .gitignore for Rust projects
+- [ ] Set up initial logging framework
 
 ---
+
+### Phase 1: Foundation
+**Duration:** 2 weeks  
+**Target Date:** 2026-04-12 to 2026-04-26  
+**Status:** Not Started
+
+- [ ] Complete all specification documents ✅ (in progress)
+- [ ] Set up development environment (Rust toolchain, IDE config)
+- [ ] Initialize git repository ✅ (complete)
+- [ ] Configure CI/CD pipeline (GitHub Actions or GitLab CI)
+- [ ] Establish security baseline (dependency scanning, cargo-audit)
+- [ ] Set up test framework (cargo test, integration test structure)
+- [ ] Create systemd service file template
+- [ ] Set up internal CA infrastructure for mTLS certs
+
+---
+
+### Phase 2: Core API Development
+**Duration:** 6 weeks  
+**Target Date:** 2026-04-26 to 2026-06-07  
+**Status:** Not Started
+
+- [ ] Implement mTLS authentication layer
+- [ ] Implement IP whitelist enforcement
+- [ ] Build configuration management (YAML loading, validation, auto-reload)
+- [ ] Build job manager (queue, status tracking, WebSocket broadcast)
+- [ ] Implement Package Management endpoints:
+  - GET /api/v1/packages (list/filter/sort)
+  - GET /api/v1/packages/{name} (details)
+  - POST /api/v1/packages (install)
+  - PUT /api/v1/packages/{name} (update)
+  - DELETE /api/v1/packages/{name} (remove)
+- [ ] Implement Patch Management endpoints:
+  - GET /api/v1/patches (list available)
+  - POST /api/v1/patches/apply (apply patches)
+- [ ] Implement System endpoints:
+  - GET /api/v1/system/info
+  - GET /api/v1/health
+  - POST /api/v1/system/reboot
+- [ ] Implement Job Management endpoints:
+  - GET /api/v1/jobs (list)
+  - GET /api/v1/jobs/{id} (status)
+  - POST /api/v1/jobs/{id}/rollback
+- [ ] Implement WebSocket streaming (/api/v1/ws/jobs)
+- [ ] Implement audit logging (systemd journal + file fallback)
+- [ ] Unit test coverage >95%
+- [ ] Integration tests for all endpoints
+
+---
+
+### Phase 3: Security Hardening
+**Duration:** 3 weeks  
+**Target Date:** 2026-06-07 to 2026-06-28  
+**Status:** Not Started
+
+- [ ] Penetration testing (internal/external)
+- [ ] Threat model validation (verify all STRIDE mitigations)
+- [ ] Security control implementation review
+- [ ] Fuzz testing on API endpoints
+- [ ] Certificate validation testing
+- [ ] Config file tampering resistance testing
+- [ ] Privilege escalation testing
+- [ ] Fix all security findings
+- [ ] Security documentation completion
+
+---
+
+### Phase 4: Production Readiness
+**Duration:** 3 weeks  
+**Target Date:** 2026-06-28 to 2026-07-17  
+**Status:** Not Started
+
+- [ ] Performance optimization (benchmarking, profiling)
+- [ ] Documentation completion (README, deployment guide, API docs)
+- [ ] Deployment automation (package creation: .deb, .rpm)
+- [ ] Installation script development
+- [ ] User acceptance testing
+- [ ] Final security review
+- [ ] Production deployment checklist
+- [ ] Release v1.0.0
+
+---
+
+## Milestones
+
+| Milestone | Description | Target Date | Status |
+|-----------|-------------|-------------|--------|
+| M0 | Phase 0 complete (scaffolding) | 2026-04-12 | ⏳ Pending |
+| M1 | All spec documents complete | 2026-04-09 | ✅ Complete |
+| M2 | Development environment ready | 2026-04-15 | ⏳ Pending |
+| M3 | CI/CD pipeline operational | 2026-04-22 | ⏳ Pending |
+| M4 | mTLS + IP whitelist working | 2026-05-03 | ⏳ Pending |
+| M5 | Core API functional (Alpha) | 2026-06-07 | ⏳ Pending |
+| M6 | Security testing complete (Beta) | 2026-06-28 | ⏳ Pending |
+| M7 | Production release (v1.0.0) | 2026-07-17 | ⏳ Pending |
+
+---
+
+## Risk Register
+
+| ID | Risk | Likelihood | Impact | Mitigation Strategy | Owner |
+|----|------|------------|--------|---------------------|-------|
+| R001 | Rust learning curve delays development | Medium | Medium | Pair programming, Rust documentation, community support | Dev Team |
+| R002 | mTLS certificate management complexity | Medium | High | Early CA setup, detailed documentation, testing certs | Security |
+| R003 | Package manager API differences across distros | High | Medium | Pluggable backend architecture, extensive testing per distro | Dev Team |
+| R004 | Security vulnerabilities in dependencies | Low | High | cargo-audit in CI, regular dependency updates, minimal deps | Security |
+| R005 | Performance issues with concurrent jobs | Medium | Medium | Load testing in Phase 3, configurable concurrency limits | Dev Team |
+| R006 | Scope creep during development | Medium | High | Strict spec adherence, change control process | PM |
+| R007 | Internal CA infrastructure delays | Low | High | Start CA setup in Phase 0, use test certs for development | Security |
+| R008 | systemd integration issues | Low | Medium | Early systemd testing, reference existing Rust systemd services | Dev Team |
+
+---
+
+## Resource Requirements
+
+### Development Team
+| Role | Count | Commitment |
+|------|-------|------------|
+| Rust Developer | 1-2 | Full-time |
+| Security Engineer | 1 | Part-time (Phases 1, 3, 4) |
+| QA/Test Engineer | 1 | Part-time (Phases 2, 3, 4) |
+
+### Infrastructure
+| Resource | Purpose | Notes |
+|----------|---------|-------|
+| Development Server | Code development | Ubuntu 22.04 LTS |
+| Test Servers | Multi-distro testing | Ubuntu, Debian, RHEL, Alpine, Arch |
+| CI/CD Runner | Automated testing | GitHub Actions or self-hosted |
+| Internal CA | Certificate issuance | Separate secure host |
+
+### Tools & Services
+| Tool | Purpose | Cost |
+|------|---------|------|
+| Rust Toolchain | Development | Free |
+| cargo-audit | Security scanning | Free |
+| Git/Gitea | Version control | Self-hosted |
+| Wireshark | Network analysis | Free |
+| Burp Suite | Security testing | Community (Free) |
+
+---
+
+## Success Criteria
+
+### Phase 0 Success
+- [ ] Cargo project builds without errors
+- [ ] All dependencies resolved
+- [ ] Code quality tools configured and passing
+
+### Phase 1 Success
+- [ ] CI/CD pipeline runs on every commit
+- [ ] Test framework operational with >95% coverage target
+- [ ] Internal CA operational with test certificates
+
+### Phase 2 Success
+- [ ] All 15 API endpoints functional
+- [ ] mTLS authentication working
+- [ ] IP whitelist enforced
+- [ ] WebSocket streaming operational
+- [ ] Audit logging complete
+- [ ] Unit test coverage >95%
+
+### Phase 3 Success
+- [ ] Penetration testing complete with all critical findings resolved
+- [ ] Threat model validated
+- [ ] Security documentation complete
+
+### Phase 4 Success
+- [ ] Performance benchmarks met
+- [ ] Documentation complete
+- [ ] Package builds (.deb, .rpm) successful
+- [ ] UAT sign-off received
+- [ ] v1.0.0 released
+
+---
+
 *Following kiro spec-driven development standards*
diff --git a/SECURITY.md b/SECURITY.md
index fda7676..0fb9a95 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,61 +1,189 @@
 # Linux_Patch_API - Security Specification Document
 
 ## Security Overview
-[Describe security philosophy and approach]
 
-## Threat Model
-### Identified Threats
-[List potential threats to the system]
+**Philosophy:** Defense in depth with zero-trust principles for internal network.
 
-### Attack Vectors
-[Describe potential attack vectors]
-
-## Authentication & Authorization
-### Authentication Requirements
-- Method: [TBD]
-- Multi-factor: [TBD]
-- Session Management: [TBD]
-
-### Authorization Model
-- RBAC/ABAC: [TBD]
-- Permission Levels: [TBD]
-
-## Data Security
-### Encryption at Rest
-[Encryption standards for stored data]
-
-### Encryption in Transit
-[TLS/SSL requirements]
-
-### Key Management
-[Key storage and rotation policies]
-
-## API Security
-### Input Validation
-[Input sanitization requirements]
-
-### Rate Limiting
-[DoS prevention measures]
-
-### CORS Policy
-[Cross-origin resource sharing rules]
-
-## Audit & Logging
-### Security Events to Log
-[List events requiring audit trails]
-
-### Log Protection
-[Log integrity and access controls]
-
-## Compliance Requirements
-[Regulatory compliance considerations]
-
-## Security Testing
-### Penetration Testing
-[Testing schedule and scope]
-
-### Vulnerability Management
-[Patch and update procedures]
+**Approach:** 
+- mTLS certificate-based authentication (required for all connections)
+- IP whitelist enforcement (deny by default, allow only listed)
+- Comprehensive audit logging for all operations
+- Systemd hardening and process isolation
+- Minimal attack surface (internal network only)
 
 ---
+
+## Threat Model
+
+### Threat Actor Profile
+
+| Attribute | Description |
+|-----------|-------------|
+| **Origin** | Internal network only |
+| **Skill Level** | Moderate to High |
+| **Resources** | Limited (not nation-state) |
+| **Motivation** | Unauthorized system access, privilege escalation |
+| **Access** | Must bypass mTLS + IP whitelist |
+
+### STRIDE Threat Analysis
+
+| Threat Category | Potential Threat | Mitigation | Status |
+|-----------------|------------------|------------|--------|
+| **Spoofing** | Attacker impersonates valid client | mTLS certificate validation, unique certs per client | ✅ Mitigated |
+| **Spoofing** | Attacker uses expired/revoked cert | Certificate expiry validation (1-year max) | ✅ Mitigated |
+| **Tampering** | API requests modified in transit | TLS 1.3 encryption | ✅ Mitigated |
+| **Tampering** | Config files modified unauthorized | File permissions (600/644), config validation before reload | ✅ Mitigated |
+| **Repudiation** | Client denies making request | Audit logging with request_id, client cert ID | ✅ Mitigated |
+| **Repudiation** | Server denies response | Comprehensive audit trail (systemd journal) | ✅ Mitigated |
+| **Information Disclosure** | Package/data info leaked to unauthorized | Silent drop for non-mTLS, IP whitelist | ✅ Mitigated |
+| **Information Disclosure** | Error messages leak system info | Detailed errors only for authenticated clients | ✅ Mitigated |
+| **Denial of Service** | Resource exhaustion via many requests | Internal network only, IP whitelist limits exposure | ⚠️ Partial |
+| **Denial of Service** | Job queue flooding | Configurable concurrent job limit (default: 5) | ✅ Mitigated |
+| **Denial of Service** | Long-running job starvation | 30-minute job timeout enforcement | ✅ Mitigated |
+| **Elevation of Privilege** | Unauthorized package installation | Root required, but mTLS + IP whitelist required | ✅ Mitigated |
+| **Elevation of Privilege** | Subprocess escape | SystemCallFilter, ProtectSystem=strict | ✅ Mitigated |
+
+### Attack Vectors & Mitigations
+
+| Attack Vector | Likelihood | Impact | Mitigation |
+|---------------|------------|--------|------------|
+| Network interception | Low | Critical | TLS 1.3 only, mTLS required |
+| Certificate theft | Medium | Critical | Cert permissions (600), internal CA only |
+| IP spoofing | Low | High | IP whitelist + mTLS (both required) |
+| Config file tampering | Medium | High | File permissions, validation before reload |
+| Package manager injection | Low | Critical | Pluggable backend with input validation |
+| Job manipulation | Low | High | Job storage isolation, exclusive rollback mode |
+| Log tampering | Medium | High | systemd journal (immutable), optional remote syslog |
+
+---
+
+## Authentication & Authorization
+
+### Authentication Requirements
+
+- **Method:** mTLS certificate-based authentication
+- **Certificate Type:** Unique client certificate per client (1-year validity)
+- **CA:** Internal self-hosted Certificate Authority
+- **TLS Version:** TLS 1.3 only
+- **Multi-factor:** Certificate + IP whitelist (dual requirement)
+- **Session Management:** Stateless (no sessions)
+
+### Authorization Model
+
+- **Model:** Binary authorization (all-or-nothing)
+- **Permission Levels:** Single level (full access if authenticated)
+- **Requirements:**
+  - Valid mTLS certificate (not expired, signed by internal CA)
+  - Source IP in whitelist (YAML config, instant apply)
+- **No RBAC:** All authenticated clients have full API access
+
+---
+
+## Data Security
+
+### Encryption at Rest
+
+- **Certificates:** File permissions 600 for private keys
+- **Job Storage:** `/var/lib/linux_patch_api/jobs/` (cleared on restart)
+- **Config Files:** `/etc/linux_patch_api/` (644 for config, 600 for keys)
+- **Audit Logs:** systemd journal (immutable by default)
+
+### Encryption in Transit
+
+- **Protocol:** TLS 1.3 only
+- **Port:** 12443
+- **Cipher Suites:** TLS 1.3 default (no legacy cipher support)
+- **Certificate Validation:** Mutual TLS (server + client cert required)
+
+### Key Management
+
+- **CA Private Key:** Stored securely on CA host only
+- **Server Certificates:** `/etc/linux_patch_api/certs/server.key` (600)
+- **Client Certificates:** Distributed manually to authorized clients
+- **Rotation:** 1-year certificate expiry, manual renewal process
+- **Revocation:** Not implemented (rely on expiry + physical cert retrieval)
+
+---
+
+## API Security
+
+### Input Validation
+
+- **Package Names:** Alphanumeric + standard package chars only
+- **Versions:** Semantic versioning validation
+- **IP Addresses:** IPv4 + CIDR validation for whitelist
+- **JSON Schema:** Strict schema validation for all request bodies
+- **Path Traversal:** Blocked (no `..` in paths)
+
+### Rate Limiting
+
+- **Not Required:** Internal network only with strict IP whitelist
+- **Job Concurrency:** Configurable limit (default: 5 concurrent jobs)
+- **Job Timeout:** 30-minute maximum per job
+
+### CORS Policy
+
+- **Not Applicable:** API is not browser-accessible
+- **Origin:** mTLS clients only (no browser CORS concerns)
+
+---
+
+## Audit & Logging
+
+### Security Events to Log
+
+- All API requests (endpoint, method, timestamp, client cert ID, source IP)
+- Authentication events (success/failure, cert validation result)
+- Authorization events (IP whitelist match/failure)
+- Package operations (package name, version, action, result)
+- Configuration changes (config reload, whitelist updates)
+- Job lifecycle events (create, start, complete, fail, timeout, rollback)
+- Service events (start, stop, restart, config validation failures)
+
+### Log Protection
+
+- **Primary Storage:** systemd journal (immutable, access-controlled)
+- **Secondary Storage:** Optional remote syslog
+- **Fallback:** Local file `/var/log/linux_patch_api/audit.log` (640)
+- **Retention:** 30 days with daily rotation and compression
+- **Access:** Root only, audit group read access
+- **Integrity:** systemd journal provides tamper evidence
+
+---
+
+## Compliance Requirements
+
+- **Internal Standards:** Follows organizational security policies
+- **No External Compliance:** Not designed for PCI-DSS, HIPAA, SOC2 (can be extended)
+- **Audit Trail:** Comprehensive logging supports internal audit requirements
+- **Access Control:** mTLS + IP whitelist provides strong access control
+
+---
+
+## Security Testing
+
+### Penetration Testing
+
+- **Schedule:** Required before production deployment
+- **Scope:**
+  - mTLS authentication bypass attempts
+  - IP whitelist enforcement testing
+  - API endpoint fuzzing
+  - Certificate validation testing
+  - Config file tampering attempts
+  - Privilege escalation attempts
+- **Tester:** Internal security team or external contractor
+- **Frequency:** Annual or after major changes
+
+### Vulnerability Management
+
+- **Dependency Scanning:** Rust crate security advisories monitored
+- **System Patches:** Host system patched via API itself (dogfooding)
+- **Certificate Updates:** Annual renewal process
+- **Config Audits:** Quarterly review of whitelist and security settings
+- **Incident Response:** Log analysis for security event investigation
+
+---
+
+*Following kiro spec-driven development standards*
 *Following kiro spec-driven development standards*
diff --git a/SPEC.md b/SPEC.md
index e30f62e..955c526 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -7,19 +7,216 @@
 **Status:** Draft  
 
 ## Scope
-[Define project scope here]
+
+**Primary Focus:** Debian/Ubuntu (apt/dpkg)  
+**Secondary Support:** RHEL/CentOS/Fedora (dnf/yum), Alpine (apk), Arch (pacman)  
+
+**In Scope:**
+- Remote package installation, removal, and updates
+- System patch management (security and general updates)
+- Multi-distribution support via pluggable package manager backend
+- Secure authentication and authorization for remote operations
+- Audit logging of all package/patch operations
+- RESTful API design with JSON request/response
+
+**Supported Operations:**
+- **Core Package:** GET /packages (with filtering), GET /packages/{name}, POST /packages (install), PUT /packages/{name} (update), DELETE /packages/{name} (remove)
+- **Patch Management:** GET /patches (list available), POST /patches/apply (apply all or specific)
+- **System Info:** GET /system/info (OS version, kernel, last update time)
+
+**Operation Features:**
+- Version pinning support (e.g., package=1.2.3)
+- Rollback capability for failed operations
+- Batch operations: best-effort (not atomic)
+- GET filtering: by name, version, status, upgradable
+- No pagination (return all results)
+
+**Out of Scope (for now):**
+- GUI/frontend interface (API-only)
+- Automatic scheduled patching (manual trigger only)
+- Cross-distribution package compatibility
 
 ## Objectives
-[List primary objectives]
+
+**Primary Objective:** Provide secure API for remote patch/package management on individual Linux hosts
+
+**Key Goals:**
+- Run as systemd service on each managed machine (Option B: Agent Per Host)
+- Internal network access only (no internet exposure)
+- Support Debian/Ubuntu first, then expand to other distributions
+- Maintain audit trail of all operations
+- Minimal resource footprint
+- mTLS certificate-based authentication
+- IP whitelist enforcement (deny by default)
 
 ## Constraints
-[List technical and operational constraints]
+
+**Deployment:**
+- One API instance per host
+- Internal network only (LAN/private network)
+- No public internet exposure
+- Must run as systemd service
+
+**Technical:**
+- Must run with elevated privileges for package management (root/sudo)
+- Must support multiple Linux distributions
+- API-only (no GUI required)
+- mTLS required for all client connections
+- IP whitelist enforcement required (block all by default, allow only listed)
+- Technology: Rust with Actix-web or Axum framework
+- Default API port: 12443
+- API Style: Pure REST (resources as nouns, HTTP verbs for actions)
+- Data Format: JSON for all requests and responses
+- Response Envelope: Standard envelope with success, request_id, timestamp, data, error fields
+- Request IDs: Required for all requests (tracking and auditing)
+- Execution Model: Hybrid (sync for quick ops, async with job ID for long ops)
+- Real-time Updates: WebSocket support for job status streaming
+- Job Timeout: Maximum 30 minutes per operation
+
+**Security:**
+- Certificate-based authentication (mTLS)
+- Network-level access control via IP/subnet whitelist
+- Silent drop for non-mTLS connections (no response)
+- Detailed error messages for authenticated clients only
+
+## Error Handling
+
+- **HTTP Status Codes:** Standard HTTP status codes (200, 400, 401, 403, 404, 500, etc.)
+
+- **Error Response Format** (inside envelope's `error` field):
+```json
+{
+  "code": "ERROR_CODE",
+  "message": "Human-readable description",
+  "details": {},
+  "retryable": false
+}
+```
+
+- **Error Categories:**
+  - Authentication failures (invalid/expired cert)
+  - Authorization failures (valid cert but not whitelisted IP)
+  - Package not found
+  - Package manager errors (dpkg/apt failures)
+  - Permission denied
+  - System resource errors
+  - Configuration errors
+
+- **Error Message Policy:**
+  - mTLS confirmed clients: Detailed error messages with debugging info
+  - Non-mTLS connections: Silent drop (no response sent)
+  - DEBUG mode: Include additional diagnostic information
+
+- **Idempotency:** Operations should be idempotent where possible (safe to retry)
 
 ## Assumptions
-[Document key assumptions]
+
+- Host machines have network connectivity to internal clients
+- API clients are trusted internal systems
+- Host OS has Rust toolchain available (or can be installed)
+- Package manager (apt/dnf/apk/pacman) is functional on target hosts
 
 ## Dependencies
-[External dependencies and integrations]
+
+- Linux OS with package manager support
+- systemd for service management
+- Network access for API communication
+- mTLS certificate infrastructure (CA, client certs)
+- IP whitelist configuration
+- Rust toolchain (rustc, cargo)
+- Actix-web or Axum framework
+- Internal CA for certificate issuance (self-hosted)
+
+## Certificate Management
+
+- **CA Type:** Internal self-hosted Certificate Authority
+- **Distribution:** Manual certificate distribution to clients
+- **Scope:** Limited distribution (small number of authorized clients)
+- **Validity Period:** 1 year standard expiration
+- **Client Identity:** Unique certificate per client (no shared certs)
+- **Rotation:** Manual renewal process before expiration
+
+## Audit Logging
+
+- **Log Content (All Required):**
+  - Every API request (endpoint, method, timestamp, client cert ID)
+  - Package operations (package name, version, action: install/remove/update)
+  - Authentication events (success/failure, cert validation)
+  - IP whitelist denials (blocked connection attempts)
+  - System changes made by the API
+  - Configuration changes (whitelist updates, cert renewals)
+
+- **Log Storage:**
+  - Primary: systemd journal (`journalctl`)
+  - Secondary: Optional remote syslog server
+  - Local file logs as fallback (`/var/log/linux_patch_api/`)
+
+- **Log Retention:**
+  - Retention period: 30 days
+  - Rotation: Daily
+  - Compression: Enabled (gzip)
+
+- **Log Levels:** Configurable at runtime (DEBUG, INFO, WARN, ERROR)
+
+## IP Whitelist Configuration
+
+- **Config File:** `/etc/linux_patch_api/whitelist.yaml`
+- **Format:** YAML
+- **Management:** Static config file (edit file to change)
+- **Apply Method:** Instant apply on file change (no restart required)
+- **Logging:** All whitelist changes logged to audit log
+
+- **Supported Entries:**
+  - Individual IPv4 addresses (e.g., `192.168.1.100`)
+  - CIDR subnets (e.g., `192.168.1.0/24`)
+  - Hostnames (resolved at config load)
+  - IPv6: Not supported (explicitly out of scope)
+
+- **Default Behavior:** Block all connections not in whitelist
+
+## API Configuration Management
+
+- **Config File:** `/etc/linux_patch_api/config.yaml`
+- **Format:** YAML
+- **Reload Method:** Config file watch with auto-reload on change (no restart required)
+
+- **Configurable Settings:**
+  - **Server:** port, bind address, timeout settings
+  - **mTLS:** CA cert path, server cert path, server key path
+  - **Logging:** log level, log retention, remote syslog server (optional)
+  - **Security:** job timeout, max concurrent jobs, rate limiting
+
+- **Hard-Coded Paths (not configurable):**
+  - Whitelist file: `/etc/linux_patch_api/whitelist.yaml`
+  - Data directory: `/var/lib/linux_patch_api/`
+  - Job storage: `/var/lib/linux_patch_api/jobs/`
+- Hard-Coded Paths (not configurable):
+  - Whitelist file: `/etc/linux_patch_api/whitelist.yaml`
+  - Data directory: `/var/lib/linux_patch_api/`
+  - Job storage: `/var/lib/linux_patch_api/jobs/`
+  - Log directory: `/var/log/linux_patch_api/`
+
+## Testing Requirements
+
+- **Unit Test Coverage:** Minimum 95%
+- **Integration Tests:** API endpoint testing with mock package manager
+- **Security Tests:** mTLS validation, IP whitelist enforcement, authentication failures
+- **End-to-End Tests:** Full workflow testing on actual Ubuntu systems
+
+- **Test Environments:**
+  - Primary: Ubuntu (latest LTS)
+  - CI/CD Pipeline: Required for automated testing
+  - Penetration Testing: Required before release
+
+- **Phase 1 Acceptance Criteria:**
+  - All endpoints functional with mTLS authentication
+  - IP whitelist enforced correctly
+  - Audit logging working (journalctl + file)
+  - Config auto-reload working
+  - WebSocket status streaming functional
+  - Rollback mechanism tested
+
+- **Security Audit:** No formal audit planned at this time
 
 ---
 *Following kiro spec-driven development standards*