diff --git a/ACP-Subprocess.md b/ACP-Subprocess.md new file mode 100644 index 0000000..3593fc6 --- /dev/null +++ b/ACP-Subprocess.md @@ -0,0 +1,6 @@ +# ACP Subprocess + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Adding-a-Feature-Module.md b/Adding-a-Feature-Module.md new file mode 100644 index 0000000..8d2bbaa --- /dev/null +++ b/Adding-a-Feature-Module.md @@ -0,0 +1,6 @@ +# Adding a Feature Module + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Adding-a-Service.md b/Adding-a-Service.md new file mode 100644 index 0000000..4b7171c --- /dev/null +++ b/Adding-a-Service.md @@ -0,0 +1,6 @@ +# Adding a Service + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Architecture-Overview.md b/Architecture-Overview.md new file mode 100644 index 0000000..757a5db --- /dev/null +++ b/Architecture-Overview.md @@ -0,0 +1,59 @@ +# Architecture Overview + +Scarf is a SwiftUI app organized around **MVVM-F** (Model-View-ViewModel-Feature). Each user-facing capability is a self-contained feature module; cross-feature concerns flow through shared services. There are no third-party UI dependencies — system SQLite3, Foundation JSON, and SwiftUI's `AttributedString` markdown carry the load. + +## Layering at a glance + +``` +Features/ SwiftUI views + @Observable ViewModels (one per capability) +Navigation/ AppCoordinator (single source of truth for navigation state) +Core/Services/ Shared services injected via .environment() +Core/Models/ Plain Codable structs +Core/Transport/ Local + SSH transport behind one protocol +Core/Persistence/ Server registry (Codable plist) +Core/Utilities/ Markdown rendering, shared helpers +``` + +See [Core Services](Core-Services), [Data Model](Data-Model), [Transport Layer](Transport-Layer), and [Sidebar & Navigation](Sidebar-and-Navigation) for the detail per layer. + +## Key invariants + +- **Features never import sibling features.** Cross-feature operations go through `AppCoordinator` (for navigation state) or a service (for data). +- **Read-only DB access.** Scarf never writes to `~/.hermes/state.db`. The only files Scarf writes are memory files (`MEMORY.md`, `USER.md`), cron job definitions, `.env`, `config.yaml`, and per-server snapshot caches. +- **Sandbox disabled.** Scarf needs to read `~/.hermes/` directly, so the App Sandbox entitlement is intentionally off. There are no extra entitlements beyond standard macOS. +- **Swift 6 strict concurrency.** `@MainActor` is the default isolation; services use `nonisolated` async methods and route results back to MainActor for UI updates. +- **No external runtime dependencies.** Sparkle (for updates) is the only SPM dependency. + +## Navigation model + +A single `@Observable AppCoordinator` holds `selectedSection: SidebarSection`, `selectedSessionId`, and `selectedProjectName`. It is injected into the view tree via `.environment()`. The sidebar reads/writes the selection; feature views observe it. This keeps "where are we" in one place rather than scattered across views. + +The sidebar groups capabilities into four sections: **Monitor**, **Interact**, **Configure**, **Manage**. See [Sidebar & Navigation](Sidebar-and-Navigation) for the full section list. + +## Multi-server: one window per server + +Scarf 2.0 is multi-window. Each window binds to exactly one **`ServerContext`** — either the local `~/.hermes/` (synthesized automatically) or a remote SSH host. Windows are independent; opening a second window for a different server gives you side-by-side state. + +Server state lives in the `ServerRegistry` (`Core/Persistence/`), which serializes to `~/Library/Preferences/com.scarf.app`. A window's `ServerContext` is built once and provides the unified API services use: + +- `context.readText(path)` / `writeText(path, body)` — file I/O via the active transport. +- `context.runHermes(args…)` — invokes `hermes` locally or `ssh host -- hermes` remotely. +- `context.openInLocalEditor(path)` — pulls remote files local first, then opens. +- `context.transport` — `LocalTransport` or `SSHTransport`, both implementing `ServerTransport`. + +Services receive a `ServerContext`, never raw `FileManager`, `Process`, or `NSWorkspace.open` for Hermes paths. See [Transport Layer](Transport-Layer) for the protocol details. + +## Chat — ACP subprocess + +The Rich Chat surface speaks the Hermes Agent Client Protocol (ACP) — a JSON-RPC dialect over stdio. `ACPClient` spawns `hermes acp` (locally) or `ssh -T host -- hermes acp` (remote) and exposes an async event stream. No SQLite polling is involved — chat is end-to-end real-time. See [ACP Subprocess](ACP-Subprocess). + +## File watching + +`HermesFileWatcher` reacts to changes under `~/.hermes/` so the Dashboard, Sessions browser, Activity feed, and Memory viewer refresh without manual reload. Local windows use FSEvents (`DispatchSourceFileSystemObject`); remote windows use mtime polling tunneled over the SSH ControlMaster. + +## Updates + +`UpdaterService` is a thin wrapper around Sparkle. The appcast lives at `https://awizemann.github.io/scarf/appcast.xml` (gh-pages branch); each entry is EdDSA-signed by the release script. See [Release Process](Release-Process). + +--- +_Last updated: 2026-04-20 — Scarf v2.0.1_ diff --git a/Build-and-Run.md b/Build-and-Run.md new file mode 100644 index 0000000..b48e938 --- /dev/null +++ b/Build-and-Run.md @@ -0,0 +1,6 @@ +# Build and Run + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Chat.md b/Chat.md new file mode 100644 index 0000000..dfe825d --- /dev/null +++ b/Chat.md @@ -0,0 +1,6 @@ +# Chat + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Contributing.md b/Contributing.md new file mode 100644 index 0000000..521a1bb --- /dev/null +++ b/Contributing.md @@ -0,0 +1,6 @@ +# Contributing + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Core-Services.md b/Core-Services.md new file mode 100644 index 0000000..68939c1 --- /dev/null +++ b/Core-Services.md @@ -0,0 +1,6 @@ +# Core Services + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Dashboard.md b/Dashboard.md new file mode 100644 index 0000000..8b0e1a8 --- /dev/null +++ b/Dashboard.md @@ -0,0 +1,6 @@ +# Dashboard + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Data-Model.md b/Data-Model.md new file mode 100644 index 0000000..69353e5 --- /dev/null +++ b/Data-Model.md @@ -0,0 +1,6 @@ +# Data Model + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/First-Run.md b/First-Run.md new file mode 100644 index 0000000..158ed6d --- /dev/null +++ b/First-Run.md @@ -0,0 +1,6 @@ +# First Run + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Gateway-Cron-Health-Logs.md b/Gateway-Cron-Health-Logs.md new file mode 100644 index 0000000..50ee00b --- /dev/null +++ b/Gateway-Cron-Health-Logs.md @@ -0,0 +1,6 @@ +# Gateway Cron Health Logs + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Hermes-Paths.md b/Hermes-Paths.md new file mode 100644 index 0000000..c17fd9e --- /dev/null +++ b/Hermes-Paths.md @@ -0,0 +1,39 @@ +# Hermes Paths + +Canonical layout of `~/.hermes/`. Scarf reads these paths through `HermesPathSet` (`Core/Models/HermesPathSet.swift`). Updates here should also be mirrored to the **Key Paths** block in `CLAUDE.md` in the main repo. + +| Path | What lives here | Scarf access | +|---|---|---| +| `~/.hermes/` | Hermes home | read-only base | +| `~/.hermes/state.db` | SQLite (WAL mode) — sessions, messages, activity, costs | **read-only**, never written | +| `~/.hermes/config.yaml` | Hermes runtime config (platforms, models, LLM settings, ~60 fields) | read + write (via Settings) | +| `~/.hermes/.env` | Secrets and env vars referenced by `config.yaml` | read + write (preserves comments + blanks) | +| `~/.hermes/memories/MEMORY.md` | Hermes's project/topic memory | read + write | +| `~/.hermes/memories/USER.md` | Hermes's user memory | read + write | +| `~/.hermes/sessions/session_*.json` | Session metadata files | read-only | +| `~/.hermes/cron/jobs.json` | Scheduled job definitions | read + write | +| `~/.hermes/logs/agent.log` | Agent log (per-session tagged) | read-only, tail | +| `~/.hermes/logs/errors.log` | Error log | read-only, tail | +| `~/.hermes/logs/gateway.log` | Messaging-gateway log | read-only, tail | +| `~/.hermes/skills/` | Installed skills | read + write (install/update/uninstall) | +| `~/.hermes/plugins/` | Installed plugins (cloned from Git URLs) | read + write | +| `~/.hermes/personalities/` | Personalities + their `SOUL.md` | read + write | +| `~/.hermes/profiles/` | Isolated Hermes instances | read + write | + +## ACP + +Chat does not go through the filesystem. It is a subprocess: `hermes acp` (local) or `ssh -T host -- hermes acp` (remote), with JSON-RPC over stdio. See [ACP Subprocess](ACP-Subprocess). + +## Mac-side caches + +| Path | What lives here | +|---|---| +| `~/Library/Caches/scarf/snapshots//` | Atomic `state.db` snapshots pulled from remote servers via `sqlite3 .backup` | +| `~/Library/Preferences/com.scarf.app.plist` | App preferences + the server registry | + +## Log line format + +Hermes log lines may carry an optional `[session_id]` tag between the level and the logger name. `HermesLogService.parseLine` treats the session tag as an optional capture group, so older untagged lines still parse correctly. + +--- +_Last updated: 2026-04-20 — Scarf v2.0.1_ diff --git a/Hermes-Version-Compatibility.md b/Hermes-Version-Compatibility.md new file mode 100644 index 0000000..e52b070 --- /dev/null +++ b/Hermes-Version-Compatibility.md @@ -0,0 +1,6 @@ +# Hermes Version Compatibility + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Home.md b/Home.md index d7f377b..b94e379 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,33 @@ -Welcome to the scarf wiki! +# Scarf + +A native macOS companion app for the [Hermes AI agent](https://github.com/hermes-ai/hermes-agent). Full visibility into what Hermes is doing, when, and what it creates — across one local install or many remote ones. + +**Latest release:** [v2.0.1](https://github.com/awizemann/scarf/releases/tag/v2.0.1) +**Targets Hermes:** v0.9.0 (v2026.4.13) + +## Quick links + +- [Installation](Installation) — download, first launch, system requirements +- [First Run](First-Run) — what Scarf expects in `~/.hermes/` +- [Architecture Overview](Architecture-Overview) — MVVM-F, services, transport +- [Servers & Remote](Servers-and-Remote) — adding remote Hermes hosts over SSH +- [Release Notes Index](Release-Notes-Index) — every version's notes +- [Wiki Maintenance](Wiki-Maintenance) — how this wiki is edited and kept in sync + +## What Scarf does + +Scarf mirrors Hermes's surface area through a sidebar-based UI grouped into four sections: + +- **Monitor** — Dashboard, Insights, Sessions, Activity. See what Hermes is doing. +- **Interact** — Chat, Memory, Skills. Talk to Hermes and shape what it knows. +- **Configure** — Platforms, Personalities, Quick Commands, Credential Pools, Plugins, Webhooks, Profiles, Servers. Set Hermes up. +- **Manage** — Tools, MCP Servers, Gateway, Cron, Health, Logs, Settings. Operate Hermes. + +Scarf 2.0 is a multi-window app — one window per Hermes server, local or remote. Remote hosts are reached over plain SSH using your existing `~/.ssh/config`, agent, ProxyJump, and ControlMaster. + +## Project status + +Open-source (MIT), 160+ stars, actively maintained. See [Roadmap](Roadmap) for what's coming. + +--- +_Last updated: 2026-04-20 — Scarf v2.0.1_ diff --git a/Insights-and-Activity.md b/Insights-and-Activity.md new file mode 100644 index 0000000..e17ba7c --- /dev/null +++ b/Insights-and-Activity.md @@ -0,0 +1,6 @@ +# Insights and Activity + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Installation.md b/Installation.md new file mode 100644 index 0000000..747c5d2 --- /dev/null +++ b/Installation.md @@ -0,0 +1,46 @@ +# Installation + +## System requirements + +- **macOS 14.6+ (Sonoma)** or newer. +- **Hermes** installed at `~/.hermes/` for the local server window. (Remote servers are reached over SSH and don't need anything on the Mac side beyond what's already there.) +- Apple Silicon or Intel Mac (Universal binary). An ARM64-only build is also published if you want a smaller download. + +## Download + +Get the latest release from [GitHub Releases](https://github.com/awizemann/scarf/releases/latest): + +- **`Scarf-v-Universal.zip`** — works on every supported Mac. +- **`Scarf-v-ARM64.zip`** — Apple Silicon only, smaller download. + +## First launch (Gatekeeper) + +Scarf is signed with a Developer ID and notarized by Apple, so the first launch should not require any right-click-to-open dance. If macOS still complains: + +1. Open **System Settings → Privacy & Security**. +2. Scroll to the message about Scarf being blocked and click **Open Anyway**. +3. Confirm in the prompt that follows. + +This only happens once per install. + +## What gets installed + +Scarf is a self-contained `.app` bundle. It does **not** install background services, launch agents, or kernel extensions. It reads `~/.hermes/` directly (sandbox is intentionally off — see [Architecture Overview](Architecture-Overview)). + +Caches written by Scarf: + +- `~/Library/Caches/scarf/snapshots//` — atomic SQLite snapshots pulled from remote servers. +- `~/Library/Preferences/com.scarf.app.plist` — preferences and the server registry (when added). + +## Auto-updates + +Scarf uses [Sparkle](https://sparkle-project.org/) for automatic updates from a GitHub-Pages-hosted appcast. See [Updating](Updating). + +## Next + +- [First Run](First-Run) — what Scarf expects in `~/.hermes/`. +- [Servers & Remote](Servers-and-Remote) — adding remote Hermes hosts. +- [Uninstalling](Uninstalling) — removing the app and its files. + +--- +_Last updated: 2026-04-20 — Scarf v2.0.1_ diff --git a/Keyboard-Shortcuts.md b/Keyboard-Shortcuts.md new file mode 100644 index 0000000..4296abe --- /dev/null +++ b/Keyboard-Shortcuts.md @@ -0,0 +1,6 @@ +# Keyboard Shortcuts + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/MCP-Servers-Plugins-Webhooks-Tools.md b/MCP-Servers-Plugins-Webhooks-Tools.md new file mode 100644 index 0000000..8e2b8ce --- /dev/null +++ b/MCP-Servers-Plugins-Webhooks-Tools.md @@ -0,0 +1,6 @@ +# MCP Servers Plugins Webhooks Tools + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Memory-and-Skills.md b/Memory-and-Skills.md new file mode 100644 index 0000000..d11624d --- /dev/null +++ b/Memory-and-Skills.md @@ -0,0 +1,6 @@ +# Memory and Skills + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Platforms-Personalities-QuickCommands.md b/Platforms-Personalities-QuickCommands.md new file mode 100644 index 0000000..f80996f --- /dev/null +++ b/Platforms-Personalities-QuickCommands.md @@ -0,0 +1,6 @@ +# Platforms Personalities QuickCommands + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Projects-and-Profiles.md b/Projects-and-Profiles.md new file mode 100644 index 0000000..6f4d487 --- /dev/null +++ b/Projects-and-Profiles.md @@ -0,0 +1,6 @@ +# Projects and Profiles + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Release-Notes-Index.md b/Release-Notes-Index.md new file mode 100644 index 0000000..ad132e1 --- /dev/null +++ b/Release-Notes-Index.md @@ -0,0 +1,6 @@ +# Release Notes Index + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Release-Process.md b/Release-Process.md new file mode 100644 index 0000000..3432291 --- /dev/null +++ b/Release-Process.md @@ -0,0 +1,46 @@ +# Release Process + +Scarf releases are produced by a single local script: [`scripts/release.sh`](https://github.com/awizemann/scarf/blob/main/scripts/release.sh) in the main repo. **The script is the source of truth** — this page is a public-facing summary; do not duplicate prerequisites or step-by-step internals here. + +## Modes + +```bash +./scripts/release.sh # full release: notarize → appcast → gh-pages → tag +./scripts/release.sh --draft # builds + notarizes, but skips appcast/tag +``` + +A full release bumps the version, archives Universal (arm64 + x86_64) + ARM64-only variants, signs with Developer ID, notarizes via `xcrun notarytool`, staples, EdDSA-signs the appcast entry with Sparkle's key, pushes the appcast to `gh-pages`, and creates a GitHub release with both zips attached. + +A draft release stops after the GitHub release is uploaded, so the current version stays "latest" until explicitly promoted. + +## Release notes + +Notes go in `releases/v/RELEASE_NOTES.md` **before** running the script. The script auto-includes the file in the version-bump commit and uses it as the GitHub release body. If absent, a placeholder is used. + +## Promotion (draft → real) + +After running with `--draft`: + +1. Edit the GitHub release → uncheck **Set as draft** → Publish. +2. Push the bump commit: `git push origin main`. +3. Tag and push: `git tag v && git push origin v`. +4. Merge the appcast entry (`releases/v/appcast-entry.xml`) into `gh-pages` `appcast.xml`, commit, push. + +## Sparkle signing key + +Releases are EdDSA-signed by Sparkle. The private key lives in the user's macOS Keychain under `https://sparkle-project.org`; the public key is embedded in `Info.plist` as `SUPublicEDKey`. **If the private key is lost, no installed Scarf can ever update again.** There is no recovery — every existing user would have to manually download a new build. + +## Where things live + +- Release script: [`scripts/release.sh`](https://github.com/awizemann/scarf/blob/main/scripts/release.sh) (full prerequisites in the file header) +- Per-version notes + appcast entry: `releases/v/` +- Appcast feed: `https://awizemann.github.io/scarf/appcast.xml` +- Releases page: + +## After a full release + +- Bump the **Latest release** line on [Home](Home). +- Append the new version to [Release Notes Index](Release-Notes-Index). + +--- +_Last updated: 2026-04-20 — Scarf v2.0.1_ diff --git a/Roadmap.md b/Roadmap.md new file mode 100644 index 0000000..5f7b0f4 --- /dev/null +++ b/Roadmap.md @@ -0,0 +1,6 @@ +# Roadmap + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Servers-and-Remote.md b/Servers-and-Remote.md new file mode 100644 index 0000000..d71d8f4 --- /dev/null +++ b/Servers-and-Remote.md @@ -0,0 +1,6 @@ +# Servers and Remote + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Sidebar-and-Navigation.md b/Sidebar-and-Navigation.md new file mode 100644 index 0000000..1d37df7 --- /dev/null +++ b/Sidebar-and-Navigation.md @@ -0,0 +1,6 @@ +# Sidebar and Navigation + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Testing.md b/Testing.md new file mode 100644 index 0000000..7eb9d7b --- /dev/null +++ b/Testing.md @@ -0,0 +1,6 @@ +# Testing + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Transport-Layer.md b/Transport-Layer.md new file mode 100644 index 0000000..510b2c9 --- /dev/null +++ b/Transport-Layer.md @@ -0,0 +1,6 @@ +# Transport Layer + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Uninstalling.md b/Uninstalling.md new file mode 100644 index 0000000..8043c5d --- /dev/null +++ b/Uninstalling.md @@ -0,0 +1,6 @@ +# Uninstalling + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Updating.md b/Updating.md new file mode 100644 index 0000000..9fd78c9 --- /dev/null +++ b/Updating.md @@ -0,0 +1,6 @@ +# Updating + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: 2026-04-20 — stub_ diff --git a/Wiki-Maintenance.md b/Wiki-Maintenance.md new file mode 100644 index 0000000..5aa7152 --- /dev/null +++ b/Wiki-Maintenance.md @@ -0,0 +1,95 @@ +# Wiki Maintenance + +This wiki is the public reference for Scarf. It is a separate git repo (`scarf.wiki.git`) at . This page documents how it is edited, what should and should not go in it, and how it stays in sync with the code. + +## Local clone + +The wiki is cloned to `.wiki-worktree/` in the main repo (gitignored, sibling to `.gh-pages-worktree/`). + +```bash +git clone git@github.com:awizemann/scarf.wiki.git .wiki-worktree +``` + +If the directory is deleted, re-run the clone — the remote is authoritative. + +## The helper: `scripts/wiki.sh` + +All routine work goes through `scripts/wiki.sh`, which wraps the local clone with a two-pass secret-scan. + +``` +./scripts/wiki.sh status # git status inside .wiki-worktree/ +./scripts/wiki.sh pull # fetch + fast-forward (aborts if dirty) +./scripts/wiki.sh new # create a stub page with dashed filename +./scripts/wiki.sh stub-check # list pages still containing the TODO marker +./scripts/wiki.sh commit "" # secret-scan, then git add -A && git commit +./scripts/wiki.sh push # secret-scan again, then git push +./scripts/wiki.sh touch # bump "Last updated" line to today +./scripts/wiki.sh --help # full usage including bootstrap +``` + +`pull` always runs first in any session — it aborts if the worktree is dirty, which prevents accidental overwrites of UI-edited pages. + +## When to update + +Update the wiki when work changes user-visible behavior, adds a feature module or core service, changes architecture, bumps the Hermes version, or ships a full release. + +**Skip** for bug fixes with no observable behavior change, pure refactors, typos, test-only changes, internal cleanups. + +## What never goes in the wiki + +- API keys, OAuth tokens, GitHub tokens, AWS keys, Slack tokens, etc. The secret-scan blocks common patterns by default. +- Private-key headers (`-----BEGIN ... PRIVATE KEY-----`, OpenSSH). +- Real `.env` file contents. +- Real hostnames or IPs of the maintainer's machines. A user-maintained blocklist at `scripts/wiki-blocklist.txt` (gitignored) catches these as hard blocks. +- Screenshots that include any of the above, or third-party chat content. + +The scan has two tiers: + +- **Hard patterns** — token regexes + the user blocklist. Any match aborts the commit or push with a non-zero exit. +- **Soft assignments** — `key = value` style lines where the key looks like a secret name (password, api_key, secret_key, token, auth_token, bearer). Matches print a warning and require `--force-terms` on the commit/push to proceed. This page is exempt because it documents the patterns. + +Do not bypass the scan without explicit approval from the maintainer. + +## Page conventions + +- **Filenames** use dashes for spaces (`Memory-and-Skills.md`). GitHub URL-encodes the title automatically. +- **Internal links** use Markdown syntax with the dashed name: `[Memory & Skills](Memory-and-Skills)`. **Not** `[[Page]]` — GitHub wikis don't support MediaWiki-style brackets. +- Every page **ends with**: + ``` + --- + _Last updated: YYYY-MM-DD — Scarf v_ + ``` + Stub pages use `— stub` in place of the version. +- Sidebar lives in `_Sidebar.md`; footer in `_Footer.md`; root is `Home.md`. + +## Stub workflow + +`./scripts/wiki.sh new Some-Page` seeds a page with this template: + +```markdown +# Some Page + +> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance). + +--- +_Last updated: YYYY-MM-DD — stub_ +``` + +`./scripts/wiki.sh stub-check` lists every page still containing that marker so unfinished pages are visible. + +## Source-of-truth rules + +- **Release Process** on the wiki is a pointer; the canonical instructions live in `CLAUDE.md` and the header of `scripts/release.sh`. +- **Hermes Paths** mirrors the Key Paths block in `CLAUDE.md` — update both when paths change. +- **Release notes** stay in `releases/v/RELEASE_NOTES.md` on `main`. The wiki's [Release Notes Index](Release-Notes-Index) only links out. +- **Internal dev notes** (PRD, Hermes API discovery, raw architecture) live in `scarf/docs/` in the main repo. The wiki carries the public-relevant parts in distilled form, not full duplicates. + +## For external contributors + +The wiki is **not forked** when someone forks the main repo — it is a separate hidden repo. Two ways to contribute: + +- **Small fixes (typos, clarifications):** click **Edit** on any wiki page in the GitHub UI. Push access to the main repo is required (editing is restricted to collaborators). +- **Larger changes:** clone `git@github.com:awizemann/scarf.wiki.git` directly, or open an issue describing the proposed change and we'll work it in. + +--- +_Last updated: 2026-04-20 — Scarf v2.0.1_ diff --git a/_Footer.md b/_Footer.md new file mode 100644 index 0000000..21f4603 --- /dev/null +++ b/_Footer.md @@ -0,0 +1 @@ +_Wiki edited via the local `.wiki-worktree/` clone. See [Wiki Maintenance](Wiki-Maintenance) for the workflow. Last sync: 2026-04-20._ diff --git a/_Sidebar.md b/_Sidebar.md new file mode 100644 index 0000000..c039c45 --- /dev/null +++ b/_Sidebar.md @@ -0,0 +1,44 @@ +**Getting Started** +- [Installation](Installation) +- [First Run](First-Run) +- [Updating](Updating) +- [Uninstalling](Uninstalling) + +**User Guide** +- [Dashboard](Dashboard) +- [Insights & Activity](Insights-and-Activity) +- [Chat](Chat) +- [Memory & Skills](Memory-and-Skills) +- [Projects & Profiles](Projects-and-Profiles) +- [Platforms / Personalities / Quick Commands](Platforms-Personalities-QuickCommands) +- [Servers & Remote](Servers-and-Remote) +- [MCP, Plugins, Webhooks, Tools](MCP-Servers-Plugins-Webhooks-Tools) +- [Gateway / Cron / Health / Logs](Gateway-Cron-Health-Logs) + +**Architecture** +- [Overview](Architecture-Overview) +- [Core Services](Core-Services) +- [Data Model](Data-Model) +- [Transport Layer](Transport-Layer) +- [Sidebar & Navigation](Sidebar-and-Navigation) +- [ACP Subprocess](ACP-Subprocess) + +**Developer Guide** +- [Build & Run](Build-and-Run) +- [Adding a Feature Module](Adding-a-Feature-Module) +- [Adding a Service](Adding-a-Service) +- [Testing](Testing) +- [Release Process](Release-Process) + +**Reference** +- [Hermes Paths](Hermes-Paths) +- [Hermes Version Compatibility](Hermes-Version-Compatibility) +- [Keyboard Shortcuts](Keyboard-Shortcuts) + +**Contributing** +- [Contributing](Contributing) +- [Wiki Maintenance](Wiki-Maintenance) + +**Release History** +- [Release Notes Index](Release-Notes-Index) +- [Roadmap](Roadmap)