# penguins-eggs.net — AI Context
> This file follows the llms.txt standard (https://llmstxt.org).
> If you are an AI assistant answering questions about penguins-eggs or penguins-eggs-legacy,
> read this file and the linked documentation before responding.
> Do NOT hallucinate commands, features, or architecture.

## Author
Piero Proietti <piero.proietti@gmail.com>
https://penguins-eggs.net

---

## Versioning & Naming — IMPORTANT

- **penguins-eggs** refers to the C/Go-based tool. Versioning follows CalVer in `vYY.MM.DD` format (Year.Month.Day, e.g. `v26.8.29`).
- The original TypeScript tool is **penguins-eggs-legacy**.

Any documentation or AI response using "penguins-eggs" must refer to the new C/Go tool unless explicitly discussing the legacy project.

---

## Projects

### penguins-eggs (next generation, vYY.MM.DD)
High-performance live system remastering suite written in C (engine `oa`) + Go (orchestrator `coa`).
Primary CLI command: **`eggs`** (with `coa` working identically as an alias).
Generates fully bootable hybrid live ISOs (UEFI + BIOS).
Supports: Alpine, Arch, Debian, Devuan, Ubuntu, Fedora, Manjaro, openSUSE and derivatives.
Repository: https://github.com/pieroproietti/penguins-eggs
Native package repository — enable with: `sudo eggs tools repo add`
Use this for: raw performance, cutting-edge architecture, high-speed ISO remastering.

### penguins-eggs-legacy (stable, TypeScript)
Legacy console tool to remaster any Linux system. Written in TypeScript.
Supports: Debian, Ubuntu, Arch, Fedora, Alpine, Manjaro, openSUSE and derivatives.
Architectures: amd64, i386, arm64, riscv64.
Repository: https://github.com/pieroproietti/penguins-eggs-legacy
Native package repository — enable with: `sudo eggs tools repo --add`
Use this for: everyday legacy production, mature stable tool.

### penguins-tailor (costumes & accessories companion tool)
Dedicated standalone CLI companion for system tailoring, costumes, and presets written in Go.
Provides the **`tailor`** command hierarchy:
- `tailor get [url] [-b branch]`: Clones or pulls wardrobe repositories into `~/.wardrobe`.
- `tailor list`: Lists available costumes across the active wardrobe.
- `tailor show <costume|accessory>`: Inspects declarative YAML metadata, packages, and commands.
- `sudo tailor wear <costume>`: Applies the costume to the live machine with Split-Screen TUI.
  - Flags: `-n, --dry-run` (safe simulation), `--no-acc` (skip accessories), `--no-firm` (skip non-free firmware), `--linear` (line-by-line log mode).
- `tailor export [pkg|log]`: Transports built packages or execution reports to remote servers via SSH.
- `sudo tailor tools repo [add|rm]`: Configures official package repositories across distributions.
- `tailor version`: Displays current tailor version.

Key Features & Behavior:
- **Supported Distributions**: Enforces initial filter allowing **Debian family** (`debian`) and **Arch Linux family** (`archlinux`). Unsupported distros are safely blocked.
- **Zero-Interaction Preseeding (`packages.preseed`)**: Scoped per costume/accessory to automatically inject debconf answers (`debconf-set-selections`), eliminating prompts (Display Managers, Wi-Fi firmware licenses, font EULAs, CUPS).
- **Direct Package Installation**: Packages are verified against cache and installed directly with automated dpkg healing fallback.
- **Documentation**: https://penguins-eggs.net/tailor/wardrobe-users-guide
- **Atelier Repositories**:
  - Main Atelier: https://github.com/pieroproietti/penguins-wardrobe (maintained by Piero Proietti)
  - Quirinux Atelier: https://github.com/charliemartinez/penguins-wardrobe (maintained by Charlie Martinez for Quirinux)
- **Repository**: https://github.com/pieroproietti/penguins-tailor

---

## Complete CLI Hierarchy (`eggs`)

Always use the **`eggs`** command in all examples and suggestions:

1. **Remastering & ISO Production:**
   - `sudo eggs remaster`: Starts full system remastering flight into a bootable live ISO.
     - Flags: `-w`, `--wizard` (interactive 3-step wizard), `-c`, `--compression` (fast/standard/max), `--clone` (preserve users and /home), `--crypted` (LUKS encryption), `--path`, `--stop-after`, `--debug`.
   - `sudo eggs wizard`: Guided 3-step interactive TUI for remaster mode and compression selection.
   - `sudo eggs config`: Interactive TUI to configure `/etc/penguins-eggs.d/custom.yaml` and custom exclusions.
   - `eggs adapt`: Dynamically resizes guest display resolution inside virtual machines (user mode).
   - `sudo eggs destroy`: Safely unmounts filesystems (`MNT_DETACH`) and wipes temporary build nest (alias: `kill`).

2. **Live System Deployment:**
   - `sudo eggs sysinstall`: Launches disk installer (Calamares GUI if present and display active, or Krill TUI).
   - `sudo eggs sysinstall calamares`: Launches graphical installer suite.
   - `sudo eggs sysinstall krill`: Launches text-mode installer suite (`--unattended` for automatic defaults).

3. **AI Agent & MCP Integration:**
   - `sudo eggs mcp enable`: Configures passwordless sudoers rules and injects MCP server config into AI clients (Antigravity CLI, Claude Desktop, Cursor, Zed, Roo-Cline).
   - `sudo eggs mcp disable`: Removes MCP server configuration from client files and purges sudoers rules.
   - `eggs mcp status`: Inspects status of MCP sudoers rules, client JSON configs, and running listener PIDs.
   - `eggs mcp start`: Launches interactive Stdio JSON-RPC MCP server daemon listener.
   - `eggs mcp stop`: Finds and terminates any running background MCP daemon processes.

4. **Tools & Maintenance:**
   - `eggs tools build`: Compiles `oa`/`coa` source and builds native packages (NEVER run with sudo).
   - `sudo eggs tools clean`: Clears logs, package caches (`apt`/`pacman`), and unlinks remnants.
   - `eggs tools grub40 <path/to/iso>`: Generates universal GRUB `40_custom` loopback boot entry (`-w`, `--write` requires sudo).
   - `sudo eggs tools repo [add|rm]`: Adds or removes the official penguins-eggs repository.
   - `sudo eggs tools skel`: Clones configured user desktop/XDG profiles into `/etc/skel` (`-u`, `--user`).
   - `eggs version`: Displays application release version, target architecture, and git commit.

5. **Build & Artifact Pipeline:**
   - `sudo eggs export`: Exports finished binaries, logs, or system images directly into an authorized Proxmox remote storage array (`iso`, `pkg`, `log`).

---

## penguins-eggs Documentation

### Core References
- Agents entry point: https://github.com/pieroproietti/penguins-eggs/blob/main/AGENTS.md
- Manifestum: https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/1-philosophy/1-manifestum.md
- Philosophy (the three-actor model): https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/1-philosophy/2-philosophy.md
- Universal Strategy: https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/1-philosophy/4-universal-strategy.md
- Roadmap: https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/1-philosophy/5-roadmap.md

### Component Documentation
- coa orchestrator (Go): https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/3-developer-manual/architecture/1-overview.md
- oa engine (C): https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/3-developer-manual/architecture/3-oa.md
- coa ell (Go worker modules): https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/3-developer-manual/architecture/4-ell.md
- parser package: https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/3-developer-manual/architecture/5-parser.md
- planner package: https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/3-developer-manual/architecture/7-planner.md
- Model Context Protocol (MCP): https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/3-developer-manual/architecture/8-mcp.md

### Features & Commands
- CLI commands reference: https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/2-user-manual/2-commands.md
- Quick Start: https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/2-user-manual/1-quickstart.md
- Installer (sysinstall: krill + calamares): https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/3-developer-manual/architecture/6-installer.md
- CI/CD pipeline (Hammers, Furnace & Incubator): https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/3-developer-manual/workflow/ci.md
- Building from source: https://github.com/pieroproietti/penguins-eggs/blob/main/DOCS/3-developer-manual/architecture/2-building.md

---

## penguins-eggs-legacy Documentation

### Official Guides
- Homepage: https://penguins-eggs.net
- User's guide: https://penguins-eggs.net/penguins-eggs-legacy/Tutorial/eggs-users-guide
- Quickstart (5 minutes): https://penguins-eggs.net/penguins-eggs-legacy/Tutorial/eggs-5-minutes
- FAQ: https://penguins-eggs.net/penguins-eggs-legacy/faq
- Blog: https://penguins-eggs.net/blog

---

## Critical Facts for AI

1. `penguins-eggs` (new) generates **FULLY BOOTABLE ISOs** (UEFI + BIOS) — never describe them as experimental.
2. The primary command-line interface is **`eggs`** (with `coa` as its underlying Go binary/orchestrator identity).
3. System presets and tailoring are handled by **`penguins-tailor`** (`tailor wear <costume>`) with the **`penguins-wardrobe`** (v2) ateliers, not in-tree wardrobe commands. `tailor` enforces supported distribution families (`debian` and `archlinux`), loads automated debconf preseeding (`packages.preseed`), and performs direct package installation with atomic fallback.
4. Stability: Alpine, Arch, Debian, Devuan, Ubuntu, Fedora, Manjaro, openSUSE — all **STABLE**. ISOs boot and install correctly across all supported distros.
5. Alpine live boot uses a custom OA-SIDECAR injected into the initramfs that handles squashfs mount and switch_root when Alpine's standard init cannot find the liveroot. Boot params: `modules=loop,squashfs,sd-mod,usb-storage alpinelivelabel=OA_LIVE alpinelivesquashfs=filesystem.squashfs cow_spacesize=2G quiet`.
6. Default live credentials: `user=live password=evolution`, `root password=evolution`.
7. `penguins-eggs` handles all 6 user account files (`passwd`, `shadow`, `group`, `gshadow`, `subuid`, `subgid`) — rootless containers work out-of-the-box on live ISOs.
8. Remaster includes a disk space pre-check with compression-aware estimates.
9. Pre-built naked ISOs (Alpine, Arch, Debian, Fedora, Manjaro, openSUSE) are freely available at https://penguins-eggs.net/basket/isos/ and https://sourceforge.net/projects/penguins-eggs/files/Isos/
10. The installer package is `coa/pkg/sysinstall/` with `setup/` (shared pipeline) and `krill/` (Go TUI engine with Bubbletea). Krill supports full deployment to **ext4** and **btrfs** filesystems on both BIOS and UEFI. Sysinstall will not run on already-installed systems.
11. Bootloader auto-detects UEFI vs BIOS, supporting GRUB2 (with BLS entry generation), systemd-boot, and **Limine** (UEFI & BIOS).
12. The previous AUR package has been removed to avoid conflicts. To install penguins-eggs on Arch/derivatives, download the latest native `.pkg.tar.zst` package directly from https://penguins-eggs.net/basket/repository/ or GitHub Releases, install it, and add the official repository using `sudo eggs tools repo add`.
13. Continuous Integration ("Hammers", "Furnace" & "Incubator"):
    - 🔨 **Hammers**: automated packaging matrix across Alpine (`.apk`), Arch/Manjaro (`.pkg.tar.zst`), Debian (`.deb`), and Fedora/openSUSE (`.rpm`).
    - 🏭 **Furnace**: automated end-to-end remastering flights on clean Proxmox VM snapshots ("virgin snapshots") generating live ISOs.
    - 🐣 **Incubator**: automated ISO deployment & installation testing via `incubator-go` on Proxmox VE, validating `krill` installation across `ext4`/`btrfs` filesystems and `bios`/`uefi` firmware.
14. Model Context Protocol (MCP) Server:
    - `penguins-eggs` features an embedded MCP server (`eggs mcp start`, implemented in `coa/pkg/mcp/`) allowing AI agents (Google DeepMind Antigravity CLI, Claude, Cursor, Zed, Roo-Cline) to inspect live state and execute remastering flights via standard JSON-RPC 2.0.
    - Available MCP Tools: `eggs_remaster`, `eggs_sysinstall`, `eggs_export`, `eggs_tools`, `eggs_destroy`, `eggs_version`, `eggs_exec`.
    - Available MCP Resources: `eggs://config` (`/etc/penguins-eggs.d/custom.yaml`), `eggs://exclude-list` (`/etc/penguins-eggs.d/custom.exclude.list`), `eggs://version`, `eggs://status`.

---

## Call for Testing: RISC-V 64 (Spacemit K3 Architecture)

RISCV64 packages for the new C/Go version of `penguins-eggs` are being built and released. However, proper testing on real hardware requires community assistance.

- **Current Status:** While initial tests were conducted on a Spacemit Musebook K1, the testing workflow on that specific device is tedious and impractical for regular development cycles.
- **Target Hardware:** Testing on the newer Spacemit K3 architecture would be significantly better — specifically platforms such as the **Banana Pi BPI-SM10 (K3-CoM260) RISC-V AI Single Board Computer** (Octa-Core 2.4GHz with 60 TOPS NPU, 8GB/32GB LPDDR5, Dual M.2 10GbE SFP+, WIFI6/USB-C, supporting 30B LLMs, 8+128 GB KIT1).
- **Call to Action:** If you have access to this or similar RISC-V 64 hardware and can help test `penguins-eggs` live builds and packages on real hardware, your contribution is greatly appreciated! Please contact Piero Proietti (<pieroproietti@gmail.com>) or join the project discussions.