docs: v2.2.0 — new Project Templates page + index + Home bump

2026-05-10 02:26:37 +00:00 · 2026-04-23 18:16:54 +02:00
parent 6e5eeae7f7
commit 566652129d
5 changed files with 265 additions and 4 deletions
@@ -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_
@@ -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/<slug>/`.
+- 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 `<project>/.scarf/config.json` as plain JSON. Secrets are stored in the login Keychain under service name `com.scarf.template.<slug>` 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 `<project>/.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 `<!-- scarf-template:<id>:begin/end -->` 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 "&lt;name&gt;" 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 `<project>/.scarf/manifest.json` into the bundle but **never** the user's values from `<project>/.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:
+
+```
+<name>.scarftemplate
+├── template.json           # manifest (see below)
+├── README.md               # shown in the install preview
+├── AGENTS.md               # REQUIRED — cross-agent instructions
+└── dashboard.json          # copied to <project>/.scarf/dashboard.json
+```
+
+And optionally:
+
+```
+├── instructions/
+│   ├── CLAUDE.md           # Claude Code shim
+│   ├── GEMINI.md
+│   ├── .cursorrules
+│   └── .github/copilot-instructions.md
+├── skills/
+│   └── <skill-name>/
+│       └── 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/<author>/<name>/` 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/<author>/<name>/<name>.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/<slug>/<skill-name>/` — never loose in the top-level skills dir, so uninstall is `rm -rf` on one folder.
+- **Cron jobs are tagged and paused:** `[tmpl:<id>] <name>` 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_
@@ -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 `<project>/.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_
@@ -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 <version>` 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_
@@ -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)