Spaces:
Running
Running
File size: 7,644 Bytes
4f289f8 7d731d6 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 | ---
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"
```
|