---
title: README
emoji: 📚
colorFrom: purple
colorTo: blue
sdk: static
pinned: false
---

# LOCALHOST1978

> [!IMPORTANT]
> **Version Control Rule**: This repository uses `lore` for version control, state tracking, and documentation. **Do not use `git`**.

---

## 1. Overview

SovereignSurvivalKit is a modular application platform for macOS and iOS. The platform provides:

- **Encrypted Local Storage**: Hardware-backed AES-GCM 256-bit encryption and encrypted `.sparsebundle` volumes managed with Apple CryptoKit and the Apple Secure Enclave.
- **On-Device Machine Learning and Audio Telemetry**: Apple Silicon neural audio separation (HTDemucs via MLX Swift), real-time $\tau$-dynamics, and 12-bin FFT chromagram analysis.
- **Zero-Knowledge Identity and Settlement**: Privacy-preserving authentication, post-quantum ML-DSA signatures, and peer-to-peer asset settlement.
- **Encrypted Mesh Networking**: WireGuard and UDP/QUIC peer-to-peer communication across an isolated `10.0.0.0/24` subnet.
- **Model Context Protocol (MCP) and Tooling**: Local ACP agent service (`SSK_StorageHost acp-agent`), Xcode developer plug-in (`XCPSSKPlugin`), and automated documentation ledger generation (`SSK_DocGen`).

---

## 2. Repository Structure

```text
SovereignSurvivalKit/
├── README.md                # Master repository documentation (this file)
├── ARCHITECTURE.md          # System architecture, module boundaries, and dependency graph
├── src/                     # Application source code, packages, and standalone tools
│   └── SovereignSurvivalKit/
│       ├── README.md        # Source root documentation and target hierarchy
│       ├── Modules/         # 10 modular Swift packages (SSK_Foundation, SSK_UI, etc.)
│       ├── SovereignSurvivalKit/       # Main macOS and iOS application target
│       ├── SSKVaultHost/               # Background daemon and lifecycle service
│       ├── SSK_DocGen/                 # Documentation ledger generator CLI
│       ├── XCPSSKPlugin/               # Xcode developer plug-in
│       ├── ClipLiveActivities/         # WidgetKit Live Activity target
│       ├── SovereignSurvivalKitIntents/ # App Intents target
│       ├── SovereignSurvivalKitMeshClip/# App Clip target
│       └── SovereignSurvivalKitMessenger/# iMessage extension target
├── scripts/                 # Build, package, and installation orchestrators
│   ├── install.sh           # Master build and installation orchestrator
│   ├── build_dmg.sh         # macOS desktop build and archive pipeline
│   ├── build_pkg.sh         # Component and product package (.pkg) builder
│   ├── install_dist.sh      # Direct filesystem distribution installer
│   └── package_dmg.sh       # Compressed disk image (.dmg) packager
├── dist/                    # Build artifacts, packages, and DMGs
├── guide/                   # Architectural guides and technical specifications
├── next/                    # Active development plans and validation roadmaps
│   └── dev/                 # Development plans and phase status matrices
└── archive/                 # Historical reference code and narrative documents
```

---

## 3. Quick Start: Build and Installation

