docs: README with build, CLI modes, data locations
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Showing 1 changed file with +61 and −0
added
README.md
+61 −0
@@ -0,0 +1,61 @@ | ||
| 1 | +# Zyquo Agent | |
| 2 | + | |
| 3 | +**Zyquo Agent** is the autonomous-agent member of the Zyquo family — a native macOS app | |
| 4 | +(Swift + SwiftUI, built with the Swift Package Manager, no Xcode IDE) that turns the same | |
| 5 | +cloud models as **Zyquo Cloud** into a deeply agentic assistant that can operate your Mac: | |
| 6 | +running `bash` commands and AppleScript, reading and writing files in per-task workspaces, | |
| 7 | +and iterating in a real plan→act→observe→reflect loop until the task is done — with | |
| 8 | +approvals, a risk-classifying policy gate, and a full audit log in front of every action. | |
| 9 | + | |
| 10 | +Sibling apps: **Zyquo Cloud** (chat client) · **Zyquo Local** (on-device models) · **Zyquo Agent** (this). | |
| 11 | + | |
| 12 | +## Requirements | |
| 13 | + | |
| 14 | +- macOS 13.0+ (Apple Silicon or Intel) | |
| 15 | +- Swift 6 command-line toolchain (Command Line Tools — the Xcode IDE is not used) | |
| 16 | +- The build pins `SDKROOT` to the MacOSX26 SDK (SDK 27's SwiftUI macros require Xcode); the | |
| 17 | + Makefile handles this automatically. | |
| 18 | + | |
| 19 | +## Build | |
| 20 | + | |
| 21 | +```bash | |
| 22 | +make dev # release build → dist/Zyquo Agent.app (ad-hoc signed, fast iteration) | |
| 23 | +make run # make dev + open the app | |
| 24 | +make release # universal binary, Developer ID sign, notarize, staple (Phase 8) | |
| 25 | +make icon # regenerate AppIcon.icns from assets/icon/zyquo-agent.svg | |
| 26 | +make test # swift test (requires an XCTest-capable toolchain) | |
| 27 | +make clean | |
| 28 | +``` | |
| 29 | + | |
| 30 | +Plain SPM also works: `swift build -c release` (export | |
| 31 | +`SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.sdk` first). | |
| 32 | + | |
| 33 | +## CLI modes | |
| 34 | + | |
| 35 | +The app binary doubles as a headless CLI: | |
| 36 | + | |
| 37 | +```bash | |
| 38 | +ZyquoAgent --run "create a folder ~/zqtest with a hello.txt, then list it" # agent loop POC | |
| 39 | +ZyquoAgent --verify # Phase 7 provider tool-calling harness (needs API keys) | |
| 40 | +ZyquoAgent --verify-policy # PolicyEngine safety self-checks | |
| 41 | +ZyquoAgent --load-vault # seed the encrypted key vault from environment variables | |
| 42 | +``` | |
| 43 | + | |
| 44 | +## Data locations | |
| 45 | + | |
| 46 | +- App data: `~/Library/Application Support/ZyquoAgent/` | |
| 47 | +- Per-task workspaces: `~/Library/Application Support/ZyquoAgent/Workspaces/` | |
| 48 | +- Encrypted key vault (AES-256-GCM, no Keychain — same design as Zyquo Cloud): `…/ZyquoAgent/vault.zq` | |
| 49 | + | |
| 50 | +## Documentation | |
| 51 | + | |
| 52 | +- `docs/PLAN.md` — phase-by-phase build plan and checkpoints | |
| 53 | +- `docs/AGENT-RESEARCH.md` — the agent-design research the architecture traces back to | |
| 54 | +- `docs/PROVIDER-REUSE.md` — the Zyquo Cloud provider study and porting contract | |
| 55 | + | |
| 56 | +API keys are **never** committed, logged, or embedded; they live only in the encrypted | |
| 57 | +vault (or env vars during testing). | |
| 58 | + | |
| 59 | +--- | |
| 60 | + | |
| 61 | +Author: Simon-Pierre Boucher · contact@spboucher.ai | |
| 62 | ||