# SamiOS Developer Guide

## Getting Started

### Prerequisites
- Arch Linux (or WSL Arch) with `base-devel`, `git`, `archiso`
- Gitea account on `git.sami`

### Clone
```bash
git clone https://git.sami/sami7777/samios.git
cd samios
```

### Project Structure
```
samios/
├── branding/               # Visual identity assets
│   ├── icons/              # Square + launcher icons (PNG + SVG)
│   ├── logos/              # Full lockups (face + pyramid)
│   ├── wallpapers/         # Desktop wallpapers
│   ├── themes/             # SDDM theme
│   ├── grub-theme/         # GRUB boot theme
│   └── README.md           # Brand guidelines
├── docs/                   # Documentation
│   ├── installation.md     # User install guide
│   ├── roadmap.md          # Development roadmap
│   ├── voice-integration-architecture.md
│   └── voice-hermes-pipeline.md
├── packaging/
│   ├── archiso/            # ISO build profile
│   │   ├── airootfs/       # Root filesystem overlay
│   │   ├── packages.x86_64 # Package list
│   │   ├── profiledef.sh   # ISO profile
│   │   └── build.sh        # Build script
│   ├── packages/           # Custom PKGBUILDs
│   │   └── samios-branding/
│   └── scripts/            # Setup and installer scripts
│       ├── samios-installer.sh
│       ├── samios-desktop-setup.sh
│       └── kdeglobals-samios
├── tests/                  # Test suite
│   ├── run_tests.sh
│   ├── test_profiledef.sh
│   ├── test_packages.sh
│   └── ...
├── Makefile                # Build/test/lint targets
└── .gitea/workflows/       # CI pipeline
```

## Development Commands

```bash
make test      # Run test suite
make lint      # Shellcheck on all scripts
make check     # Full CI (lint + test)
make build     # Build ISO (requires archiso)
make clean     # Clean build artifacts
```

## Building the ISO

```bash
# Install archiso
sudo pacman -S archiso

# Build
cd packaging/archiso
sudo ./build.sh

# Output
ls out/samios-*.iso
```

## Font Policy

- **Default UI font:** Sami Grotesk (Helvetica-like sans-serif)
- **Secondary font:** Sami Sans
- **Excluded:** Any fonts with "7777" in the filename (personal branding)
- Font config: `packaging/archiso/airootfs/etc/fonts/conf.d/10-samios-fonts.conf`

## Adding Packages

Edit `packaging/archiso/packages.x86_64` and add the package name. Test with:
```bash
make check
```

## Modifying Branding

1. Place new assets in `branding/` (follow existing structure)
2. Update `branding/README.md` with new entries
3. If changing icons, generate all sizes from the SVG source
4. Test the ISO build

## Voice Integration

See `docs/voice-hermes-pipeline.md` for the SamiType voice command architecture.

## CI/CD

Gitea Actions workflow at `.gitea/workflows/ci.yml` runs on every push:
- Shellcheck on all `.sh` files
- Profile structure validation
- Test suite execution

## Release Process

1. Update version in `profiledef.sh`, `samios` CLI, and `README.md`
2. Update `docs/roadmap.md` with completed items
3. Commit: `git commit -m "vX.Y.Z: Description"`
4. Tag: `git tag vX.Y.Z`
5. Push: `git push origin master --tags`