Use the master orchestrator script [`scripts/install.sh`](file:///Users/voxels/SovereignSurvivalKit/scripts/install.sh) to build, package, install, or reset the software.

### Standard Clean Build and Installation
Execute a clean build of all macOS schemes and install products to system directories:

```bash
./scripts/install.sh --clean
```

### Common Command Options

| Goal | Command |
| :--- | :--- |
| **Build without installing** | `./scripts/install.sh --build-only --clean` |
| **Install existing `dist/` products** | `./scripts/install.sh --install-only` |
| **Install via signed macOS package (`.pkg`)** | `./scripts/install.sh --via-pkg` |
| **Uninstall all applications and tools** | `./scripts/install.sh --uninstall` |
| **Reset data, caches, and databases** | `./scripts/install.sh --clean --reset-data` |
| **Simulate commands without changes** | `./scripts/install.sh --dry-run` |

### Specialized Build Scripts

For CI/CD pipelines or isolated steps, run the specialized scripts directly:

- **Clean build and archive**: [`./scripts/build_dmg.sh --clean-dist --refresh-packages`](file:///Users/voxels/SovereignSurvivalKit/scripts/build_dmg.sh)
- **Direct system install**: [`./scripts/install_dist.sh`](file:///Users/voxels/SovereignSurvivalKit/scripts/install_dist.sh)
- **Generate installer `.pkg`**: [`./scripts/build_pkg.sh dist/Export/Products`](file:///Users/voxels/SovereignSurvivalKit/scripts/build_pkg.sh)
- **Package `.dmg`**: [`./scripts/package_dmg.sh dist/Export/Products`](file:///Users/voxels/SovereignSurvivalKit/scripts/package_dmg.sh)

---

## 4. Installed System Locations

The installation scripts deploy components to standard system paths:

| Component | Direct Install Path (`install_dist.sh`) | Package Install Path (`build_pkg.sh`) |
| :--- | :--- | :--- |
| **Desktop Application** | `/Applications/SovereignSurvivalKit.app` | `/Applications/SovereignSurvivalKit.app` |
| **Daemon Application** | `/Applications/SSKVaultHost.app` | `/Applications/SSKVaultHost.app` |
| **Command Line Tools** | `/usr/local/bin/SSK_StorageHost`<br>`/usr/local/bin/SSK_DocGen`<br>`/usr/local/bin/SSKVaultHost` | `/usr/local/bin/SSK_StorageHost`<br>`/usr/local/bin/SSK_DocGen`<br>`/usr/local/bin/SSKVaultHost` |
| **Shell Path Config** | `/etc/paths.d/SovereignSurvivalKit` | `/etc/paths.d/SovereignSurvivalKit` |
| **Xcode Plug-in** | `~/Library/Developer/Xcode/Plug-ins/XCPSSKPlugin.xcplugin` | `/Library/Application Support/Developer/Shared/Xcode/Plug-ins/XCPSSKPlugin.xcplugin` |

---

## 5. System Operations and Tooling

### 1. Launch the Desktop Application
Start the main application from Launchpad, Finder, or Terminal:

```bash
open /Applications/SovereignSurvivalKit.app
```

### 2. Run Command-Line Tools
Verify the command-line interfaces:

```bash
SSK_StorageHost --help
SSK_DocGen --help
SSKVaultHost --help
```

### 3. Connect Xcode Coding Intelligence to MCP
Configure Xcode to use the local ACP agent:
- **Executable**: `/usr/local/bin/SSK_StorageHost`
- **Arguments**: `acp-agent`

---

## 6. Documentation and Architectural References

- [ARCHITECTURE.md](file:///Users/voxels/SovereignSurvivalKit/ARCHITECTURE.md): Comprehensive module breakdown, dependencies, and subsystem diagrams.
- [Source Root README](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/README.md): Detailed guide to Swift packages, Xcode schemes, and target relationships.
- [SSK_DocGen README](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SSK_DocGen/README.md): Documentation worker protocol, security boundaries, and manual verification procedures.
- [DocGen Phase Roadmap](file:///Users/voxels/SovereignSurvivalKit/next/dev/SSK_DOCGEN_PHASE_ROADMAP.md): Priority specifications and lifecycle status for documentation services.
- [DocC Master Index](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/data/docs/SSK_Ledger_Vault/DocC_Index.md): Auto-generated symbol documentation.

---

## 7. Version Control with Lore

This project uses `lore`. Follow these standard commands for state tracking:

```bash
# Check modified files
lore status --scan

# Inspect local changes
lore diff

# Stage modified paths
lore stage --scan <paths>

# Create a commit
lore commit "Description of change"
```