# Neith Domain Developer Guide

This guide covers the implemented Neith developer surfaces in Phase 52:
`@neith/release`, `@neith/qa`, and `@neith/linux`.

## Current Scope

Neith is still broader in planning than in repository implementation. The
current contributor workflow is centered on three concrete surfaces:

- `@neith/release` for release management, distribution, publishing, and release
  quality gates
- `@neith/qa` for repository auditors, certification ledgers, and doc/code gate
  enforcement
- `@neith/linux` for Neith Linux build, module, package, and update
  infrastructure used by the self-hostability story

## Prerequisites

| Tool    | Minimum Version       | Purpose                                                    |
| ------- | --------------------- | ---------------------------------------------------------- |
| Node.js | >= 20                 | Workspace scripts, Nx, Vitest, and TypeScript tooling      |
| pnpm    | >= 9                  | Workspace package management                               |
| Rust    | stable / 2021 edition | `@neith/linux` crates and validation                       |
| Cargo   | bundled with Rust     | Build, test, lint, and formatting for Linux crates         |
| Nix     | flakes enabled        | `@neith/linux` flake validation and ISO build verification |

## Workspace Layout

```text
libs/neith/
  release/   release orchestration, distribution, publishing, performance gates
  qa/        auditors, certification generators, doc/code quality analysis
  linux/     flake, NixOS modules, ISO pipeline, Rust crates, package lifecycle

docs/domains/neith/
  README.md           domain docs hub
  developer-guide.md  this guide
  release/            release package docs
  qa/                 QA package docs
  linux/              Linux package docs
  *.md / *.json       Phase 52 certification ledgers and SBOM artifacts
```

## Core Workflow

Start from the implemented package that owns the behavior you are changing:

- release-control-plane work belongs in `libs/neith/release`
- certification, evidence, and gate logic belongs in `libs/neith/qa`
- self-hosting and workstation/platform work belongs in `libs/neith/linux`

Any material Neith change should update both implementation and evidence:

1. Extend the implementation surface.
2. Update or add automated verification.
3. Update the relevant standalone docs under `docs/domains/neith/`.
4. If the change affects a Phase 52 completion criterion, update the matching
   `@neith/qa` certification gate and published certification document.

## Verification Commands

Run the commands that match the surfaces you touched.

### Release Surface

```bash
pnpm nx run @neith/release:typecheck
pnpm nx run @neith/release:lint
pnpm nx run @neith/release:test
pnpm nx run @neith/release:integration
pnpm nx run @neith/release:e2e
pnpm nx run @neith/release:benchmark
```

### QA Surface

```bash
pnpm nx run @neith/qa:typecheck
pnpm nx run @neith/qa:lint
pnpm nx run @neith/qa:test
pnpm nx run @neith/qa:sbom
```

### Linux Surface

```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
```

## Documentation Rules

- Keep the standalone Neith docs tree aligned with the implemented footprint,
  not the full long-range TODO scope.
- Prefer evidence-oriented docs: package overviews, developer guides, user/API
  guides, runbooks, training material, and certification ledgers.
- When you add a new certification gate, link it from
  `docs/domains/neith/README.md` and update the Oshun-local reference pages.
- When a guide becomes stale, fix the guide and the enforcement logic together.
  Narrative docs without an automated gate tend to drift.

## Extending Phase 52 Certifications

Phase 52 completion criteria are treated as auditable claims. The expected
pattern is:

1. Add or update an auditor in `libs/neith/qa/src/code-quality/`.
2. Add a repo-backed Vitest spec for the auditor.
3. Publish or refresh the generated certification markdown in
   `docs/domains/neith/`.
4. Link the certification from the domain index and Oshun-local references.
5. Check the corresponding item in `TODOS/phase-52.md`.

## Package-Specific Guides

- [Neith Release Overview](./release/README.md)
- [Neith Release Developer Guide](./release/developer-guide.md)
- [Neith QA Overview](./qa/README.md)
- [Neith QA Developer Guide](./qa/developer-guide.md)
- [Neith Linux Overview](./linux/README.md)
- [Neith Linux Developer Guide](./linux/developer-guide.md)
