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

2026-05-10 10:36:35 +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)