aipackage/specs/001-enterprise-experience/plan.md

# Implementation Plan: Enterprise Appliance Experience Hardening

**Branch**: `001-enterprise-experience` | **Date**: 2026-07-12 | **Spec**: [spec.md](spec.md)

**Input**: Feature specification from `specs/001-enterprise-experience/spec.md`

## Summary

Harden Nexus One AI through three independently accepted phases: setup/readiness, daily
administration, and recovery/support. Preserve the current static portal, FastAPI management API,
SQLite appliance data, shell/Ansible installer, and license compatibility model. Introduce shared
experience contracts for truthful states, durable operations, redacted support evidence, consistent
entitlements, accessibility, and release provenance rather than replacing the product architecture.

## Technical Context

**Language/Version**: Python 3.11; browser-native HTML/CSS/JavaScript; Bash; Ansible YAML

**Primary Dependencies**: FastAPI 0.111+, Uvicorn 0.29+, python-jose, passlib/bcrypt, psutil,
APScheduler, Nginx, systemd, Ansible, Ubuntu autoinstall

**Storage**: SQLite at `/opt/cezen/data/cezen.db`; JSON appliance records under `/opt/cezen`;
filesystem backups under `/opt/cezen/backups`; systemd journal and install logs

**Testing**: Python unit/contract tests to be added around backend state and redaction; browser
journey and accessibility checks; shell/static validation; Ansible syntax checks; clean-install,
upgrade, interruption, backup/restore, pilot, and packaged-artifact verification

**Target Platform**: Nexus One AI Workstation and Server appliances on Ubuntu 22.04, accessed through
supported desktop browsers on customer-controlled networks

**Project Type**: On-premises appliance package containing a static web portal, management API,
installer, deployment automation, system services, and ISO build paths

**Performance Goals**: Readiness visible within 10 seconds of portal entry under normal appliance
conditions; local navigation feedback within 1 second; operation acknowledgement within 2 seconds;
progress freshness appropriate to the underlying operation and never presented as live when stale

**Constraints**: Restricted/offline operation after installation; existing `starter/basic/pro/max`
compatibility identifiers; Workstation remains outside the Server tier ladder; no fabricated runtime
state; secrets excluded from diagnostics; WCAG 2.2 AA; safe migration of existing SQLite appliances;
no unsupported HA or recovery claims

**Scale/Scope**: Approximately 60 static portal pages, one large FastAPI service, two first-boot
interfaces, four Server tiers plus Workstation packaging, multiple Ansible roles, and three ISO build
paths. Phase 1 is limited to setup/readiness on one representative Workstation and one representative
Server configuration.

## Constitution Check

*GATE: Passed before Phase 0 and re-checked after Phase 1 design.*

- **Enterprise experience — PASS**: The spec and UI contract define primary, loading, empty, ready,
  degraded, failed, restricted, stale, and recovery states with consistent terminology.
- **Lifecycle safety — PASS**: Operation state is durable; setup, interruption, backup/restore,
  upgrade, retry, resume, rollback, and escalation responsibilities are explicitly mapped.
- **Security and audit — PASS**: Existing server-side authorization is preserved; new audit and
  support-evidence contracts require redaction, actor, scope, result, and correlation identifiers.
- **Entitlement and packaging — PASS**: The plan preserves internal identifiers, keeps Workstation
  separate, and requires portal/API/installer/Ansible/documentation/ISO consistency evidence.
- **Evidence — PASS**: Quickstart validation distinguishes static, local, deployed, live-appliance,
  pilot, and release-artifact evidence.

Post-design re-check: PASS. No constitutional exception is required.

## Phased Design

### Phase 1 — Setup and Readiness

1. Establish canonical customer-facing state, severity, entitlement, operation, and error vocabulary.
2. Make browser and console setup persist non-secret progress and expose safe resume/retry behaviour.
3. Replace process-local install status as the sole truth with a durable operation record.
4. Normalize readiness into a customer-impact view with freshness and actionable next steps.
5. Align Workstation and representative Server setup/readiness behaviour.
6. Validate WCAG 2.2 AA, clean install, interruption, restricted-network guidance, and artifact
   provenance before pilot.

### Phase 2 — Daily Administration

1. Introduce shared portal presentation helpers for status, errors, operations, entitlement, and
   accessible announcements while retaining static delivery.
2. Apply the common shell and state contract first to dashboard, appliance, health, licensing,
   users/security, models, and knowledge journeys.
3. Remove fabricated production examples or label them explicitly as samples.
4. Provide a unified operations history for consequential and long-running actions.
5. Add role-aware orientation and locally available contextual guidance.
6. Complete the daily-administration portions of entitlement consistency and guided handover.

### Phase 3 — Recovery and Support

1. Model backup, restore, restart, upgrade, removal, diagnostic export, and escalation as authorized,
   durable operations.
2. Add redacted support-evidence generation and correlation across API, audit, install, and service
   state.
3. Define recovery preconditions, customer impact, confirmation, progress, outcome, and next action.
4. Validate upgrade/interruption/rollback paths and controlled pilot results before general release.

Entitlement consistency is a cross-cutting workstream spanning all three delivery phases. Guided
handover is accepted within Delivery Phase 2. These workstreams do not create additional delivery
phases or alter the approved order.

## Project Structure

### Documentation (this feature)

```text
specs/001-enterprise-experience/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── customer-experience-contract.md
└── checklists/
    └── requirements.md
```

### Source Code (repository root)

```text
autoinstall/
├── websetup/server.py          # browser setup and current process-local install state
├── firstboot-setup.sh         # console setup flow
├── user-data*                # ISO-specific first-boot entrypoints
└── build-iso*.sh             # Workstation/Server ISO build paths

cezen-portal/
├── branding.js               # shared branding/entitlement behaviour
├── auth.js                   # session and role enforcement
├── style.css                 # shared design/accessibility primitives
├── index.html                # primary landing experience
├── appliance.html            # readiness, license, audit, backup/restore
├── health.html               # subsystem health experience
└── *.html                    # remaining administration and user journeys

ansible/roles/cezen-backend/
├── files/main.py             # API, SQLite model, audit, readiness, backups
├── files/cezen_license.py    # deployed entitlement helper
├── files/cezen-api.service   # runtime contract
└── tasks/main.yml            # backend deployment

ansible/roles/cezen-nginx/          # static portal deployment and routing
scripts/cezen_license.py            # canonical source entitlement helper
scripts/cezen-backup.sh             # appliance backup/restore utility
install.sh                          # phase orchestration and install record
ansible/{starter,entry,pro,max}.yml # Server deployment profiles
```

**Structure Decision**: Extend the existing appliance package in place. Keep the static portal and
single management service for this initiative; extract shared modules only where needed to enforce
one state/operation contract. Treat `scripts/cezen_license.py` as the canonical entitlement source
and keep deployed copies synchronized through explicit verification.

## Migration and Compatibility Strategy

- Additive SQLite changes MUST use idempotent migrations executed before new reads/writes; startup
  `CREATE TABLE IF NOT EXISTS` alone is insufficient for column evolution.
- Existing endpoints remain compatible during each phase. New envelope fields are additive until all
  packaged portal consumers migrate.
- Existing install and license JSON fields remain readable. New operation/progress data is separate
  and excludes raw signed license payloads.
- Existing backups remain restorable; schema version and compatibility are checked before mutation.
- Removal preserves backups by default, explicitly inventories retained/deleted data, and records the
  limits of rollback before confirmation.
- Portal, API, installer, canonical/deployed license helpers, Ansible roles, docs, and ISO contents are
  compared during release validation.

## Complexity Tracking

No constitutional violations require justification.