da6aa7f50a
PHASE 27: THE GLYPH & THE GHOST (Visual Cortex Polish)
========================================================
- Replaced placeholder block font with full IBM VGA 8x16 bitmap (CP437)
- Implemented CRT scanline renderer for authentic terminal aesthetics
- Set Sovereign Blue background (0xFF401010) with Phosphor Amber text
- Added ANSI escape code stripper for clean graphical output
- Updated QEMU hints to include -device virtio-gpu-device
Files:
- core/rumpk/libs/membrane/term.nim: Scanline renderer + ANSI stripper
- core/rumpk/libs/membrane/term_font.nim: Full VGA bitmap data
- src/nexus/forge.nim: QEMU device flag
- docs/dev/PHASE_26_VISUAL_CORTEX.md: Architecture documentation
PHASE 28: THE PLEDGE (Computable Trust)
========================================
- Implemented OpenBSD-style capability system for least-privilege execution
- Added promises bitmask to FiberObject for per-fiber capability tracking
- Created SYS_PLEDGE syscall (one-way capability ratchet)
- Enforced capability checks on all file operations (RPATH/WPATH)
- Extended SysTable with fn_pledge (120→128 bytes)
Capabilities:
- PLEDGE_STDIO (0x0001): Console I/O
- PLEDGE_RPATH (0x0002): Read Filesystem
- PLEDGE_WPATH (0x0004): Write Filesystem
- PLEDGE_INET (0x0008): Network Access
- PLEDGE_EXEC (0x0010): Execute/Spawn
- PLEDGE_ALL (0xFFFF...): Root (default)
Files:
- core/rumpk/core/fiber.nim: Added promises field
- core/rumpk/core/ion.nim: Capability constants + SysTable extension
- core/rumpk/core/kernel.nim: k_pledge + enforcement checks
- core/rumpk/libs/membrane/ion_client.nim: Userland ABI sync
- core/rumpk/libs/membrane/libc.nim: pledge() wrapper
- docs/dev/PHASE_28_THE_PLEDGE.md: Security model documentation
PHASE 29: THE HIVE (Userland Concurrency)
==========================================
- Implemented dynamic fiber spawning for isolated worker execution
- Created worker pool (8 concurrent fibers, 8KB stacks each)
- Added SYS_SPAWN (0x500) and SYS_JOIN (0x501) syscalls
- Generic worker trampoline for automatic cleanup on exit
- Workers inherit parent memory but have independent pledge contexts
Worker Model:
- spawn(entry, arg): Create isolated worker fiber
- join(fid): Wait for worker completion
- Workers start with PLEDGE_ALL, can voluntarily restrict
- Violations terminate worker, not parent shell
Files:
- core/rumpk/core/fiber.nim: user_entry/user_arg fields
- core/rumpk/core/kernel.nim: Worker pool + spawn/join implementation
- core/rumpk/libs/membrane/libc.nim: spawn()/join() wrappers
- docs/dev/PHASE_29_THE_HIVE.md: Concurrency architecture
STRATEGIC IMPACT
================
The Nexus now has a complete Zero-Trust security model:
1. Visual identity (CRT aesthetics)
2. Capability-based security (pledge)
3. Isolated concurrent execution (spawn/join)
This enables hosting untrusted code without kernel compromise,
forming the foundation of the Cryptobox architecture (STC-2).
Example usage:
proc worker(arg: uint64) {.cdecl.} =
discard pledge(PLEDGE_INET | PLEDGE_STDIO)
http_get("https://example.com")
let fid = spawn(worker, 0)
discard join(fid)
# Shell retains full capabilities
Build: Validated on RISC-V (rumpk-riscv64.elf)
Status: Production-ready
|
||
|---|---|---|
| .. | ||
| cli | ||
| schemas | ||
| security | ||
| Beyond Devcontainers_ Introducing nexus target devcell.md | ||
| DEPENDENCY_RESOLUTION.md | ||
| DEVELOPER_GUIDE.md | ||
| HASH_ALGORITHM_MIGRATION.md | ||
| INTEGRATION_GUIDE.md | ||
| License_and_Compliance.md | ||
| NIPCELLS_SUPERIORITY.md | ||
| NIPPELS_DEVELOPER_GUIDE.md | ||
| NIPPELS_EXAMPLES.md | ||
| NIPPELS_TROUBLESHOOTING.md | ||
| NIPPELS_USER_GUIDE.md | ||
| NIPPELS_VS_FLATPAK.md | ||
| NIPPELS_VS_PACKAGES.md | ||
| NexusOS_Architecture_Overview.md | ||
| NexusOS_Package_Management.md | ||
| OPTIMIZATION_GUIDE.md | ||
| README.md | ||
| RESOLVER_DEVELOPER_GUIDE.md | ||
| RESOLVER_VISUAL_GUIDE.md | ||
| USER_GUIDE.md | ||
| arch-linux-guide.md | ||
| architecture.md | ||
| automatic-updates.md | ||
| binary-cache.md | ||
| bootstrap-api.md | ||
| bootstrap-detection-flow.md | ||
| bootstrap-guide.md | ||
| bootstrap-overview.md | ||
| build-configuration.md | ||
| build-examples.md | ||
| build-flow.md | ||
| build-system-help.md | ||
| build-troubleshooting.md | ||
| build_system.md | ||
| butane_ignition_integration for internet deployments.md | ||
| cas-security-architecture.md | ||
| container-builds.md | ||
| dependency-resolution.md | ||
| enhanced-cli-interface.md | ||
| formats_and_concepts.md | ||
| gentoo-nix-guide.md | ||
| getting-started.md | ||
| init_systems.md | ||
| json-output.md | ||
| learning-nim.md | ||
| license_json_examples.md | ||
| license_yaml_examples.md | ||
| nexus Package Formats and Their Purposes.md | ||
| nexus_targets.md | ||
| nexusos_commercial_badge.md | ||
| nexusos_licensing.md | ||
| nexusos_overview.md | ||
| nimpak_types_reference.md | ||
| nip_verify_acul_enforcement.md | ||
| nipcell-usage.md | ||
| nipcells.md | ||
| platform-detection.md | ||
| quick-reference.md | ||
| remote-cache.md | ||
| remote-repository-specification.md | ||
| remote_cli_guide.md | ||
| roadmap.md | ||
| security-and-verification-system.md | ||
| security-features.md | ||
| security_event_logging.md | ||
| shell-guide.md | ||
| shell-interface.md | ||
| source-build-guide.md | ||
| static-build-guide.md | ||
| vision.md | ||
README.md
NIP Documentation
Welcome to the NIP documentation! This guide will help you find what you need.
New to NIP?
Start here:
- Getting Started Guide - Complete introduction with examples
- Quick Reference - Command cheat sheet
- Bootstrap Overview - Understanding automatic build tool management
User Guides
Package Management
- Getting Started - Installation and basic usage
- Source Build Guide - Building packages from source
- Arch Linux Guide - Hybrid package management on Arch
- Gentoo + Nix Guide - Using Nix packages on Gentoo
Bootstrap System
- Bootstrap Overview - What is the bootstrap system?
- Bootstrap Guide - Detailed usage and commands
- Bootstrap Detection Flow - How automatic detection works
- Container Builds - Docker/Podman integration
- Binary Cache - Local caching system
- Remote Cache - Team collaboration with remote cache
- Automatic Updates - Self-updating system
Build System
- Build Flow - Understanding the build process
- Build Configuration - Configuring builds
- Build Examples - Common build scenarios
- Build Troubleshooting - Solving build issues
Advanced Topics
- Architecture - System architecture overview
- Security Features - Security and verification
- Remote CLI Guide - Remote package management
Developer Guides
Bootstrap System
- Bootstrap API - API reference for developers
- Recipe Authoring - Creating bootstrap recipes
- Build Binaries - Building standalone binaries
Build System
- Build System Help - Build system internals
- Types Reference - Core type definitions
Package Format
- Formats and Concepts - Package formats
- Remote Repository Specification - Repository format
Reference
Command Line
- Enhanced CLI Interface - CLI design
- JSON Output - Machine-readable output
- Shell Interface - Interactive shell
Configuration
- Build Configuration - Build settings
- Schemas - See
docs/schemas/directory
Security
- Security Features - Overview
- Security and Verification - Detailed system
- Hash Algorithm Migration - Blake2b to Blake3
Quick Navigation
I want to...
Install a package → Getting Started Guide
Build from source → Source Build Guide
Understand automatic bootstrap → Bootstrap Overview
Use NIP on Arch Linux → Arch Linux Guide
Build in containers → Getting Started Guide
Manage build tools → Bootstrap Guide
Troubleshoot builds → Build Troubleshooting
Create custom recipes → Recipe Authoring Guide
Understand the API → Bootstrap API
Documentation Structure
docs/
├── README.md # This file
├── getting-started.md # Start here!
│
├── User Guides/
│ ├── bootstrap-overview.md # Bootstrap system overview
│ ├── bootstrap-guide.md # Bootstrap usage
│ ├── bootstrap-detection-flow.md # Detection logic
│ ├── source-build-guide.md # Source building
│ ├── arch-linux-guide.md # Arch Linux workflow
│ ├── build-flow.md # Build process
│ ├── build-configuration.md # Build config
│ ├── build-examples.md # Build examples
│ └── build-troubleshooting.md # Troubleshooting
│
├── Developer Guides/
│ ├── bootstrap-api.md # Bootstrap API
│ ├── architecture.md # System architecture
│ ├── build-system-help.md # Build internals
│ └── nimpak_types_reference.md # Type reference
│
├── Reference/
│ ├── enhanced-cli-interface.md # CLI reference
│ ├── json-output.md # JSON format
│ ├── security-features.md # Security
│ └── formats_and_concepts.md # Package formats
│
└── schemas/ # JSON schemas
Contributing to Documentation
Found an issue or want to improve the docs?
- Documentation lives in
nip/docs/ - Use Markdown format
- Follow existing structure and style
- Test all code examples
- Update this index when adding new docs
Getting Help
- Issues: https://git.maiwald.work/Nexus/NexusToolKit/issues
- Wiki: https://git.maiwald.work/Nexus/NexusToolKit/wiki
- Repository: https://git.maiwald.work/Nexus/NexusToolKit
Documentation Status
| Document | Status | Last Updated |
|---|---|---|
| Getting Started | ✅ Complete | 2025-11 |
| Bootstrap Overview | ✅ Complete | 2025-11 |
| Bootstrap Guide | ✅ Complete | 2025-11 |
| Bootstrap Detection Flow | ✅ Complete | 2025-11 |
| Bootstrap API | ✅ Complete | 2025-11 |
| Source Build Guide | ✅ Complete | 2025-11 |
| Arch Linux Guide | ✅ Complete | 2025-11 |
| Gentoo + Nix Guide | ✅ Complete | 2025-11 |
| Build Flow | ✅ Complete | 2025-11 |
| Container Builds | ✅ Complete | 2025-11 |
| Binary Cache | ✅ Complete | 2025-11 |
| Remote Cache | ✅ Complete | 2025-11 |
| Automatic Updates | ✅ Complete | 2025-11 |
| Recipe Authoring | ✅ Complete | 2025-11 |
| Build Binaries | ✅ Complete | 2025-11 |
Summary
The documentation is organized to help you:
- Get started quickly - Follow the getting started guide
- Learn by doing - Practical examples throughout
- Understand deeply - Detailed explanations when needed
- Reference easily - Quick lookup for specific topics
Start with Getting Started and explore from there!