✨ feat: add documentation for system lifecycle and distribution

- Introduce two new markdown files detailing the distribution strategy and system lifecycle of VibeAuracle.
- The new docs cover CI/CD pipeline, cross-compilation, metadata injection, and the philosophy behind a seamless user experience.

Author: nathfavour

docs/docs/lifecycle/distribution.md

@@ -0,0 +1,31 @@
+# Distribution & Integrity
+
+VibeAuracle uses a highly portable distribution strategy centered around a single, statically-linked Go binary.
+
+## CI/CD Pipeline
+
+We use GitHub Actions (`release.yml`) to manage a complex matrix of builds. On every tag (`v*`) or push to the `release` branch, the following occurs:
+
+1.  **Cross-Compilation:** We build for 7+ targets:
+    *   `linux/amd64`, `linux/arm64`
+    *   `darwin/amd64`, `darwin/arm64` (macOS)
+    *   `windows/amd64`, `windows/arm64`
+    *   `android/arm64` (Native Termux support)
+2.  **Metadata Injection:** Version strings, Git commits, and build timestamps are baked into the binary using `-ldflags`.
+3.  **Checksum Generation:** A `checksums.txt` file is generated containing SHA-256 hashes of every artifact.
+4.  **Rolling Releases:** The `release` branch always maintains a `latest` rolling tag, allowing users to track the "Stable-Edge" without waiting for semantic version increments.
+
+## Strict Integrity Policy
+
+Security is a primary concern for a tool with system-level access. VibeAuracle enforces a **Strict Integrity Policy**:
+
+*   **Mandatory Verification:** During any binary update, the tool *must* successfully download and parse the remote `checksums.txt`. 
+*   **Fail-Hard:** If the checksum file is missing, or if the downloaded binary's hash does not match, the update process is aborted immediately. 
+*   **Audit Trail:** Every integrity check (success or failure) is logged to the lifecycle audit database.
+
+## Discovery Mechanism
+
+The tool uses a multi-layered discovery process to check for updates:
+1.  **Git Discovery:** Uses `git ls-remote` to bypass GitHub API rate limits and get the latest commit hashes directly from the repository.
+2.  **API Fallback:** If Git is unavailable, it falls back to the GitHub Releases API.
+3.  **Metadata Comparison:** It compares the embedded `Commit` hash of the running binary against the remote target to determine if an update is truly necessary, even if versions appear the same.

docs/docs/lifecycle/index.md

@@ -0,0 +1,30 @@
+# System Lifecycle & Distribution
+
+VibeAuracle is designed with a **"System-Intimate"** philosophy. This extends beyond its runtime behavior to how it is delivered, maintained, and eventually removed from a host system. 
+
+This section provides a deep dive into the engineering behind VibeAuracle's distribution pipeline—covering the "why" and "how" of our autonomous update, installation, and self-healing mechanisms.
+
+## Philosophy
+
+Most CLI tools are static binaries managed by external package managers. VibeAuracle, however, treats itself as a **living process**. Our lifecycle goals are:
+
+1.  **Zero-Friction Updates:** The tool should evolve without requiring manual intervention or losing state.
+2.  **Universal Portability:** Seamless operation across Linux, macOS, Windows, and Android (Termux) without platform-specific installers.
+3.  **Strict Integrity:** Automated verification of every byte downloaded to the system.
+4.  **Self-Healing:** The ability to detect corruption or build failures and automatically recover to a stable state.
+5.  **Observability:** Every lifecycle event is audited and logged for long-term intelligence.
+
+## Pipeline Overview
+
+The lifecycle is divided into four main pillars:
+
+*   [**Distribution & CI/CD**](./distribution.md): How we build and verify binaries across architectures.
+*   [**Installation & Migration**](./installation.md): How the tool integrates with the host system and shell.
+*   [**Updates & Hot-Swapping**](./updates.md): Our multi-track update system and state-preserving restarts.
+*   [**Audit & Debugging**](./audit.md): How we track system health and lifecycle events.
+*   [**Uninstallation & Rollback**](./removal.md): Clean removal and version jumping.
+
+---
+
+### For AI Agents
+If you are an AI agent managing this system, you can find structured audit logs at `~/.vibeauracle/audit/lifecycle.jsonl`. These logs provide a machine-readable history of every update and installation event.