# Neith Linux Developer Guide

This guide is for contributors extending `@neith/linux`.

## Prerequisites

| Tool  | Minimum Version       | Purpose                                               |
| ----- | --------------------- | ----------------------------------------------------- |
| Rust  | stable / 2021 edition | Workspace crate development                           |
| Cargo | bundled with Rust     | Build, test, lint, and formatting                     |
| Nix   | flakes enabled        | Flake validation, package composition, and ISO builds |

## Workspace Layout

```text
libs/neith/linux/
  Cargo.toml            Rust workspace root
  flake.nix             system and ISO flake outputs
  iso/                  full, minimal, and recovery ISO definitions
  modules/neith/        Neith workstation, services, update, and rollback modules
  modules/profiles/     installation/live profile composition
  packages/             package flake, catalog, overlay, templates
  crates/
    neith-distro-core
    neith-pkg-manager
    neith-update-agent
    neith-services
    neith-installer
    ...
```

## Development Rules

- Keep module and flake outputs reproducible. Do not hide environment-specific
  assumptions in generated commands or Nix expressions.
- Preserve the separation between sovereign core behavior and transitional
  compatibility integrations.
- When you add a new Rust crate, wire it into the Cargo workspace and explain
  its role in the Neith Linux docs.
- When you add a new NixOS capability, keep the owning module explicit and
  update the self-hostability evidence if that capability supports a certified
  Phase 52 claim.

## Verification Commands

```bash
pnpm nx run @neith/linux:build
pnpm nx run @neith/linux:test
pnpm nx run @neith/linux:lint
pnpm nx run @neith/linux:fmt
pnpm nx run @neith/linux:nix-check
```

`build-iso` is available when you need to materialize the ISO output directly,
but `nix-check` is the normal fast verification path for documentation and
configuration changes.

## High-Value Extension Areas

- `modules/neith/` for platform policy, services, rollback, updates, security,
  and workstation behavior
- `packages/` for sovereign package definitions and overlay behavior
- `iso/` for full, minimal, and recovery image composition
- `crates/` for package lifecycle, update transactions, installation, and
  service runtime capabilities

## Cross-Surface Coordination

`@neith/linux` is not isolated work. Changes here often need corresponding
updates in:

- `docs/domains/neith/linux/` for contributor documentation
- `docs/domains/neith/core-neith-stack-self-hostability-certification.md` when
  self-hostability evidence changes
- `docs/domains/neith/phase-52-sbom.*.json` when the workspace component
  inventory changes
- `@neith/qa` auditors and tests when a certification boundary moves
