mirror of
https://github.com/awizemann/scarf.git
synced 2026-05-10 02:26:37 +00:00
docs: bootstrap wiki — 8 full pages, 26 stubs, sidebar/footer/home
Alan Wizemann
@@ -0,0 +1,6 @@
|
||||
# ACP Subprocess
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
@@ -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_
|
||||
@@ -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_
|
||||
@@ -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_
|
||||
@@ -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_
|
||||
+6
@@ -0,0 +1,6 @@
|
||||
# Chat
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
@@ -0,0 +1,6 @@
|
||||
# Contributing
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
@@ -0,0 +1,6 @@
|
||||
# Core Services
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
+6
@@ -0,0 +1,6 @@
|
||||
# Dashboard
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
@@ -0,0 +1,6 @@
|
||||
# Data Model
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
+6
@@ -0,0 +1,6 @@
|
||||
# First Run
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
@@ -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_
|
||||
+39
@@ -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/<server-id>/` | 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_
|
||||
@@ -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_
|
||||
+33
-1
@@ -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_
|
||||
|
||||
@@ -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_
|
||||
+46
@@ -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<version>-Universal.zip`** — works on every supported Mac.
|
||||
- **`Scarf-v<version>-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/<server-id>/` — 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_
|
||||
@@ -0,0 +1,6 @@
|
||||
# Keyboard Shortcuts
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
@@ -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_
|
||||
@@ -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_
|
||||
@@ -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_
|
||||
@@ -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_
|
||||
@@ -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_
|
||||
@@ -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 <VERSION> # full release: notarize → appcast → gh-pages → tag
|
||||
./scripts/release.sh <VERSION> --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<VERSION>/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<VERSION> && git push origin v<VERSION>`.
|
||||
4. Merge the appcast entry (`releases/v<VERSION>/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<version>/`
|
||||
- Appcast feed: `https://awizemann.github.io/scarf/appcast.xml`
|
||||
- Releases page: <https://github.com/awizemann/scarf/releases>
|
||||
|
||||
## 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_
|
||||
+6
@@ -0,0 +1,6 @@
|
||||
# Roadmap
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
@@ -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_
|
||||
@@ -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_
|
||||
+6
@@ -0,0 +1,6 @@
|
||||
# Testing
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
@@ -0,0 +1,6 @@
|
||||
# Transport Layer
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
@@ -0,0 +1,6 @@
|
||||
# Uninstalling
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
+6
@@ -0,0 +1,6 @@
|
||||
# Updating
|
||||
|
||||
> **TODO: document.** This page is a stub. See [Wiki Maintenance](Wiki-Maintenance).
|
||||
|
||||
---
|
||||
_Last updated: 2026-04-20 — stub_
|
||||
@@ -0,0 +1,95 @@
|
||||
# Wiki Maintenance
|
||||
|
||||
This wiki is the public reference for Scarf. It is a separate git repo (`scarf.wiki.git`) at <https://github.com/awizemann/scarf/wiki>. 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 <Page-Name> # create a stub page with dashed filename
|
||||
./scripts/wiki.sh stub-check # list pages still containing the TODO marker
|
||||
./scripts/wiki.sh commit "<msg>" # secret-scan, then git add -A && git commit
|
||||
./scripts/wiki.sh push # secret-scan again, then git push
|
||||
./scripts/wiki.sh touch <Page-Name> # 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<current>_
|
||||
```
|
||||
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<ver>/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_
|
||||
+1
@@ -0,0 +1 @@
|
||||
_Wiki edited via the local `.wiki-worktree/` clone. See [Wiki Maintenance](Wiki-Maintenance) for the workflow. Last sync: 2026-04-20._
|
||||
+44
@@ -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)
|
||||
Reference in New Issue
Block a user