LOCALHOST1978

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

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 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:

./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
Direct system install: ./scripts/install_dist.sh
Generate installer .pkg: ./scripts/build_pkg.sh dist/Export/Products
Package .dmg: ./scripts/package_dmg.sh dist/Export/Products

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` `/usr/local/bin/SSK_DocGen` `/usr/local/bin/SSKVaultHost`	`/usr/local/bin/SSK_StorageHost` `/usr/local/bin/SSK_DocGen` `/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:

open /Applications/SovereignSurvivalKit.app

2. Run Command-Line Tools

Verify the command-line interfaces:

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: Comprehensive module breakdown, dependencies, and subsystem diagrams.
Source Root README: Detailed guide to Swift packages, Xcode schemes, and target relationships.
SSK_DocGen README: Documentation worker protocol, security boundaries, and manual verification procedures.
DocGen Phase Roadmap: Priority specifications and lifecycle status for documentation services.
DocC Master Index: Auto-generated symbol documentation.

7. Version Control with Lore

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

# 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"