README.md

LOCALHOST:1978

https://huggingface.co/buckets/localhost1978/localhost

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.
• TESTING.md: Guide for unit tests, integration tests, and UI tests.
• 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"