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/releasefor release management, distribution, publishing, and release quality gates@neith/qafor repository auditors, certification ledgers, and doc/code gate enforcement@neith/linuxfor 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:
- Extend the implementation surface.
- Update or add automated verification.
- Update the relevant standalone docs under
docs/domains/neith/. - If the change affects a Phase 52 completion criterion, update the matching
@neith/qacertification 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.mdand 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:
- Add or update an auditor in
libs/neith/qa/src/code-quality/. - Add a repo-backed Vitest spec for the auditor.
- Publish or refresh the generated certification markdown in
docs/domains/neith/. - Link the certification from the domain index and Oshun-local references.
- Check the corresponding item in
TODOS/phase-52.md.