# Neith Linux User Guide

This guide is for operators and users working with the implemented Neith Linux
platform surface.

## What Neith Linux Includes

The current Neith Linux repository footprint provides:

- a flake-based Neith Linux workspace
- full, minimal, and recovery ISO image definitions
- NixOS modules for workstation behavior, services, security, updates, and
  rollback
- package, overlay, and catalog infrastructure
- Rust crates for installer, package lifecycle, update-agent, and system
  services

## Getting Started

### Choose The Right Image

- use the full image for a complete workstation-style validation environment
- use the minimal image for constrained or focused bring-up work
- use the recovery image when the goal is diagnosis, repair, or rollback support

### Install Or Boot

1. Build or obtain the desired ISO image.
2. Boot the target machine or VM from that image.
3. Select the appropriate installation or live environment profile.
4. Complete the installation flow and reboot into the installed system.

## First Boot Checklist

After booting into the system:

- confirm the system identity and expected Neith profile are present
- verify required services are running
- confirm package and overlay state matches the intended deployment
- check that the update and rollback components are available before relying on
  the machine operationally

## Updates And Recovery

### Standard Updates

Use the normal system update path when adopting a new tested system state. For
production-like deployments, validate the update flow on a non-critical machine
first.

### Rollback And Recovery

Neith Linux includes explicit rollback and recovery-oriented surfaces. Use them
when:

- an update fails validation
- a boot target regresses
- a service change needs immediate reversal
- you need to recover using the dedicated recovery image

## Package And Integration Options

Neith Linux is designed around sovereign package and system composition, but the
current Phase 52 footprint still allows explicitly configured transitional
integrations where needed.

Examples include:

- optional external binary caches
- optional Flatpak integration for selected user workflows

Treat those as deliberate compatibility choices, not implicit defaults.

## Common Tasks

### Validate A New Image

1. Build the intended image variant.
2. Boot it in a VM or validation machine.
3. Confirm required packages, modules, and services are present.
4. Exercise update and rollback behavior before broader rollout.

### Prepare A Recovery Path

1. Keep the recovery image available for the target hardware class.
2. Rehearse a failed-update scenario on a non-production system.
3. Confirm the rollback path restores the expected prior state.

## Troubleshooting

| Symptom                                     | First Check                                                         |
| ------------------------------------------- | ------------------------------------------------------------------- |
| System did not boot as expected             | selected image/profile and system configuration                     |
| Update did not apply cleanly                | update-agent path and channel inputs                                |
| Recovery path not available                 | recovery image availability and rollback configuration              |
| Optional integrations behaving unexpectedly | whether Flatpak or external cache support was intentionally enabled |

## Related Documentation

- [Neith Linux Overview](./README.md)
- [Neith Domain User Guide](../user-guide.md)
- [Neith Linux Developer Guide](./developer-guide.md)
- [Core Neith Stack Self-Hostability Certification](../core-neith-stack-self-hostability-certification.md)
