feat: initial commit - founding documents

.gitignore

@@ -0,0 +1,32 @@
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Build output directories
+/build/
+/out/
+/dist/
+*.iso
+*.img
+*.tar.gz
+
+# Keys and secrets
+*.key
+*.pem
+*.crt
+id_rsa
+id_ed25519
+.env
+.env.local
+.env.*.local
+
+# Temporary files
+*.tmp
+*.bak
+*.swp
+*~

README.md

@@ -0,0 +1,11 @@
+# Sawa Server (SS)
+
+## Overview
+Sawa Server (CodeName: SS) is an Alpine Linux-based USB server node project. The primary deliverable is a customized, bootable USB stick that instantly provisions a machine as a Sawa network node. 
+
+**Note: This is NOT a web application.** It is an infrastructure project focused on system-level configuration, network provisioning, and hardware abstraction using the lightweight and secure Alpine Linux environment.
+
+## Vision
+The vision for Sawa Server is to create a zero-touch, highly resilient, disposable infrastructure layer. By booting entirely from a USB drive (and eventually running diskless in RAM), nodes can be deployed instantly, wiped cleanly without leaving traces on the host machine, and replaced seamlessly in the Sawa mesh network.
+
+MVP Success Criteria: Insert USB into any x86_64 machine, power on, complete ss-init wizard in under 10 minutes, node is online and visible to the Sawa network.

docs/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to the Sawa Server (SS) project will be documented in this file.
+
+## [v0.1.0] - Current State
+### Added
+- Initial project scaffolding and core founding documents.
+- Defined project vision, roadmap phases, and AI guidelines.
+- Established Git repository structure and contribution conventions.

docs/CLAUDE.md

@@ -0,0 +1,15 @@
+# AI Agent Instructions for Sawa Server (SS)
+
+You are assisting with the **sawa-server** project.
+
+## Project Context
+- **Name:** sawa-server
+- **Codename:** SS
+- **Nature of the project:** Alpine Linux USB server node project. This is **NOT** a web app. The end product is a bootable USB stick.
+
+## Guidelines
+1. **System-Level Focus:** Focus on shell scripting, Alpine Linux package management (`apk`), system services (`OpenRC`), minimal disk partitioning, and network configurations. 
+2. **Minimalism:** Alpine Linux is strictly minimal. Always prefer lightweight native tools (e.g., `busybox`, `ash` instead of `bash`).
+3. **No Web Frameworks:** Do not suggest Node.js, React, or any web frameworks unless explicitly requested for a localized control interface.
+4. **Resiliency & State:** The system will transition to running diskless in RAM. Data persistence requires specific Alpine tools like Alpine Local Backup (`lbu`). Commands must respect this ephemeral environment.
+5. **Project Structure:** *Never* use the project root folder for new files unless absolutely necessary. Place all documentation (except `README.md`) in the `docs/` folder and organize source code into appropriate subdirectories. `README.md` must stay in the project root for git forge display.

docs/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing to Sawa Server
+
+Thanks for contributing to Sawa Server (SS)!
+
+## Commit Conventions
+We follow the same commit conventions as the `sawa-control-panel` project. Please ensure your commits adhere to these rules:
+
+- **feat:** A new feature (e.g., `feat: add ss-init script for first boot`)
+- **fix:** A bug fix (e.g., `fix: resolve issue with lbu commit on unmounted drive`)
+- **docs:** Documentation only changes
+- **style:** Changes that do not affect the meaning of the code (formatting, missing spaces, etc.)
+- **refactor:** A code change that neither fixes a bug nor adds a feature
+- **perf:** A code change that improves performance
+- **test:** Adding missing tests or correcting existing tests
+- **chore:** Changes to the build process or auxiliary tools and scripts
+
+Please write your commit messages in the imperative mood (e.g., "Add feature" instead of "Added feature").
+
+## General Guidelines
+- Keep scripts POSIX-compliant or standard `ash` compatible, given our Alpine Linux environment.
+- Test changes on actual bootable media or a compatible VM before submitting.

docs/ISSUES.md

@@ -0,0 +1,9 @@
+# Open Issues
+
+## Phase 1 & 2 Blockers
+- **[ISSUE-1] Base Image Selection:** Determine exactly which Alpine Linux flavor (Standard vs. Extended) provides the best balance of required packages and size for our base image.
+- **[ISSUE-2] Core Package List:** Define the minimal set of `apk` packages that must be injected into the base build before Phase 2.
+- **[ISSUE-3] `ss-init` Prompt Design:** Outline the exact parameters the first boot wizard needs to ask the user (e.g., hostname, static IP vs DHCP, mesh participation rules).
+
+## General
+- **[ISSUE-4] Hardware Compatibility:** Document any known USB boot issues, UEFI/BIOS quirks, or secure boot obstacles on target hardware architectures.

docs/ROADMAP.md

@@ -0,0 +1,26 @@
+# Sawa Server (SS) Roadmap
+
+## Phase 1: Base Alpine USB Build
+- Prepare base Alpine Linux USB boot medium.
+- Establish `sys` mode installation (current state).
+- Document current baseline configuration and manual build steps.
+
+## Phase 2: First Boot Wizard
+- Develop the `ss-init` interactive initialization script.
+- Automate initial network configuration, key generation, and identity setup.
+- Provide a seamless onboarding experience upon first boot.
+- ss-init completion time target: under 10 minutes from power-on to node online.
+
+## Phase 3: Diskless/RAM Mode
+- Transition from `sys` mode to a diskless setup running entirely in RAM.
+- Implement Alpine Local Backup (`lbu`) for intentional state persistence across reboots.
+- Optimize image size and boot speed for rapid node deployment.
+
+## Phase 4: Node Cloning and Imaging Tools
+- Create scripts and tools to rapidly clone the configured USB stick.
+- Automate the flashing process for mass deployment of replica nodes.
+
+## Phase 5: Multi-node Discovery and Mesh
+- Implement network discovery protocols for peer-to-peer awareness.
+- Configure automatic mesh networking between multiple SS nodes on the same network.
+- Establish secure inter-node communication and load distribution.