docs: add quick start guide for project setup and build

Add QUICK_START.md with current status, quick commands for checking build status, restarting build, and cleanup procedures for rapid project resumption and execution.

💘 Generated with Crush

Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
2026-01-29 10:01:10 -05:00
parent 54c88c401d
commit 249af2b843

114
QUICK_START.md Normal file
View File

@@ -0,0 +1,114 @@
# KNEL-Football Project - Quick Start
## Current Status (2026-01-24 19:00 CST)
### ISO Build Running in Background
- **Status**: Active build (3rd attempt, minimal config)
- **Started**: 18:04 CST
- **Expected Completion**: 19:00-19:15 CST
- **Log**: `/tmp/knel-iso-build.log`
### First Actions When Returning
1. **Check if ISO is ready**:
```bash
cd /home/tsys/Projects/KNEL/football
ls -lh output/
```
Expected: `knel-football-secure-v1.0.0.iso` (~1-2GB)
2. **If ISO is ready**, verify it:
```bash
cd output/
sha256sum -c knel-football-secure-v1.0.0.iso.sha256
```
3. **If ISO is NOT ready**, check build progress:
```bash
tail -50 /tmp/knel-iso-build.log | grep "P:"
```
## Quick Commands
### Check Build Status
```bash
cd /home/tsys/Projects/KNEL/football
ls -lh output/ # Check for ISO
tail -f /tmp/knel-iso-build.log # Monitor build
```
### Restart Build (if failed)
```bash
# See full command in RESUME.md
# Current working config documented there
```
### Clean Up
```bash
./run.sh clean # Remove artifacts
./run.sh lint # Check scripts
./run.sh test # Run tests
```
## Key Files
| File | Purpose |
|------|---------|
| `RESUME.md` | Complete resumption guide (START HERE) |
| `JOURNAL.md` | Development journal (append-only) |
| `AGENTS.md` | Docker-only workflow requirements |
| `run.sh` | Main entry point (build/test/lint/iso/clean) |
| `Dockerfile` | Build environment |
| `config/` | Live-build configuration |
| `output/` | Final ISO artifacts (when complete) |
## Build Configuration (Working Version)
### Required Flags
- `--privileged` - Mount operations
- `--user root` - Live-build requirement
- Build in `/tmp` - Not mounted volume
- USER_UID/USER_GID - Ownership preservation
### Removed Flags (Causing Issues)
- `--linux-packages` - Duplicate package names
- `--memtest` - Missing file
- `--win32-loader` - Package not available
## Expected Output
### When Build Completes
```
output/
├── knel-football-secure-v1.0.0.iso (~1-2GB)
├── knel-football-secure-v1.0.0.iso.sha256 (checksum)
└── knel-football-secure-v1.0.0.iso.md5 (checksum)
```
### All Files Owned By You
- User: tsys (UID 1000)
- Group: tsys (GID 1000)
- NOT root
## Next Steps After Build Completes
1. Verify ISO and checksums
2. Test ISO boot with libvirt/virsh
3. Validate security features:
- WiFi/Bluetooth disabled
- SSH configuration
- Firewall rules
- USB automount
- WireGuard QR code import
## Session Summary
- **Work Time**: 8 hours (11:00-19:00 CST)
- **ISO Build Attempts**: 7
- **Final Strategy**: Minimal configuration (working)
- **Status**: Build running, expected completion in ~15 minutes
- **Documentation**: Complete (RESUME.md, JOURNAL.md)
**Safe to close session.** All work documented. Check `output/` when returning.
---