From 566652129dfe5d958f6ebb77b15e0a2ff8f270a4 Mon Sep 17 00:00:00 2001 From: Alan Wizemann Date: Thu, 23 Apr 2026 18:16:54 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20v2.2.0=20=E2=80=94=20new=20Project=20Te?= =?UTF-8?q?mplates=20page=20+=20index=20+=20Home=20bump?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Home.md | 5 +- Project-Templates.md | 253 +++++++++++++++++++++++++++++++++++++++ Projects-and-Profiles.md | 5 +- Release-Notes-Index.md | 5 +- _Sidebar.md | 1 + 5 files changed, 265 insertions(+), 4 deletions(-) create mode 100644 Project-Templates.md diff --git a/Home.md b/Home.md index 81ed193..d5d93dd 100644 --- a/Home.md +++ b/Home.md @@ -2,7 +2,7 @@ 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.1.0](https://github.com/awizemann/scarf/releases/tag/v2.1.0) +**Latest release:** [v2.2.0](https://github.com/awizemann/scarf/releases/tag/v2.2.0) **Targets Hermes:** v0.9.0 (v2026.4.13) **Available in:** English, Simplified Chinese (zh-Hans), German (de), French (fr), Spanish (es), Japanese (ja), Brazilian Portuguese (pt-BR). See [Localization](Localization). @@ -10,6 +10,7 @@ A native macOS companion app for the [Hermes AI agent](https://github.com/hermes - [Installation](Installation) — download, first launch, system requirements - [First Run](First-Run) — what Scarf expects in `~/.hermes/` +- [Project Templates](Project-Templates) — `.scarftemplate` bundles, install / export / author - [Architecture Overview](Architecture-Overview) — MVVM-F, services, transport - [Servers & Remote](Servers-and-Remote) — adding remote Hermes hosts over SSH - [Localization](Localization) — supported languages + how to contribute a new one @@ -32,4 +33,4 @@ Scarf 2.0 is a multi-window app — one window per Hermes server, local or remot Open-source (MIT), 160+ stars, actively maintained. See [Roadmap](Roadmap) for what's coming. --- -_Last updated: 2026-04-21 — Scarf v2.1.0_ +_Last updated: 2026-04-23 — Scarf v2.2.0_ diff --git a/Project-Templates.md b/Project-Templates.md new file mode 100644 index 0000000..319aaf6 --- /dev/null +++ b/Project-Templates.md @@ -0,0 +1,253 @@ +# Project Templates + +`.scarftemplate` bundles — shareable projects for Scarf and any agent that reads the [agents.md](https://agents.md/) standard. Introduced in v2.2.0. + +A template packages everything needed to reproduce a project on another machine: the dashboard, the agent instructions, any skills, any scheduled cron jobs, an optional memory appendix, and — as of v2.2 — a typed configuration schema that drives a form during install. Templates are agent-portable out of the box: the same bundle works identically for users running Claude Code, Cursor, Codex, Aider, and the 20+ other agents that read `AGENTS.md`. + +## Quick jump + +- [Installing a template](#installing-a-template) +- [Configuring a template](#configuring-a-template) +- [The Site tab](#the-site-tab) +- [Uninstalling](#uninstalling) +- [Exporting a project as a template](#exporting-a-project-as-a-template) +- [Authoring a template](#authoring-a-template) — manifest, schema, AGENTS.md contract +- [The public catalog](#the-public-catalog) +- [Safe-by-design invariants](#safe-by-design-invariants) +- [Troubleshooting](#troubleshooting) + +## Installing a template + +Three entry points, all under **Projects → Templates** in the project sidebar's toolbar menu: + +1. **Install from File…** — pick a `.scarftemplate` from disk. +2. **Install from URL…** — paste an `https://` URL pointing at a `.scarftemplate`. +3. **`scarf://install?url=…`** — click a deep link in a browser. macOS hands it to Scarf via the registered URL scheme. Only `https://` targets are accepted; `http://`, `file://`, and `javascript:` are refused. The install sheet always opens for user confirmation — a deep link never installs silently. + +Every install goes through a preview sheet that lists: + +- The exact project directory to be created (you pick the parent folder). +- Every file inside the project. +- Every skill to be namespaced under `~/.hermes/skills/templates//`. +- Every cron job to be registered, always paused on install — you enable each one manually from the Cron sidebar when ready. +- Every Keychain secret the Configure step will write. +- A live diff of any memory appendix against your existing `MEMORY.md`. + +Nothing writes until you click **Install**. + +## Configuring a template + +Templates can declare a typed configuration schema. When present, Scarf inserts a **Configure** step between the parent-directory pick and the preview sheet. + +Seven field types are supported today: + +| Type | JSON key | Rendered as | Constraints | +|---|---|---|---| +| Single-line string | `"type": "string"` | Text field | `minLength`, `maxLength`, `pattern` (regex) | +| Multi-line string | `"type": "text"` | Text editor | `minLength`, `maxLength` | +| Number | `"type": "number"` | Number field | `min`, `max` | +| Boolean | `"type": "bool"` | Toggle | — | +| Enum | `"type": "enum"` | Segmented picker (≤4) / Dropdown (>4) | `options: [{value, label}]` | +| List of strings | `"type": "list"` + `"itemType": "string"` | Repeatable rows with add/remove | `minItems`, `maxItems` | +| Secret | `"type": "secret"` | Password field with show/hide | Stored in macOS Keychain | + +Non-secret values are written to `/.scarf/config.json` as plain JSON. Secrets are stored in the login Keychain under service name `com.scarf.template.` with an account keyed to a hash of the project directory path — two installs of the same template in different directories don't collide. + +After install, the **slider icon** in the dashboard header re-opens the same form pre-filled with current values. Change a site, rotate a token, toggle a feature; the next cron run picks up the new values automatically. Secrets are never echoed back — the form shows "Saved in Keychain — leave empty to keep the stored value" if the Keychain entry already exists. + +### Model recommendations + +A template can suggest a preferred model plus alternatives: + +```json +"modelRecommendation": { + "preferred": "claude-sonnet-4.5", + "rationale": "Tool-heavy workload — reasoning helps.", + "alternatives": ["claude-opus-4.1", "gpt-4.1"] +} +``` + +Scarf displays this in the Configure sheet without auto-switching your active model — always your call. Change it in Settings if you agree. + +## The Site tab + +A dashboard that includes at least one `webview` widget automatically gets a **Site** tab next to **Dashboard** in the project view. Useful for templates that watch something renderable — a site, a Grafana panel, a preview endpoint. + +The example `awizemann/site-status-checker` template uses this: on every cron run, the agent rewrites the webview's `url` field to the first configured site, so the Site tab stays in sync with whatever you configured. + +## Uninstalling + +Right-click any template-installed project in the sidebar → **Uninstall Template (remove installed files)…**, or click the uninstall icon in the dashboard header. + +Uninstall is driven by `/.scarf/template.lock.json`, which records everything the installer wrote. The preview sheet lists what will be removed and what will be preserved: + +- **Removed:** every file listed in the lock, the skills namespace directory (wholesale — it's isolated), every Keychain ref, every tagged cron job via `hermes cron remove`, the memory block between its `` markers, and the projects-registry entry. +- **Preserved:** every file in the project directory that *wasn't* installed by the template. If the cron job wrote a `status-log.md` or you dropped a personal file into the project folder, it stays. The directory itself is removed only if nothing user-owned is left inside; otherwise the directory is kept with just your files. A banner on the uninstall success screen explicitly lists preserved paths so you know what's left behind. + +There's no undo — reinstalling means re-running the install flow. + +### Remove from List vs. Uninstall Template + +Two distinct actions in the project sidebar's right-click menu: + +- **Remove from List (keep files)…** — *registry only*. Scarf forgets the project; nothing on disk is touched, cron jobs stay, Keychain secrets stay, skills stay. A confirmation dialog spells this out. Useful for hand-installed projects (not template-installed) or if you want to hide a project from the sidebar without destroying it. +- **Uninstall Template (remove installed files)…** — *full cleanup*, driven by the lock file as above. Only shown for projects that were installed from a `.scarftemplate`. + +## Exporting a project as a template + +Select any project → **Projects → Templates → Export "<name>" as Template…**. The form asks for: + +- Id (author/name, e.g. `awizemann/focus-dashboard`). +- Display name, version, description. +- Optional author block (name, url), category, tags. +- Optional icon + screenshots. +- Which skills from `~/.hermes/skills/` to include. +- Which cron jobs from `~/.hermes/cron/jobs.json` to include. +- Optional memory snippet to ship. + +The exporter carries the configuration *schema* from `/.scarf/manifest.json` into the bundle but **never** the user's values from `/.scarf/config.json`. Exporting is safe on projects with live config — your secrets and personal settings stay local. + +The output is a single `.scarftemplate` file you can hand to anyone, upload to a share, or submit to the public catalog. + +## Authoring a template + +The bundle is a zip with at minimum: + +``` +.scarftemplate +├── template.json # manifest (see below) +├── README.md # shown in the install preview +├── AGENTS.md # REQUIRED — cross-agent instructions +└── dashboard.json # copied to /.scarf/dashboard.json +``` + +And optionally: + +``` +├── instructions/ +│ ├── CLAUDE.md # Claude Code shim +│ ├── GEMINI.md +│ ├── .cursorrules +│ └── .github/copilot-instructions.md +├── skills/ +│ └── / +│ └── SKILL.md +├── cron/ +│ └── jobs.json # array of cron job definitions +└── memory/ + └── append.md # appended to ~/.hermes/memories/MEMORY.md +``` + +### Manifest (`template.json`) + +```json +{ + "schemaVersion": 2, + "id": "yourname/your-template", + "name": "Your Template", + "version": "1.0.0", + "description": "One-line description shown in catalog + install sheet.", + "author": { "name": "Your Name", "url": "https://github.com/yourname" }, + "category": "productivity", + "tags": ["example", "monitoring"], + "contents": { + "dashboard": true, + "agentsMd": true, + "instructions": ["CLAUDE.md"], + "skills": ["example-skill"], + "cron": 1, + "memory": true, + "config": 2 + }, + "config": { + "schema": [ + { "key": "site_url", "type": "string", "label": "Site URL", "required": true, + "pattern": "^https://" }, + { "key": "api_token", "type": "secret", "label": "API Token", "required": true } + ], + "modelRecommendation": { + "preferred": "claude-haiku-4", + "rationale": "Lightweight workload — haiku is plenty." + } + } +} +``` + +The `contents` block is a *claim* — the installer verifies every claim against the actual zip entries before anything touches disk. A bundle that ships 2 cron jobs while claiming `"cron": 1` is refused at load time. + +### `AGENTS.md` contract + +`AGENTS.md` is the single source of truth for what the project does and how to operate it. It must: + +- Describe the project's purpose and layout. +- Document every `~/.scarf/config.json` field the cron job reads. +- Document every file in the project the cron job writes. +- Document every widget in `dashboard.json` the cron job updates (by title + key). +- Use `{{PROJECT_DIR}}` in any path references — the installer substitutes absolute paths at install time. + +The cron job's `prompt` field in `cron/jobs.json` is the operational instruction; `AGENTS.md` is the reference spec. Both should agree; if they drift, catalog CI doesn't catch it, so template authors own the consistency. + +### Install-time token substitution + +In cron-job prompts and in `dashboard.json` strings, the installer substitutes: + +- `{{PROJECT_DIR}}` — absolute path of the newly-created project directory. +- `{{TEMPLATE_ID}}` — the `owner/name` id from the manifest. +- `{{TEMPLATE_SLUG}}` — the sanitised slug used for the skills namespace + project dir. + +Cron jobs need `{{PROJECT_DIR}}` because Hermes doesn't set a CWD when firing cron — relative paths would resolve against wherever Hermes happens to be. + +## The public catalog + +Published templates live at [awizemann.github.io/scarf/templates/](https://awizemann.github.io/scarf/templates/), generated from `templates///` in the [Scarf repo](https://github.com/awizemann/scarf/tree/main/templates). + +Each template gets a detail page with: + +- The README rendered as markdown. +- A live preview of the post-install dashboard (`site/widgets.js` renders the same widget vocabulary the app uses). +- The configuration schema rendered with constraint summaries ("1–25 items", "≥ 1", "Pattern: `^https://`"). +- A one-click install button that opens `scarf://install?url=…` in the user's browser. + +Submissions go through [`templates/CONTRIBUTING.md`](https://github.com/awizemann/scarf/blob/main/templates/CONTRIBUTING.md). A CI-enforced Python validator ([`tools/build-catalog.py`](https://github.com/awizemann/scarf/blob/main/tools/build-catalog.py)) mirrors the Swift-side invariants (supported field types, widget types, contents-claim verification, secret-with-default rejection, 5 MB bundle-size cap, high-confidence secret patterns). Bundles are raw-served from `main` at `https://raw.githubusercontent.com/awizemann/scarf/main/templates///.scarftemplate` — no per-template GitHub Releases ceremony. + +## Safe-by-design invariants + +The installer enforces these rules — a bundle that violates any of them is refused at load time: + +- **Never writes to global configuration:** `~/.hermes/config.yaml`, `auth.json`, sessions, or any credential path is off-limits. +- **Skills are namespaced:** `~/.hermes/skills/templates///` — never loose in the top-level skills dir, so uninstall is `rm -rf` on one folder. +- **Cron jobs are tagged and paused:** `[tmpl:] ` with `paused: true` on create. You enable each one manually from the Cron sidebar. +- **Secrets never land in `config.json`:** `secret`-type field values route through `SecItemAdd` and the config file stores `keychain://service/account` URIs. +- **Bundle size capped:** 50 MB at the install layer, 5 MB at the catalog-submission layer. +- **Install preview is load-bearing:** every file the installer will write appears in the sheet. There's no silent write path. + +## Troubleshooting + +**"The install sheet closes as soon as I click Continue on the Configure step."** +Fixed in v2.2.0. If you're seeing this, you're on an older dev build — update via Sparkle. + +**"Run Now on a cron job shows Run failed but the dashboard updates a minute later anyway."** +Fixed in v2.2.0. The cron tick timeout was too short; Run Now now shows "Agent started — dashboard will update when it finishes" without blocking. + +**"The Site tab shows a GitHub 404 instead of my configured site."** +Was a bug in the `awizemann/site-status-checker` template's pre-first-run placeholder URL. Fixed in v1.1.0 of that template. After install, the first cron run rewrites the URL to your first configured site. + +**"I uninstalled the project but the folder is still on disk."** +Intentional. The uninstaller preserves files that weren't installed by the template — typically a `status-log.md` written by a cron job. The uninstall success screen lists the preserved paths. Delete the folder from Finder if you don't need the extra files. + +**"I installed the same template twice and got an error."** +Expected — the installer refuses a re-install of the same template id into the same location to avoid double-appending to `MEMORY.md`. Uninstall the existing install first, or pick a different parent directory. + +**"My template's cron job runs but uses relative paths that don't resolve."** +Use `{{PROJECT_DIR}}` in the cron prompt. Hermes doesn't set a CWD for cron runs, so relative paths resolve against the agent's own dir. The installer substitutes `{{PROJECT_DIR}}` with the absolute project path at install time. + +## See also + +- [Installation](Installation) — getting Scarf set up in the first place. +- [Projects & Profiles](Projects-and-Profiles) — the broader Projects feature that templates build on. +- [Memory & Skills](Memory-and-Skills) — what the "memory appendix" and "skills" sections of a template reference. +- [Gateway / Cron / Health / Logs](Gateway-Cron-Health-Logs) — cron lifecycle beyond just templates. +- [Release Notes Index](Release-Notes-Index) — v2.2.0 for the full launch notes. + +--- +_Last updated: 2026-04-23 — Scarf v2.2.0_ diff --git a/Projects-and-Profiles.md b/Projects-and-Profiles.md index 453f106..d4140c1 100644 --- a/Projects-and-Profiles.md +++ b/Projects-and-Profiles.md @@ -24,6 +24,8 @@ The full schema is documented in [`scarf/docs/DASHBOARD_SCHEMA.md`](https://gith **Adding a project:** click + in the Projects sidebar, pick a directory. The project is registered in `~/.hermes/scarf/projects.json`; the dashboard JSON lives in `/.scarf/dashboard.json` (which you should add to your project's `.gitignore` if it's user-specific). +**Sharing a project:** as of v2.2.0, projects can be packaged into `.scarftemplate` bundles and shared with anyone — see [Project Templates](Project-Templates). Export turns a live project into a redistributable bundle; install unpacks one and sets up the dashboard, skills, cron jobs, and configuration schema in a single preview-and-confirm step. The public catalog lives at [awizemann.github.io/scarf/templates/](https://awizemann.github.io/scarf/templates/). + ## Profiles A profile is an isolated Hermes installation — separate config, sessions, memory, skills, the lot. Useful for keeping work / personal context separate, or for testing a config change without disturbing your main instance. @@ -39,9 +41,10 @@ Profiles live under `~/.hermes/profiles/`. The currently active profile is whate ## Related pages +- [Project Templates](Project-Templates) — `.scarftemplate` bundles, the install / export / author flows, the public catalog. - [Hermes Paths](Hermes-Paths) — `~/.hermes/profiles/` and the projects registry. - [Memory & Skills](Memory-and-Skills) — memory is profile-scoped. - [Settings](Gateway-Cron-Health-Logs) — exposes "Backup & Restore" buttons (`hermes backup` / `hermes import`) at the profile level. --- -_Last updated: 2026-04-20 — Scarf v2.0.1_ +_Last updated: 2026-04-23 — Scarf v2.2.0_ diff --git a/Release-Notes-Index.md b/Release-Notes-Index.md index a0329b2..0e97e62 100644 --- a/Release-Notes-Index.md +++ b/Release-Notes-Index.md @@ -4,6 +4,7 @@ Every Scarf release in chronological order. The notes themselves live in `releas | Version | Date | GitHub release | Notes file | |---|---|---|---| +| **v2.2.0** | 2026-04-23 | [v2.2.0](https://github.com/awizemann/scarf/releases/tag/v2.2.0) | [`releases/v2.2.0/RELEASE_NOTES.md`](https://github.com/awizemann/scarf/blob/main/releases/v2.2.0/RELEASE_NOTES.md) | | **v2.1.0** | 2026-04-21 | [v2.1.0](https://github.com/awizemann/scarf/releases/tag/v2.1.0) | [`releases/v2.1.0/RELEASE_NOTES.md`](https://github.com/awizemann/scarf/blob/main/releases/v2.1.0/RELEASE_NOTES.md) | | **v2.0.2** | 2026-04-20 | [v2.0.2](https://github.com/awizemann/scarf/releases/tag/v2.0.2) | [`releases/v2.0.2/RELEASE_NOTES.md`](https://github.com/awizemann/scarf/blob/main/releases/v2.0.2/RELEASE_NOTES.md) | | v2.0.1 | 2026-04-20 | [v2.0.1 (draft)](https://github.com/awizemann/scarf/releases/tag/v2.0.1) | [`releases/v2.0.1/RELEASE_NOTES.md`](https://github.com/awizemann/scarf/blob/main/releases/v2.0.1/RELEASE_NOTES.md) | @@ -15,6 +16,8 @@ Every Scarf release in chronological order. The notes themselves live in `releas ## Highlights by major +**2.2** — [Project Templates](Project-Templates): shareable `.scarftemplate` bundles with typed configuration schemas, Keychain-backed secrets, a public template catalog at [awizemann.github.io/scarf/templates/](https://awizemann.github.io/scarf/templates/), `scarf://install?url=…` deep links, CI-enforced PR validator, and a Site tab for webview-bearing dashboards. Cross-agent by default via the `AGENTS.md` standard — works in Claude Code, Cursor, Codex, Aider, and every other agent that reads it. + **2.1** — Full UI translations for six locales on top of English (Simplified Chinese, German, French, Spanish, Japanese, Brazilian Portuguese); locale-aware currency / byte-size / compact-number formatting; chat slash-command menu with filtering and argument hints; auto-scroll polish and loading state for chat session reconnects. **2.0** — Multi-server, remote Hermes over SSH, chat UX overhaul (no more flash, no scroll jumping, real error explanations), and a correctness pass that fixed remote WAL spam, stale-snapshot session resume, auto-resume of dead cron sessions, and 230+ Swift 6 concurrency warnings. @@ -34,4 +37,4 @@ When `scripts/release.sh ` completes a full (non-draft) release, this p This is one of the [wiki update triggers](Wiki-Maintenance) that future Claude Code sessions will follow automatically. --- -_Last updated: 2026-04-21 — Scarf v2.1.0_ +_Last updated: 2026-04-23 — Scarf v2.2.0_ diff --git a/_Sidebar.md b/_Sidebar.md index c039c45..d500ff9 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -10,6 +10,7 @@ - [Chat](Chat) - [Memory & Skills](Memory-and-Skills) - [Projects & Profiles](Projects-and-Profiles) +- [Project Templates](Project-Templates) - [Platforms / Personalities / Quick Commands](Platforms-Personalities-QuickCommands) - [Servers & Remote](Servers-and-Remote) - [MCP, Plugins, Webhooks, Tools](MCP-Servers-Plugins-Webhooks-Tools)