chore: Bump version to 2.2.1

Covers the four commits landed since v2.2.0:

- New catalog template: awizemann/template-author (scaffolding skill)
- Config sheet fix: EnumControl always uses Menu picker, not Segmented
  (the long-option-label overflow that clipped the form)
- Config sheet fix: maxWidth constraint on inner VStacks so descriptions
  with unbreakable tokens wrap cleanly
- SKILL.md authoring guidance: prefer markdown link syntax over raw URLs
- Devops: scripts/catalog.sh accepts git worktrees

release.sh picks up this file as the GitHub release body.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.github/PULL_REQUEST_TEMPLATE/template-submission.md

@@ -0,0 +1,42 @@
+<!--
+Use this template when submitting a new Scarf project template or updating
+an existing one. For regular code/docs PRs, delete this template and write
+your own summary.
+
+Switch to this template by adding `?template=template-submission.md` to the
+compare URL, or let GitHub pick it up automatically when you touch files
+under templates/.
+-->
+
+## What's in this PR
+
+- [ ] New template: `templates/<your-handle>/<your-template-name>/`
+- [ ] Update to existing template: `templates/<author>/<name>/` (which one and why)
+
+## One-line pitch
+
+_What does this template do for its installers? Two sentences max._
+
+## Checklist
+
+- [ ] I wrote this template, or have the author's explicit permission to submit it.
+- [ ] `AGENTS.md` is present and tells any cross-agent what the project does and how to run it.
+- [ ] `README.md` includes install, customize, and uninstall instructions.
+- [ ] The bundle's `template.json` `contents` claim matches what's actually in the zip.
+- [ ] Cron jobs (if any) ship paused and use self-contained prompts.
+- [ ] No secrets in any file (API keys, tokens, hostnames, IPs, credentials).
+- [ ] No writes to `config.yaml`, `auth.json`, or credential paths — v1 installer will refuse.
+- [ ] `python3 tools/build-catalog.py --check` passes locally.
+- [ ] I installed + uninstalled this template on my machine and verified the `AGENTS.md` contract works end-to-end.
+- [ ] I did **not** edit `templates/catalog.json` — the maintainer regenerates it post-merge.
+
+## Testing notes
+
+_What did you run, what did you see? Paste the log output of the cron job
+firing once, or the chat transcript of asking the agent to do the main
+thing. Reviewers don't have your machine — show, don't tell._
+
+## Screenshots (optional)
+
+_Drop screenshots of the installed dashboard, or the catalog detail page
+rendered locally (`./scripts/catalog.sh preview && open /tmp/scarf-catalog-preview/templates/<slug>/index.html`)._

.github/workflows/validate-template-pr.yml

@@ -0,0 +1,74 @@
+# Validates `.scarftemplate` bundles on PRs that touch templates/.
+#
+# Mirrors the invariants `ProjectTemplateService.verifyClaims` enforces at
+# install time. Runs the same Python script the maintainer uses locally
+# (tools/build-catalog.py --check) so a bundle can't reach main unless the
+# validator is happy.
+#
+# Also runs tools/test_build_catalog.py so drift between the validator and
+# its own test suite is caught on the same PR.
+
+name: Validate template submissions
+
+on:
+  pull_request:
+    paths:
+      - 'templates/**'
+      - 'tools/build-catalog.py'
+      - 'tools/test_build_catalog.py'
+      - '.github/workflows/validate-template-pr.yml'
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Full clone so we can diff against the PR base and scope
+          # --only to just the changed templates if we want to later.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          # The validator is stdlib-only and tested against 3.9+ (the
+          # system Python on current macOS, what most maintainers run
+          # locally). CI uses 3.11 for faster cold-cache times on
+          # GitHub Actions runners — same stdlib APIs, same code paths.
+          python-version: '3.11'
+
+      - name: Run validator unit tests
+        run: python3 tools/test_build_catalog.py -v
+
+      - name: Validate every template
+        id: validate
+        run: |
+          set -o pipefail
+          python3 tools/build-catalog.py --check 2>&1 | tee /tmp/validator.log
+
+      - name: Post failure comment
+        if: failure() && steps.validate.outcome == 'failure'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            let body = '## Template validation failed\n\n';
+            try {
+              const log = fs.readFileSync('/tmp/validator.log', 'utf8');
+              body += '```\n' + log.slice(-3000) + '\n```\n';
+            } catch (e) {
+              body += 'See the failed job log for details.\n';
+            }
+            body += '\nFix the issues above and push again — the check reruns automatically.\n';
+            body += '\nLocal reproduction: `python3 tools/build-catalog.py --check`\n';
+            await github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body,
+            });

CLAUDE.md

@@ -85,3 +85,82 @@ Public documentation lives in the GitHub wiki at https://github.com/awizemann/sc
 ## Hermes Version
 
 Targets Hermes v0.9.0 (v2026.4.13). Log lines may carry an optional `[session_id]` tag between the level and logger name — `HermesLogService.parseLine` treats the session tag as an optional capture group, so older untagged lines still parse.
+
+## Project Templates
+
+Scarf ships a `.scarftemplate` format (v1 as of 2.2.0) for sharing pre-packaged projects across users and machines. A bundle is a zip containing:
+
+- `template.json` — manifest (id, name, version, `contents` claim)
+- `README.md` — shown in the install preview sheet
+- `AGENTS.md` — required; the [Linux Foundation cross-agent instructions standard](https://agents.md/) — every template is agent-portable out of the box
+- `dashboard.json` — copied to `<project>/.scarf/dashboard.json`
+- `instructions/…` — optional per-agent shims (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`)
+- `skills/<name>/…` — optional; installed to `~/.hermes/skills/templates/<slug>/` (namespaced so uninstall is `rm -rf` on one folder)
+- `cron/jobs.json` — optional; registered via `hermes cron create` with a `[tmpl:<id>] …` name prefix and immediately paused
+- `memory/append.md` — optional; appended to `~/.hermes/memories/MEMORY.md` between `<!-- scarf-template:<id>:begin/end -->` markers
+
+Key services: [ProjectTemplateService.swift](scarf/scarf/Core/Services/ProjectTemplateService.swift) (inspect + validate + plan), [ProjectTemplateInstaller.swift](scarf/scarf/Core/Services/ProjectTemplateInstaller.swift) (execute a plan), [ProjectTemplateExporter.swift](scarf/scarf/Core/Services/ProjectTemplateExporter.swift) (build a bundle from a project), [ProjectTemplateUninstaller.swift](scarf/scarf/Core/Services/ProjectTemplateUninstaller.swift) (reverse an install using the lock file). UI in [Features/Templates/](scarf/scarf/Features/Templates/). The `scarf://install?url=<https URL>` deep link + `file://` URLs for `.scarftemplate` files are handled by [TemplateURLRouter.swift](scarf/scarf/Core/Services/TemplateURLRouter.swift) and `onOpenURL` in `scarfApp.swift`. A `<project>/.scarf/template.lock.json` uninstall manifest is written after every install and drives the uninstall flow.
+
+**Uninstall semantics:** driven by the lock file. Only files listed in `lock.projectFiles` are removed from the project dir; user-added files (e.g. a `sites.txt` created on first run) are preserved. If every file in the dir was installed by the template, the dir is removed too; otherwise the dir stays with just the user's files. Skills namespace is always removed wholesale (it's isolated). Cron jobs are removed via `hermes cron remove <id>` after resolving each lock-recorded name. Memory block is stripped between the `begin`/`end` markers, leaving the rest of MEMORY.md intact. No "undo" — uninstall is destructive; to re-install, run the install flow again. Uninstall UI lives on the project-list context menu and the dashboard header (only shown when the selected project has a lock file).
+
+**Never** let a template write to `config.yaml`, `auth.json`, sessions, or any credential path — the v1 installer refuses. If you extend the format, treat the preview sheet as load-bearing: the user's only trust boundary is that the sheet is honest about everything that's about to be written.
+
+### Template configuration (v2.3, schemaVersion 2)
+
+Templates can declare a typed configuration schema in `template.json`'s new `config` block. The installer renders a **Configure** step between the parent-directory pick and the preview sheet; values land at `<project>/.scarf/config.json` (non-secret) and in the login Keychain (secret). A post-install **Configuration** button on the dashboard header (shown when `<project>/.scarf/manifest.json` exists) opens the same form pre-filled for editing.
+
+Manifest shape:
+
+```json
+{
+  "schemaVersion": 2,
+  "contents": { "dashboard": true, "agentsMd": true, "config": 2 },
+  "config": {
+    "schema": [
+      {"key": "site_url", "type": "string", "label": "Site URL", "required": true},
+      {"key": "api_token", "type": "secret", "label": "API Token", "required": true}
+    ],
+    "modelRecommendation": {
+      "preferred": "claude-sonnet-4.5",
+      "rationale": "Tool-heavy workload — reasoning helps."
+    }
+  }
+}
+```
+
+Supported field types: `string`, `text`, `number`, `bool`, `enum` (with `options: [{value, label}]`), `list` (itemType `"string"` only in v1), `secret`. Type-specific constraints (`pattern`, `min`/`max`, `minLength`/`maxLength`, `minItems`/`maxItems`) are optional. `secret` fields **must not** declare a `default` — the validator refuses.
+
+Key services: [TemplateConfig.swift](scarf/scarf/Core/Models/TemplateConfig.swift) (schema + value models + Keychain ref helpers), [ProjectConfigKeychain.swift](scarf/scarf/Core/Services/ProjectConfigKeychain.swift) (thin `SecItemAdd`/`Copy`/`Delete` wrapper; the only Keychain user in Scarf today), [ProjectConfigService.swift](scarf/scarf/Core/Services/ProjectConfigService.swift) (load/save config.json, resolve secrets, cache manifest, validate schema + values). UI in [Features/Templates/ViewModels/TemplateConfigViewModel.swift](scarf/scarf/Features/Templates/ViewModels/TemplateConfigViewModel.swift) + [Features/Templates/Views/TemplateConfigSheet.swift](scarf/scarf/Features/Templates/Views/TemplateConfigSheet.swift).
+
+**Secret storage.** Keychain service name is `com.scarf.template.<slug>`, account is `<fieldKey>:<project-path-hash-short>`. The path-hash suffix means two installs of the same template in different dirs don't collide on Keychain entries. Values in `config.json` are `"keychain://service/account"` URIs — never plaintext. The bytes hit the Keychain only on form commit, so cancelling never leaves orphan entries.
+
+**Uninstall.** `TemplateLock` v2 gains `config_keychain_items` and `config_fields` arrays. The uninstaller iterates each URI through `SecItemDelete` before removing the lock file. Absent items (user hand-cleaned) are no-ops.
+
+**Exporter.** Carries the *schema* from `<project>/.scarf/manifest.json` through into exported bundles, never values. Exporting never leaks anyone's secrets. `schemaVersion` bumps to 2 only when a schema is forwarded; schema-less exports stay at 1.
+
+**Catalog site.** [tools/build-catalog.py](tools/build-catalog.py) mirrors the Swift schema validator. Each v2 template's `template.json` is copied into `.gh-pages-worktree/templates/<slug>/manifest.json` and the site's `widgets.js` calls `ScarfWidgets.renderConfigSchema` to display the schema on the detail page (display-only — the form lives in-app).
+
+**Schema is Swift-primary.** If `TemplateConfigField.FieldType` gains a new case, update in order: `TemplateConfig.swift` (model + validation), `tools/build-catalog.py` (`SUPPORTED_CONFIG_FIELD_TYPES` + type-specific rules), `widgets.js` (`summariseConstraint`), `TemplateConfigSheet.swift` (new control subview), tests on both sides. Schema drift between validator + installer is the kind of bug users only notice after shipping.
+
+## Template Catalog
+
+Shipped community templates live at `templates/<author>/<name>/` (one level down — `templates/CONTRIBUTING.md` explains the submission flow for authors). The catalog site is generated from this directory and served at `awizemann.github.io/scarf/templates/` alongside the Sparkle appcast — the two coexist on the `gh-pages` branch but touch completely disjoint paths.
+
+Pipeline:
+
+- **Validator + regenerator:** [tools/build-catalog.py](tools/build-catalog.py) is stdlib-only Python (3.9+). It walks `templates/*/*/`, validates every `.scarftemplate` against its manifest claim (mirrors the Swift `ProjectTemplateService.verifyClaims` invariants), enforces a 5 MB bundle-size cap, scans for high-confidence secret patterns, checks `staging/` matches the built bundle byte-for-byte, and emits `templates/catalog.json`. Tested by [tools/test_build_catalog.py](tools/test_build_catalog.py) — 16 tests covering every validation path.
+- **Wrapper:** [scripts/catalog.sh](scripts/catalog.sh) mirrors the `scripts/wiki.sh` shape with `check / build / preview / serve / publish` subcommands. `publish` runs a second-pass secret-scan against the rendered site before committing + pushing `gh-pages`.
+- **Site source:** `site/index.html.tmpl` + `site/template.html.tmpl` are `{{TOKEN}}`-substitution templates. `site/widgets.js` (~300 lines of vanilla JS) is the dogfood — renders a `ProjectDashboard` JSON into HTML using the same widget vocabulary the Swift app uses, so each template's detail page shows a live preview of its post-install dashboard.
+- **Install-URL hosting:** raw-served from `main` at `https://raw.githubusercontent.com/awizemann/scarf/main/templates/<author>/<name>/<name>.scarftemplate`. No per-template Releases ceremony.
+- **CI gate:** [.github/workflows/validate-template-pr.yml](.github/workflows/validate-template-pr.yml) runs the Python validator + its own test suite on every PR that touches `templates/`, the validator, or its tests. Failures post a comment on the PR with the last 3 KB of the validator log.
+
+Maintainer workflow on merge to main:
+
+```bash
+./scripts/catalog.sh build       # regenerate templates/catalog.json + .gh-pages-worktree/templates/
+./scripts/catalog.sh publish     # secret-scan rendered output + commit + push gh-pages
+```
+
+Same cadence as `scripts/release.sh` (manual, auditable, no auto-deploy). Runs stay isolated: release.sh only touches `appcast.xml` on gh-pages; catalog.sh only touches `templates/` on gh-pages. Never push catalog output on a release cadence or vice versa.
+
+**Schema is Swift-primary.** When `ProjectDashboardWidget.type` gains a new case or `ProjectTemplateManifest` adds a field, update Swift first, then mirror into `tools/build-catalog.py` (`SUPPORTED_WIDGET_TYPES`, `_validate_manifest`, `_validate_contents_claim`) so the web validator stays honest. The Python test suite's real-bundle test catches drift on the example template but not on the full widget vocabulary — add a synthetic fixture to `test_build_catalog.py` for any new widget type.

CONTRIBUTING.md

@@ -37,6 +37,23 @@ Rules:
 
 Public docs live in the [GitHub wiki](https://github.com/awizemann/scarf/wiki). Small fixes (typos, clarifications) can be made via the "Edit" button on any wiki page — you need push access to the main repo. For larger changes, clone the wiki locally (`git clone git@github.com:awizemann/scarf.wiki.git`) or open an issue describing the proposed change.
 
+## Adding a Language
+
+Scarf ships with English + Simplified Chinese, German, French, Spanish, Japanese, and Brazilian Portuguese. To add another locale (or improve an existing one):
+
+1. **Fork** the repo and create a branch.
+2. **Add the locale to `knownRegions`** in `scarf/scarf.xcodeproj/project.pbxproj` — follow the existing list (e.g. add `it` after `"pt-BR"`).
+3. **Drop a new JSON file at `tools/translations/<locale>.json`** — copy an existing one (say `tools/translations/es.json`) as a starting point. Each entry maps the English source string to your translation. Keys you omit fall back to English at runtime — do that for proper nouns (Scarf, Hermes, Anthropic, OAuth, SSH, …) and for anything technical that shouldn't translate.
+4. **Preserve format specifiers exactly**: `%@`, `%lld`, `%d`, positional `%1$@` / `%2$lld`, etc. If word order needs to change in your language, use positional forms (`%1$@ … %2$@`).
+5. **Add your locale to `tools/merge-translations.py`'s `LOCALES` list** and run `python3 tools/merge-translations.py` — this writes your translations into `scarf/scarf/Localizable.xcstrings`.
+6. **Translate `scarf/scarf/InfoPlist.xcstrings`** (the macOS microphone-permission prompt) for your locale. Add a new `stringUnit` under `localizations`.
+7. **Build** (`xcodebuild -project scarf/scarf.xcodeproj -scheme scarf build`) and **sanity-check in Xcode**: Scheme → Run → App Language → your locale. Walk the main views (Dashboard, Chat, Settings) and look for clipping or obvious leaks.
+8. **Open a PR** including the new JSON file, the updated catalog, and the pbxproj / script changes. Mention which routes you spot-checked.
+
+AI translation is fine for the first pass — it's how the initial six locales landed. Native-speaker review improves quality and is always welcome, either as a follow-up PR or as review comments on the initial one.
+
+See [scarf/docs/I18N.md](scarf/docs/I18N.md) for deeper context on the String Catalog setup and which strings are intentionally kept verbatim.
+
 ## Reporting Issues
 
 Open an issue with:

README.md

@@ -13,18 +13,40 @@
   <img src="https://img.shields.io/badge/macOS-14.6+%20Sonoma-blue" alt="macOS">
   <img src="https://img.shields.io/badge/Swift-6-orange" alt="Swift">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+  <br>
+  <em>Available in English, 简体中文, Deutsch, Français, Español, 日本語, and Português (Brasil).</em>
   <br><br>
   <a href="https://www.buymeacoffee.com/awizemann"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me a Coffee" height="28"></a>
 </p>
 
-## What's New in 2.0
+## What's New in 2.2
+
+- **Project Templates** — Scarf projects can now travel. Package a project's dashboard, agent instructions, skills, cron jobs, and a typed configuration schema into a `.scarftemplate` bundle, hand it to anyone, and they install it in one click. Every bundle ships with a cross-agent `AGENTS.md` ([agents.md](https://agents.md/) standard) so the instructions work in Claude Code, Cursor, Codex, Aider, and the 20+ other agents that read it natively. Browser-based one-click install via `scarf://install?url=…` deep links. Export / Install from File / Install from URL live under the new **Templates** menu in the Projects toolbar.
+- **Typed configuration with Keychain-backed secrets** — Templates declare a schema with seven field types (`string`, `text`, `number`, `bool`, `enum`, `list`, `secret`). A **Configure** step in the install flow renders the form, routes secrets to the macOS Keychain, and drops non-secret values into `<project>/.scarf/config.json`. A slider icon in the dashboard header opens the same form post-install for edits — rotate a token, change a site, toggle a feature, and the next cron run picks it up.
+- **Public template catalog** — [awizemann.github.io/scarf/templates/](https://awizemann.github.io/scarf/templates/) is a static catalog site generated from `templates/<author>/<name>/` in this repo. Each template has a detail page with a live dashboard preview, the schema rendered with constraint summaries, and a one-click install button. Community submissions go through a CI-enforced Python validator that mirrors the Swift-side invariants.
+- **Preview-before-apply** — Every install shows a preview sheet listing the exact project directory that will be created, every file inside it, every skill that will be namespaced, every cron job that will be registered (paused by default), every Keychain secret that will be written, and a live diff of any memory appendix. Markdown fields render inline. Nothing writes until you click Install.
+- **Site tab** — A dashboard with at least one `webview` widget gets a second tab next to Dashboard. The example `awizemann/site-status-checker` template uses this to render whatever URL you configured as your first watched site, updating on every cron run.
+- **Safe-by-design** — Skills install into `~/.hermes/skills/templates/<slug>/` so they never collide with your own. Cron jobs carry a `[tmpl:<id>]` tag and start paused. A `template.lock.json` records every file, cron job, Keychain ref, and memory block for one-click uninstall. Exports carry the configuration schema but never the user's values — safe on projects with live config. Templates **never** touch `config.yaml`, `auth.json`, sessions, or credentials.
+
+See the full [v2.2.0 release notes](https://github.com/awizemann/scarf/releases/tag/v2.2.0) and the [Project Templates wiki page](https://github.com/awizemann/scarf/wiki/Project-Templates).
+
+### Previously, in 2.1
+
+- **Seven languages** — Full UI translations for Simplified Chinese, German, French, Spanish, Japanese, and Brazilian Portuguese on top of English. Scarf respects the system language by default; override per-app via **System Settings → Language & Region → Apps → Scarf**. Contributor workflow for adding more locales is documented in [CONTRIBUTING.md → Adding a Language](CONTRIBUTING.md#adding-a-language).
+- **Locale-aware number formatting** — Currency, byte sizes, compact token counts (`15K`, `1.5M`), and day-of-week charts now follow the user's locale instead of POSIX / English defaults.
+- **Chat slash-command menu** — Type `/` in Rich Chat to browse every command the agent has advertised plus any user-defined `quick_commands:` from config.yaml. ↑/↓ to navigate, Tab/Enter to complete, Esc to dismiss.
+- **Chat polish** — Auto-scroll on send and on prompt completion, a non-blocking loading spinner during session reconnects, properly centered empty state, and the long-standing "session loads with whitespace" bug fixed (LazyVStack → VStack in the message list).
+
+See the full [v2.1.0 release notes](https://github.com/awizemann/scarf/releases/tag/v2.1.0).
+
+### Previously, in 2.0
 
 - **Multi-server** — Manage multiple Hermes installations (local + any number of remotes) from one app. Each window binds to one server; open them side-by-side.
 - **Remote Hermes over SSH** — Every feature that worked against your local `~/.hermes/` now works against a remote host. File I/O routes through `scp`/`sftp`; chat ACP runs over `ssh -T`; SQLite is served from atomic `.backup` snapshots pulled on file-watcher ticks.
 - **Chat UX overhaul** — No more white-screen flash on first message, no more scroll jumping into whitespace during streaming, failed prompts explain themselves instead of silently spinning forever.
 - **Correctness pass** — Fixed remote WAL error spam, stale-snapshot session resume, auto-resume of dead cron sessions, 230+ Swift 6 concurrency warnings.
 
-See the full [v2.0.0 release notes](https://github.com/awizemann/scarf/releases/tag/v2.0.0).
+See the [v2.0.0 release notes](https://github.com/awizemann/scarf/releases/tag/v2.0.0) for the full 2.0 series.
 
 ### Previously, in 1.6
 
@@ -376,6 +398,16 @@ Signing prerequisites (one-time):
 - `scarf-notary` keychain profile registered via `xcrun notarytool store-credentials`
 - Sparkle EdDSA private key in Keychain item `https://sparkle-project.org` (back this up — without it, shipped apps can never receive updates)
 
+## Template Catalog
+
+Community-contributed Scarf project templates live under [`templates/`](templates/) in this repo and are browsable at **[awizemann.github.io/scarf/templates/](https://awizemann.github.io/scarf/templates/)** with live dashboard previews and one-click `scarf://install?url=…` links.
+
+- **Install from the web** — click "Install with Scarf" on any template's detail page; the app takes over from there.
+- **Install from a local file** — Scarf → Projects → Templates → Install from File…, or double-click any `.scarftemplate` in Finder.
+- **Author a template** — see [`templates/CONTRIBUTING.md`](templates/CONTRIBUTING.md) for the full walkthrough. Fork, drop a template under `templates/<your-github-handle>/<your-name>/`, open a PR; CI validates the bundle automatically.
+
+The catalog's site is a static HTML + vanilla JS build generated by [`tools/build-catalog.py`](tools/build-catalog.py) and driven by [`scripts/catalog.sh`](scripts/catalog.sh) (check / build / preview / publish). Appcast and main landing page are independent — updating the catalog never disturbs Sparkle.
+
 ## Contributing
 
 Contributions are welcome. Please open an issue to discuss what you'd like to change before submitting a PR.
@@ -386,6 +418,8 @@ Contributions are welcome. Please open an issue to discuss what you'd like to ch
 4. Push to the branch (`git push origin feature/my-feature`)
 5. Open a Pull Request
 
+For template submissions, see [`templates/CONTRIBUTING.md`](templates/CONTRIBUTING.md) — same flow, with a catalog-specific checklist + automated CI validation.
+
 ## Support
 
 If you find Scarf useful, consider buying me a coffee.

releases/v2.1.0/RELEASE_NOTES.md

@@ -0,0 +1,52 @@
+## What's New in 2.1.0
+
+Scarf now speaks seven languages and has a proper slash-command menu in the chat. The language work closes [#13](https://github.com/awizemann/scarf/issues/13) and opens the door for community contributions of additional locales.
+
+### Multi-language support
+
+The UI is now fully translated to **Simplified Chinese, German, French, Spanish, Japanese, and Brazilian Portuguese** on top of the existing English. Scarf respects the system language by default; override per-app from **System Settings → Language & Region → Apps → Scarf**.
+
+- **644 source strings** catalogued. **583 translated per locale** — the remaining ~60 are deliberate fall-throughs to English: proper nouns (Scarf, Hermes, OAuth, MCP, SSH), brand names (Docker, Daytona, Singularity, BlueBubbles), format-only tokens (`%lld`, `·`, `•`), and config-literal placeholders (`my_server`, `npx`, `sk-…`).
+- **Locale-aware number and date formatting.** Previous builds hardcoded POSIX-style decimal separators (`$12.34`) and English unit names (`"MB"`, `"K"`, `"M"`). Currency now routes through `.formatted(.currency(code: "USD"))`, byte sizes through `.byteCount(style: .file)`, token counts through `.notation(.compactName)`, and the day-of-week chart through `Calendar.current.shortWeekdaySymbols` — so German users see `15,2 MB`, Japanese users see `15.5万 tokens`, and the activity heatmap starts on the locale's first weekday.
+- **Microphone permission prompt localized** — the system dialog that appears the first time you enable voice chat now reads in the user's language.
+
+#### How the translation work shipped
+
+Three stacked PRs to keep each piece independently reviewable, all AI-translated with the bar explicitly set low so native speakers can iterate:
+
+1. **[#22](https://github.com/awizemann/scarf/pull/22) — String Catalog infrastructure.** Added `Localizable.xcstrings` + `InfoPlist.xcstrings`, expanded `knownRegions` with the six new locales, and fixed the locale-aware number formatters mentioned above. No user-visible English-locale change; the groundwork only.
+2. **[#24](https://github.com/awizemann/scarf/pull/24) — Audit burn-down.** Swept the codebase for "silently un-localizable" patterns that look fine in Xcode's catalog but leak English at runtime: `Text(cond ? "A" : "B")` routes through the String overload instead of `LocalizedStringKey`, as do `Label(stringVar, systemImage:)`, `.help(stringVar)`, and composite format strings with translatable text suffixes. ~40 sites refactored, covering Chat voice/TTS toggles, Logs pickers, Insights period + day names, MCPServer test result, Profiles, SignalSetup, QuickCommands, ConnectionStatusPill. Without this PR the translations would have landed but ~40 visible strings would still have rendered in English.
+3. **[#25](https://github.com/awizemann/scarf/pull/25) — Translations + contributor path.** The six locale JSONs + a 90-line merge script + a "Adding a Language" section in `CONTRIBUTING.md`. The sidebar and Settings tab bar fix also shipped here after smoke-testing revealed they were still missed — `Label(section.rawValue, …)` goes to the String overload just like the audit cases.
+
+#### Contributing a new language
+
+Per-locale source of truth lives in [`tools/translations/<locale>.json`](https://github.com/awizemann/scarf/tree/main/tools/translations). Each entry is a plain `{ "English": "Translation" }` map — keys you omit fall through to English at runtime. Workflow is: fork, drop a JSON, run `python3 tools/merge-translations.py`, open a PR. The full bar is documented in [CONTRIBUTING.md → Adding a Language](https://github.com/awizemann/scarf/blob/main/CONTRIBUTING.md#adding-a-language).
+
+Native-speaker review of the initial six locales is welcome — AI translation gets us most of the way, but idiom and tone are better with someone who actually uses the language. Post a PR against the relevant `<locale>.json` and it'll land as a follow-up.
+
+### Chat slash-command menu
+
+Type `/` in Rich Chat and a floating menu appears above the input with every command the connected agent has advertised via ACP's `available_commands_update`, plus any user-defined `quick_commands:` from `~/.hermes/config.yaml`. ↑/↓ to navigate, Tab or Enter to complete, Esc to dismiss. Commands with argument hints (e.g. `/compress <topic>`) insert a trailing space so you can start typing the argument immediately.
+
+The filter uses pure-prefix match and re-renders on every query — the old menu had a description-fallback filter and a cached child view that together pinned `/help` on-screen regardless of what you typed. The dedicated `/compress` button is hidden once the menu has more than one command; it only surfaces when `/compress` is the single advertised slash command, preserving the v2.0 one-click compression flow for that case.
+
+### Chat UX polish
+
+- **Auto-scroll on send and on completion.** `.defaultScrollAnchor(.bottom)` handles slow streaming fine, but rapid slash-command responses (common once the menu lands) outran the anchor and left the reply off-screen. Now the list explicitly scrolls to the latest message when you submit and again when the prompt finishes.
+- **Loading state.** `ChatViewModel.isPreparingSession` is true during Starting / Creating / Loading / Reconnecting. While true, the message list swaps its empty-state placeholder for a spinner — non-blocking, just a view inside the ScrollView.
+- **Empty-state centering.** The "Start a new session or resume an existing one" placeholder was positioned with a fixed `.padding(.vertical, 80)` that looked wrong at extreme window sizes. Replaced with Spacers inside `.containerRelativeFrame(.vertical)` so it sits in the true vertical center of the chat pane.
+- **Session-load whitespace bug.** Opening a session used to render a blank viewport you'd have to scroll up from — the fix was `LazyVStack` → `VStack` in `RichChatMessageList`. LazyVStack's estimated row heights were fooling `.defaultScrollAnchor(.bottom)` into overshooting real content; VStack measures every row upfront so the anchor has real heights to work with.
+
+### Under the hood
+
+- **String Catalog build pipeline.** `SWIFT_EMIT_LOC_STRINGS` + `STRING_CATALOG_GENERATE_SYMBOLS` are enabled; keys extract automatically on IDE build. Headless builds use `xcrun xcstringstool sync` to merge the per-source `.stringsdata` files into the catalog (wrapped by [`tools/merge-translations.py`](https://github.com/awizemann/scarf/blob/main/tools/merge-translations.py) when applying JSON translations).
+- **New docs.** [`scarf/docs/I18N.md`](https://github.com/awizemann/scarf/blob/main/scarf/docs/I18N.md) covers the catalog setup, the patterns that silently bypass localization (and their fixes), and which strings are intentionally kept verbatim. Anyone adding UI copy should read the "Guardrails when writing new UI code" section to avoid re-introducing the leaks #24 cleaned up.
+
+### Migrating from 2.0.x
+
+Sparkle will offer the update automatically. No config migration needed. The first launch after update picks up the system locale — if you want English even on a non-English macOS, set **System Settings → Language & Region → Apps → Scarf → English**.
+
+### Thanks
+
+- [Onion3](https://github.com/Onion3) for filing [#13](https://github.com/awizemann/scarf/issues/13) back in April. The single-locale ask turned into a six-locale rollout.
+- Future translators: if you spot a weird AI translation in your language, open a PR against `tools/translations/<locale>.json`. The bar is explicitly low — we'd rather have a 95%-correct translation shipped and iterated on than hold everything for perfection.

releases/v2.2.0/RELEASE_NOTES.md

@@ -0,0 +1,94 @@
+## What's New in 2.2.0
+
+Scarf projects can now travel. This release introduces **Project Templates** — a shareable `.scarftemplate` bundle format that packages a project's dashboard, agent instructions, skills, cron jobs, and a typed configuration schema into a single file anyone can install with one click. Bundles are agent-portable by design: every template ships with a cross-agent [`AGENTS.md`](https://agents.md/) so the instructions work natively in Claude Code, Cursor, Codex, Aider, Jules, Copilot, Zed, and every other agent that reads the Linux Foundation standard.
+
+This is also the first release to ship a public **template catalog website** — a static site generated from `templates/<author>/<name>/` in this repo, previewed at [awizemann.github.io/scarf/templates/](https://awizemann.github.io/scarf/templates/), with a CI-enforced validator for community submissions.
+
+### Project Templates
+
+- **Bundle format: `.scarftemplate`.** A zip carrying a `template.json` manifest, the project's dashboard, a required `AGENTS.md` (the [Linux Foundation cross-agent instructions standard](https://agents.md/) — reads natively in Claude Code, Cursor, Codex, Aider, Jules, Copilot, Zed, and more), a README shown in the installer, optional per-agent instruction shims (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`), optional namespaced skills, optional cron job definitions, and an optional memory appendix.
+- **Install preview sheet.** Before anything touches disk, Scarf shows you the exact project directory that will be created, every file inside it, every skill that will be namespaced under `~/.hermes/skills/templates/<slug>/`, every cron job that will be registered (always paused — you enable each one manually), and a live diff of the memory appendix against your existing `MEMORY.md`. Markdown fields — the README, field descriptions, cron prompts — render inline. The manifest's content claim is cross-checked against the actual zip entries so a bundle can't hide files from the preview.
+- **`scarf://install?url=…` deep links.** Register Scarf as the handler for the `scarf` URL scheme so a future catalog site can link one-click installs straight into the app. Only `https://` payloads are accepted; `file://`, `javascript:`, and `http://` are refused on principle. A 50 MB size cap keeps a malicious link from exhausting disk. The URL never auto-installs — the preview sheet is always user-confirmed.
+- **Install-time token substitution.** Template authors use `{{PROJECT_DIR}}`, `{{TEMPLATE_ID}}`, and `{{TEMPLATE_SLUG}}` placeholders in cron prompts; the installer resolves them to absolute paths at install time so the registered cron job works regardless of where Hermes sets CWD.
+- **Export any project as a template.** Select a project, open the new Templates menu in the Projects toolbar, fill in a handful of fields (id, name, version, description, optional author + category + tags), tick the skills and cron jobs you want to include, optionally drop in a memory snippet, and save. The exporter carries the authored configuration schema forward but **never** the user's values — exports are safe on projects with live config.
+- **No-overwrite, reversible by design.** Installed templates drop a `<project>/.scarf/template.lock.json` recording exactly what they wrote — every project file, skill path, cron job name, memory block id, and Keychain reference. Installing the same template id twice is refused at the preview step so you don't accidentally double-append to `MEMORY.md`.
+- **Safe globals.** Skills install to `~/.hermes/skills/templates/<slug>/<skill-name>/` so they never collide with your own skills. Cron jobs are prefixed with `[tmpl:<id>]` and start paused. The installer **never** touches `~/.hermes/config.yaml`, `auth.json`, sessions, or any credential-bearing path.
+
+### Template Configuration (schemaVersion 2)
+
+Templates can now declare a typed configuration schema that drives a form step during install — no more "edit a `sites.txt` file to get started."
+
+- **Typed field vocabulary.** Seven field types: `string`, `text` (multiline), `number` (with `min`/`max`), `bool`, `enum` (with `{value, label}` options), `list` (of strings, with `minItems`/`maxItems`), and `secret` (routed to the macOS Keychain). Constraints per type — `pattern` for regex, `minLength`/`maxLength` for text, etc. — are enforced at install and at edit time.
+- **Configure step in the install flow.** If the template declares a schema, a **Configure** screen is inserted between "pick parent directory" and the preview sheet. Non-secret values land in `<project>/.scarf/config.json`; secrets land in the macOS Keychain with a service name of `com.scarf.template.<slug>` and an account keyed to the project-directory hash (so two installs of the same template in different dirs don't collide on Keychain entries).
+- **Post-install Configuration editor.** A slider icon in the dashboard header opens the same form pre-filled with the current values. Change a site, rotate a token, toggle a feature — the cron job picks up the new values on its next run. Secrets are never echoed back ("Saved in Keychain — leave empty to keep the stored value").
+- **Model recommendations.** Templates can suggest a preferred model (`claude-sonnet-4.5`, `claude-haiku-4`, `gpt-4.1`, etc.) with a rationale. Scarf surfaces the recommendation in the configure sheet without auto-switching your active model — always your call.
+- **Secrets are tracked in the lock file.** Uninstalling a template runs `SecItemDelete` on every Keychain ref recorded at install, so a full clean-up leaves nothing behind. Absent entries (user already cleaned them) are no-ops.
+
+### Template Catalog
+
+A Sparkle-style pipeline for community-contributed templates, living on the same `gh-pages` branch as the auto-update feed.
+
+- **Static site.** [awizemann.github.io/scarf/templates/](https://awizemann.github.io/scarf/templates/) — generated from every `templates/<author>/<name>/` directory. Each template gets a detail page showing the README, a live preview of the post-install dashboard, and the configuration schema rendered with human-readable constraint summaries. One-click install via the `scarf://install?url=…` button.
+- **Stdlib-only Python validator.** `tools/build-catalog.py` is a no-external-dependencies Python script that mirrors the Swift-side schema and validation invariants (supported widget types, supported field types, `contents` claim verification, secret-with-default rejection, bundle-size cap, high-confidence secret patterns). Run it locally with `./scripts/catalog.sh check` before submitting a PR.
+- **CI gate on PRs.** [`.github/workflows/validate-template-pr.yml`](https://github.com/awizemann/scarf/blob/main/.github/workflows/validate-template-pr.yml) runs the validator + its 24-test suite on every PR touching `templates/`, the validator itself, or its tests. Failing PRs get an inline comment with the last 3 KB of the validator output; passing PRs get a tailored checklist naming the specific template directory being changed.
+- **Install-URL hosting.** 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.
+- **Dogfood: the site uses Scarf's dashboard format.** `site/widgets.js` is ~300 lines of vanilla JS that renders a `ProjectDashboard` JSON using the same widget vocabulary the app uses, so each detail page's "live preview" is the actual dashboard the user will get.
+
+### Example template: `awizemann/site-status-checker`
+
+Ships as the first catalog entry and exercises every v2.2 surface. [See it in the catalog →](https://awizemann.github.io/scarf/templates/awizemann-site-status-checker/)
+
+- Configure step asks for a list of URLs and a per-URL timeout.
+- A paused cron job runs daily at 09:00 (editable from the Cron sidebar), does HTTP GETs with 3-redirect follow, writes a timestamped results table to `status-log.md`, updates the dashboard's Sites Up / Sites Down / Last Checked stat widgets plus the Watched Sites list, and rewrites the Site tab's webview URL to the first configured site.
+- Works in any agent — the `AGENTS.md` is the single source of truth; no per-agent shim needed.
+
+### Site tab
+
+A dashboard with at least one `webview` widget now exposes a **Site** tab next to Dashboard. Useful for templates that watch something renderable (a site, a preview endpoint, a Grafana panel). The `site-status-checker` example rewrites the webview URL to the first configured site on every cron run, so the tab stays in sync with live config.
+
+### Using templates
+
+- **Install from file:** Projects → Templates → *Install from File…*, pick a `.scarftemplate` from disk.
+- **Install from URL:** Projects → Templates → *Install from URL…*, paste an https URL.
+- **Install from the web:** click any `scarf://install?url=…` link in a browser.
+- **Export:** select a project → Projects → Templates → *Export "&lt;name&gt;" as Template…*, fill the form, save.
+- **Edit config post-install:** slider icon in the dashboard header.
+- **Uninstall:** right-click the project in the sidebar → *Uninstall Template (remove installed files)…*, or click the uninstall icon in the dashboard header. The preview sheet lists every file, cron job, Keychain secret, and memory block that will be removed, plus every user-created file that will be preserved.
+
+### UX clarifications
+
+- **Remove from List vs. Uninstall Template.** Sidebar context-menu labels clarified so you can see at a glance whether a click is destructive. *Remove from List (keep files)…* is registry-only — nothing on disk is touched, cron jobs stay, Keychain secrets stay. A confirmation dialog spells this out before the click lands. *Uninstall Template (remove installed files)…* is the full, lock-driven cleanup.
+- **Post-uninstall "folder kept" banner.** When the uninstaller preserves the project directory because the cron wrote a `status-log.md` (or the user dropped files in there), the success view now explicitly lists the preserved paths with a pointer to delete the folder from Finder if desired.
+- **Run Now no longer blocks on agent runs.** The Cron sidebar's Run Now button used to show a "Run failed" toast whenever an agent job ran longer than 60 s — even when the job was finishing correctly in the background. Run Now now shows "Agent started — dashboard will update when it finishes" immediately and the dashboard watcher picks up the completed state when it lands (timeout bumped to 300 s for the catch-stuck-process case).
+
+### Uninstall
+
+- **One-click uninstall** driven by `template.lock.json`. The preview sheet lists every file, cron job, Keychain ref, and memory block that will be removed, and every user-created file that will be preserved.
+- **User content is never removed.** Files you (or the agent) added to the project dir after install — like a `sites.txt` or `status-log.md` — are detected and listed as "keep" in the preview. The project directory itself is removed only if nothing user-owned is left inside.
+- **Clean global state.** The isolated `~/.hermes/skills/templates/<slug>/` namespace is removed wholesale. Tagged cron jobs are removed via `hermes cron remove`. Every recorded Keychain ref is cleared via `SecItemDelete`. The memory block between the `<!-- scarf-template:<id>:begin/end -->` markers is stripped, leaving the rest of MEMORY.md intact. The project registry entry is removed last.
+- **No undo.** Uninstall is destructive — to reinstall, run the install flow again.
+
+### Under the hood
+
+- New models in `Core/Models/ProjectTemplate.swift` (manifest, inspection, install plan, lock file v2) and `Core/Models/TemplateConfig.swift` (schema + typed values + Keychain ref model).
+- `Core/Services/ProjectTemplateService.swift` unzips, parses, and validates; `ProjectTemplateInstaller.swift` executes the plan with preflight + fail-fast semantics; `ProjectTemplateUninstaller.swift` reverses an install driven by the lock file; `ProjectTemplateExporter.swift` builds bundles from a live project + selections.
+- `Core/Services/ProjectConfigService.swift` owns load/save/validation of `<project>/.scarf/config.json` + secret resolution; `Core/Services/ProjectConfigKeychain.swift` is the thin `SecItemAdd`/`Copy`/`Delete` wrapper (the only Keychain consumer in Scarf today).
+- `Core/Services/TemplateURLRouter.swift` is the process-wide landing pad for `scarf://` URLs so a cold-launch browser click still reaches the install sheet.
+- New Swift Testing suites covering 57 tests across the service / installer / uninstaller / exporter / config / Keychain / URL-router paths.
+- New Python validator (`tools/build-catalog.py`) + test suite (`tools/test_build_catalog.py`, 24 tests) mirrors the Swift invariants for the CI gate and the site generator. Schema is Swift-primary — additions go to Swift first, Python mirrors.
+- `scripts/catalog.sh` wraps the validator with `check / build / preview / serve / publish` subcommands that parallel the `scripts/release.sh` shape.
+
+### Migrating from 2.1.x
+
+Sparkle will offer the update automatically. No config migration needed. Existing projects are untouched — templates are additive. If you had a v2.2.0-dev install of the earlier `project-templates` branch, uninstall and reinstall any previously-installed templates to pick up the schema-version-2 lock file.
+
+### Documentation
+
+- [Project Templates wiki page](https://github.com/awizemann/scarf/wiki/Project-Templates) — installing, exporting, configuring, authoring, uninstalling.
+- [Catalog site](https://awizemann.github.io/scarf/templates/) — the public catalog with live dashboard previews.
+- [`templates/CONTRIBUTING.md`](https://github.com/awizemann/scarf/blob/main/templates/CONTRIBUTING.md) — how to submit a template via PR.
+- [Architecture notes in root `CLAUDE.md`](https://github.com/awizemann/scarf/blob/main/CLAUDE.md#project-templates) — service-layer map, Keychain scheme, schema-drift discipline.
+
+### Thanks
+
+Thanks to everyone who tested drafts of the install flow, caught the "Run Now blocks on agent" bug, and pushed on the Remove-vs-Uninstall UX until it was clear. A 2.3 follow-up will extend the catalog validator to enforce per-field-type constraints at PR-time (currently enforced on install but not at submission).

releases/v2.2.1/RELEASE_NOTES.md

@@ -0,0 +1,38 @@
+## What's New in 2.2.1
+
+A patch release covering Template Configuration rendering fixes reported against v2.2.0, plus a new catalog template that packages a Hermes skill for scaffolding new Scarf projects.
+
+### Configuration sheet — no more clipping
+
+Two independent rendering fixes to the post-install Configuration editor and the install-flow Configure step:
+
+- **Enum fields with long option labels.** An enum with three or four options whose labels exceeded ~20 characters — e.g. a Claude-model picker with labels like *"Claude Opus 4 (Recommended - Most Capable)"* — rendered as a segmented picker that sized to the intrinsic width of all labels concatenated. On macOS, `.pickerStyle(.segmented)` refuses to respect offered width, refuses to wrap, refuses to truncate. The result was a ~650pt picker that overflowed the sheet's 560pt viewport and clipped the entire form on both sides. Enum fields now always render as a dropdown Menu picker, which surfaces long labels in the popup list and respects the parent's offered width regardless of option count or label length.
+- **Descriptions with unbreakable content.** Field descriptions rendered via inline AttributedString markdown can contain tokens SwiftUI's `Text` refuses to break mid-token (raw URLs, long paths). Added `.frame(maxWidth: .infinity, alignment: .leading)` on the sheet's inner VStack and on each field row as a secondary constraint, so description text wraps at whitespace boundaries instead of expanding the sheet width. Applied the same modifier to `TemplateInstallSheet`'s main preview VStack for symmetry — installs with README blocks or cron prompts containing long URLs now wrap cleanly too.
+
+### New catalog entry — `awizemann/template-author`
+
+A `.scarftemplate` whose only content is a Hermes skill (`scarf-template-author`) plus a minimal dashboard that points users at it. Installing the template drops the skill at `~/.hermes/skills/templates/awizemann-template-author/scarf-template-author/SKILL.md`, discoverable by Claude Code, Cursor, Codex, Aider, and every other agent that reads the standard `~/.hermes/skills/` directory.
+
+The skill teaches agents how to scaffold a new Scarf-compatible project through a short interview — purpose, data source, cadence, widgets, config, secrets — then write `<project>/.scarf/dashboard.json`, `<project>/.scarf/manifest.json`, `<project>/AGENTS.md`, and `<project>/README.md`. Scaffolded projects are usable locally and cleanly exportable as `.scarftemplate` bundles via Scarf's Export flow later. [Catalog detail page →](https://awizemann.github.io/scarf/templates/awizemann-template-author/)
+
+v1 is fully conversational / blank-slate. Pre-baked archetypes (monitor, dev-dashboard, personal-log) are deferred to a future release pending real usage data.
+
+### Authoring guidance — SKILL.md
+
+The `scarf-template-author` skill now tells scaffolding agents to prefer markdown link syntax (`[label](https://…)`) over raw URLs in schema field descriptions. Raw URLs work now (v2.2.1's description wrap fix above handles them gracefully), but `[Anthropic console](https://console.anthropic.com)` reads cleaner in the form than a dumped URL. Same rule extended to long paths or other unbreakable strings — wrap in inline code if they have to appear verbatim, prefer markdown links otherwise.
+
+### Under the hood
+
+- **`scripts/catalog.sh publish` fix.** The pre-flight `need_ghpages` check tested `[[ -d "$GHPAGES_DIR/.git" ]]` — "is `.git` a directory?" — which is true for a regular clone but false for a `git worktree add` worktree (where `.git` is a pointer file). `release.sh` creates and leaves the gh-pages worktree around, so after any release the subsequent catalog-publish call was rejected with a misleading "run `git worktree add`" error on a worktree that was already there and valid. Switched to `-e` (exists, either file or directory). Unblocks publishing the catalog immediately after a release.
+
+### Migrating from 2.2.0
+
+Sparkle will offer the update automatically. No config migration needed. Existing template installs are untouched.
+
+If you've already installed `awizemann/template-author` from a pre-release build, no action needed — the catalog and bundle content are forward-compatible.
+
+### Documentation
+
+- [Project Templates wiki page](https://github.com/awizemann/scarf/wiki/Project-Templates) — installing, exporting, configuring, authoring, uninstalling.
+- [Catalog site](https://awizemann.github.io/scarf/templates/) — two templates live: `awizemann/site-status-checker` and `awizemann/template-author`.
+- [`templates/CONTRIBUTING.md`](https://github.com/awizemann/scarf/blob/main/templates/CONTRIBUTING.md) — how to submit a template via PR.

scarf/docs/I18N.md

@@ -0,0 +1,84 @@
+# Internationalization (i18n)
+
+Scarf uses Apple's modern **String Catalog** workflow. Source strings are auto-extracted from `Text("…")` and `String(localized: …)` literals into [`scarf/scarf/Localizable.xcstrings`](../scarf/Localizable.xcstrings) at build time (when built in Xcode.app; `xcodebuild` alone emits per-source `.stringsdata` but does not merge back into the catalog). Info.plist keys are localized via [`scarf/scarf/InfoPlist.xcstrings`](../scarf/InfoPlist.xcstrings).
+
+## Languages
+
+| Locale | Status |
+|---|---|
+| `en` (English) | Base / source |
+| `zh-Hans` (Simplified Chinese) | AI-translated, native-speaker review welcome |
+| `de` (German) | AI-translated, native-speaker review welcome |
+| `fr` (French) | AI-translated, native-speaker review welcome |
+| `es` (Spanish) | AI-translated, native-speaker review welcome |
+| `ja` (Japanese) | AI-translated, native-speaker review welcome |
+| `pt-BR` (Portuguese, Brazil) | AI-translated, native-speaker review welcome |
+
+Canadian French users are served by base `fr`. `fr-CA` will be added only if a concrete Québec-specific bug is reported.
+
+### Translation workflow
+
+Source-of-truth per locale lives in `tools/translations/<locale>.json` — a flat `{ "English": "Translation" }` map. The merge step writes those into `scarf/scarf/Localizable.xcstrings` via:
+
+```bash
+python3 tools/merge-translations.py
+```
+
+Keys absent from a locale file fall back to English at runtime — this is deliberate for proper nouns (Scarf, Hermes, Anthropic, OAuth, SSH…) and format-only strings (`%lld`, `%@ → %@`, `•`). Re-running the merge is idempotent; iterate on a JSON and re-merge.
+
+Contributor path for new languages is documented in the repo root [CONTRIBUTING.md](../../CONTRIBUTING.md#adding-a-language).
+
+## Adding a new language
+
+1. Xcode → Project → Info → Localizations → `+` (add locale).
+2. Ensure the locale code is also listed in `knownRegions` of `scarf.xcodeproj/project.pbxproj`.
+3. Open `Localizable.xcstrings` in Xcode; the new locale appears as an empty column — translate or use Xcode's AI suggestions.
+4. Repeat for `InfoPlist.xcstrings` (microphone usage, etc.).
+5. Smoke-test via scheme language override (Edit Scheme → Run → App Language).
+
+## Adding translations (AI-first workflow)
+
+For the three supported non-English locales we use Xcode's built-in AI translation:
+
+1. Open `Localizable.xcstrings` in Xcode.
+2. Select untranslated rows for a locale → right-click → **Translate** (Xcode 26+ provides GPT-backed suggestions with context from the surrounding code comment).
+3. Review each suggestion before marking **Translated**.
+4. For terms that should NOT translate (proper nouns like *Scarf*, *Hermes*, *Anthropic*; env var names; file paths), wrap the source site in `Text(verbatim: "…")` so the key never hits the catalog.
+
+## Guardrails when writing new UI code
+
+`Text("literal")` auto-localizes. These patterns **silently leak English** and need explicit handling:
+
+| Pattern | Fix |
+|---|---|
+| `Text(someStringVar)` | `Text(LocalizedStringResource("key"))` or pass a `LocalizedStringKey` down the view tree |
+| `"Hello " + name` | `String(localized: "Hello \(name)")` |
+| `String(format: "$%.2f", cost)` | `cost.formatted(.currency(code: "USD").precision(.fractionLength(2)))` |
+| `String(format: "%.1f MB", size)` | `Int64(size).formatted(.byteCount(style: .file))` |
+| `String(format: "%.1fM", n)` | `n.formatted(.number.notation(.compactName))` |
+| Custom `DateFormatter` with fixed `dateFormat` | `date.formatted(.dateTime.month().day().year())` |
+| `.help(stringVar)` | Compute a `LocalizedStringKey` or use `.help(Text(…))` |
+| `Button(stringVar)` | `Button(LocalizedStringResource("key")) { … }` |
+
+Strings that are **user data** (session titles, memory file contents, log lines, shell commands shown in UI, file paths) should pass through without localization — this happens naturally when the value is a `String` variable, since those overloads skip the catalog.
+
+## Audit status
+
+Phase 1b (the `multi-language` PR) closed every tracked site from the original audit:
+
+- **Category A high-priority (ternary UI copy)** — converted to `Text`-ternary form so each branch routes through `LocalizedStringKey`.
+- **Category A medium-priority (enum `.rawValue` displays)** — each enum now exposes `displayName: LocalizedStringResource` and call sites use it. `LogEntry.LogLevel` (technical jargon) stays verbatim.
+- **Category A lower-priority (displayName passthroughs)** — wrapped with `Text(verbatim:)` for proper nouns / user data (`HermesToolPlatform`, `ServerRegistry.Entry`, `MCPServerPreset`). `MCPTransport.displayName` promoted to `LocalizedStringResource`.
+- **Category B (composite format strings)** — migrated to `Text("\(arg) suffix")` with `LocalizedStringKey` or to `.percent` / `.currency` FormatStyle.
+- **Category C (hard-coded day names)** — replaced with `Calendar.current.shortWeekdaySymbols`, re-indexed to match the existing Mon=0 data model.
+- **Category D (`.help(stringVar)` sites)** — `ConnectionStatusPill` now returns `Text` from its `labelText` / `tooltipText` properties.
+
+If you spot a new silently-un-localizable site during translation review, prefer the patterns in the table above over one-off workarounds.
+
+### Non-blocking (intentional verbatim)
+
+The following are correct as-is because they pass user data or machine-readable content through to the UI:
+
+- Session titles, message content, memory / skill / YAML file contents, log lines, shell commands, file paths, session IDs, model IDs, credential sources, URL strings.
+
+If we later need to badge these (e.g. "(empty)" placeholder), the badge itself becomes a localizable key while the data passthrough stays verbatim.

scarf/scarf.xcodeproj/project.pbxproj

@@ -214,6 +214,12 @@
 			knownRegions = (
 				en,
 				Base,
+				"zh-Hans",
+				de,
+				fr,
+				es,
+				ja,
+				"pt-BR",
 			);
 			mainGroup = 534959372F7B83B600BD31AD;
 			minimizedProjectReferenceProxies = 1;
@@ -300,6 +306,7 @@
 			buildSettings = {
 				ALWAYS_SEARCH_USER_PATHS = NO;
 				ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES;
+				CLANG_ANALYZER_LOCALIZABILITY_NONLOCALIZED = YES;
 				CLANG_ANALYZER_NONNULL = YES;
 				CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
 				CLANG_CXX_LANGUAGE_STANDARD = "gnu++20";
@@ -329,6 +336,7 @@
 				CLANG_WARN_UNREACHABLE_CODE = YES;
 				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
 				COPY_PHASE_STRIP = NO;
+				DEAD_CODE_STRIPPING = YES;
 				DEBUG_INFORMATION_FORMAT = dwarf;
 				DEVELOPMENT_TEAM = 3Q6X2L86C4;
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
@@ -354,6 +362,7 @@
 				MTL_FAST_MATH = YES;
 				ONLY_ACTIVE_ARCH = YES;
 				SDKROOT = macosx;
+				STRING_CATALOG_GENERATE_SYMBOLS = YES;
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = "DEBUG $(inherited)";
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
 			};
@@ -364,6 +373,7 @@
 			buildSettings = {
 				ALWAYS_SEARCH_USER_PATHS = NO;
 				ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES;
+				CLANG_ANALYZER_LOCALIZABILITY_NONLOCALIZED = YES;
 				CLANG_ANALYZER_NONNULL = YES;
 				CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
 				CLANG_CXX_LANGUAGE_STANDARD = "gnu++20";
@@ -393,6 +403,7 @@
 				CLANG_WARN_UNREACHABLE_CODE = YES;
 				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
 				COPY_PHASE_STRIP = NO;
+				DEAD_CODE_STRIPPING = YES;
 				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
 				DEVELOPMENT_TEAM = 3Q6X2L86C4;
 				ENABLE_NS_ASSERTIONS = NO;
@@ -411,6 +422,7 @@
 				MTL_ENABLE_DEBUG_INFO = NO;
 				MTL_FAST_MATH = YES;
 				SDKROOT = macosx;
+				STRING_CATALOG_GENERATE_SYMBOLS = YES;
 				SWIFT_COMPILATION_MODE = wholemodule;
 			};
 			name = Release;
@@ -424,7 +436,8 @@
 				CODE_SIGN_ENTITLEMENTS = scarf/scarf.entitlements;
 				CODE_SIGN_STYLE = Automatic;
 				COMBINE_HIDPI_IMAGES = YES;
-				CURRENT_PROJECT_VERSION = 21;
+				CURRENT_PROJECT_VERSION = 24;
+				DEAD_CODE_STRIPPING = YES;
 				DEVELOPMENT_TEAM = 3Q6X2L86C4;
 				ENABLE_APP_SANDBOX = NO;
 				ENABLE_HARDENED_RUNTIME = YES;
@@ -436,7 +449,7 @@
 					"@executable_path/../Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 14.6;
-				MARKETING_VERSION = 2.0.2;
+				MARKETING_VERSION = 2.2.1;
 				PRODUCT_BUNDLE_IDENTIFIER = com.scarf.app;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;
@@ -458,7 +471,8 @@
 				CODE_SIGN_ENTITLEMENTS = scarf/scarf.entitlements;
 				CODE_SIGN_STYLE = Automatic;
 				COMBINE_HIDPI_IMAGES = YES;
-				CURRENT_PROJECT_VERSION = 21;
+				CURRENT_PROJECT_VERSION = 24;
+				DEAD_CODE_STRIPPING = YES;
 				DEVELOPMENT_TEAM = 3Q6X2L86C4;
 				ENABLE_APP_SANDBOX = NO;
 				ENABLE_HARDENED_RUNTIME = YES;
@@ -470,7 +484,7 @@
 					"@executable_path/../Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 14.6;
-				MARKETING_VERSION = 2.0.2;
+				MARKETING_VERSION = 2.2.1;
 				PRODUCT_BUNDLE_IDENTIFIER = com.scarf.app;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;
@@ -488,11 +502,12 @@
 			buildSettings = {
 				BUNDLE_LOADER = "$(TEST_HOST)";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 21;
+				CURRENT_PROJECT_VERSION = 24;
+				DEAD_CODE_STRIPPING = YES;
 				DEVELOPMENT_TEAM = 3Q6X2L86C4;
 				GENERATE_INFOPLIST_FILE = YES;
 				MACOSX_DEPLOYMENT_TARGET = 26.2;
-				MARKETING_VERSION = 2.0.2;
+				MARKETING_VERSION = 2.2.1;
 				PRODUCT_BUNDLE_IDENTIFIER = com.scarfTests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				STRING_CATALOG_GENERATE_SYMBOLS = NO;
@@ -509,11 +524,12 @@
 			buildSettings = {
 				BUNDLE_LOADER = "$(TEST_HOST)";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 21;
+				CURRENT_PROJECT_VERSION = 24;
+				DEAD_CODE_STRIPPING = YES;
 				DEVELOPMENT_TEAM = 3Q6X2L86C4;
 				GENERATE_INFOPLIST_FILE = YES;
 				MACOSX_DEPLOYMENT_TARGET = 26.2;
-				MARKETING_VERSION = 2.0.2;
+				MARKETING_VERSION = 2.2.1;
 				PRODUCT_BUNDLE_IDENTIFIER = com.scarfTests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				STRING_CATALOG_GENERATE_SYMBOLS = NO;
@@ -529,10 +545,11 @@
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 21;
+				CURRENT_PROJECT_VERSION = 24;
+				DEAD_CODE_STRIPPING = YES;
 				DEVELOPMENT_TEAM = 3Q6X2L86C4;
 				GENERATE_INFOPLIST_FILE = YES;
-				MARKETING_VERSION = 2.0.2;
+				MARKETING_VERSION = 2.2.1;
 				PRODUCT_BUNDLE_IDENTIFIER = com.scarfUITests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				STRING_CATALOG_GENERATE_SYMBOLS = NO;
@@ -548,10 +565,11 @@
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 21;
+				CURRENT_PROJECT_VERSION = 24;
+				DEAD_CODE_STRIPPING = YES;
 				DEVELOPMENT_TEAM = 3Q6X2L86C4;
 				GENERATE_INFOPLIST_FILE = YES;
-				MARKETING_VERSION = 2.0.2;
+				MARKETING_VERSION = 2.2.1;
 				PRODUCT_BUNDLE_IDENTIFIER = com.scarfUITests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				STRING_CATALOG_GENERATE_SYMBOLS = NO;

scarf/scarf.xcodeproj/xcshareddata/xcschemes/scarf.xcscheme

@@ -0,0 +1,100 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "2620"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES"
+      buildArchitectures = "Automatic">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "5349593F2F7B83B600BD31AD"
+               BuildableName = "scarf.app"
+               BlueprintName = "scarf"
+               ReferencedContainer = "container:scarf.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      shouldAutocreateTestPlan = "YES">
+      <Testables>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "5349594E2F7B83B700BD31AD"
+               BuildableName = "scarfTests.xctest"
+               BlueprintName = "scarfTests"
+               ReferencedContainer = "container:scarf.xcodeproj">
+            </BuildableReference>
+         </TestableReference>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "534959582F7B83B700BD31AD"
+               BuildableName = "scarfUITests.xctest"
+               BlueprintName = "scarfUITests"
+               ReferencedContainer = "container:scarf.xcodeproj">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "5349593F2F7B83B600BD31AD"
+            BuildableName = "scarf.app"
+            BlueprintName = "scarf"
+            ReferencedContainer = "container:scarf.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "5349593F2F7B83B600BD31AD"
+            BuildableName = "scarf.app"
+            BlueprintName = "scarf"
+            ReferencedContainer = "container:scarf.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>

scarf/scarf/ContentView.swift

@@ -14,6 +14,7 @@ struct ContentView: View {
     var body: some View {
         NavigationSplitView {
             SidebarView()
+                .navigationSplitViewColumnWidth(min: 180, ideal: 240, max: 360)
         } detail: {
             detailView
                 .toolbar {

scarf/scarf/Core/Models/HermesMCPServer.swift

@@ -6,7 +6,7 @@ enum MCPTransport: String, Sendable, Equatable, CaseIterable, Identifiable {
 
     var id: String { rawValue }
 
-    var displayName: String {
+    var displayName: LocalizedStringResource {
         switch self {
         case .stdio: return "Local (stdio)"
         case .http: return "Remote (HTTP)"

scarf/scarf/Core/Models/HermesMessage.swift

@@ -99,6 +99,17 @@ enum ToolKind: String, Sendable, CaseIterable {
     case browser
     case other
 
+    var displayName: LocalizedStringResource {
+        switch self {
+        case .read: return "Read"
+        case .edit: return "Edit"
+        case .execute: return "Execute"
+        case .fetch: return "Fetch"
+        case .browser: return "Browser"
+        case .other: return "Other"
+        }
+    }
+
     var icon: String {
         switch self {
         case .read: return "doc.text.magnifyingglass"

scarf/scarf/Core/Models/HermesSlashCommand.swift

@@ -0,0 +1,17 @@
+import Foundation
+
+/// A slash command available in chat. Sourced either from the ACP server
+/// (`available_commands_update`) or from user-defined `quick_commands` in
+/// `config.yaml`.
+struct HermesSlashCommand: Identifiable, Sendable, Equatable {
+    enum Source: Sendable, Equatable {
+        case acp
+        case quickCommand
+    }
+
+    var id: String { name }
+    let name: String
+    let description: String
+    let argumentHint: String?
+    let source: Source
+}

scarf/scarf/Core/Models/ProjectDashboard.swift

@@ -86,8 +86,8 @@ enum WidgetValue: Codable, Sendable, Hashable {
         case .string(let s): return s
         case .number(let n):
             return n.truncatingRemainder(dividingBy: 1) == 0
-                ? String(Int(n))
+                ? Int(n).formatted(.number)
-                : String(format: "%.1f", n)
+                : n.formatted(.number.precision(.fractionLength(1)))
         }
     }
 

scarf/scarf/Core/Models/ProjectTemplate.swift

@@ -0,0 +1,335 @@
+import Foundation
+
+// MARK: - Manifest (what lives inside the .scarftemplate zip)
+
+/// On-disk manifest for a Scarf project template. Shipped as `template.json`
+/// at the root of a `.scarftemplate` (zip) bundle.
+///
+/// The `contents` block is a claim the author makes about what the bundle
+/// ships; the installer verifies the claim against the actual unpacked files
+/// before showing the preview sheet so a malicious bundle can't hide extra
+/// files from the user.
+struct ProjectTemplateManifest: Codable, Sendable, Equatable {
+    let schemaVersion: Int
+    let id: String
+    let name: String
+    let version: String
+    let minScarfVersion: String?
+    let minHermesVersion: String?
+    let author: TemplateAuthor?
+    let description: String
+    let category: String?
+    let tags: [String]?
+    let icon: String?
+    let screenshots: [String]?
+    let contents: TemplateContents
+    /// Optional configuration schema (added in manifest schemaVersion 2).
+    /// When present, the installer presents a form during install and
+    /// writes values to `<project>/.scarf/config.json` + the Keychain.
+    /// Schema-v1 manifests omit this field entirely — Codable's
+    /// optional-field decoding keeps them working unchanged.
+    let config: TemplateConfigSchema?
+
+    /// Filesystem-safe slug derived from `id` (`"owner/name"` → `"owner-name"`).
+    /// Used for the install directory name, skills namespace, and cron-job tag.
+    nonisolated var slug: String {
+        let ascii = id.unicodeScalars.map { scalar -> Character in
+            let c = Character(scalar)
+            if c.isLetter || c.isNumber || c == "-" || c == "_" { return c }
+            return "-"
+        }
+        let collapsed = String(ascii)
+            .split(separator: "-", omittingEmptySubsequences: true)
+            .joined(separator: "-")
+        return collapsed.isEmpty ? "template" : collapsed
+    }
+}
+
+struct TemplateAuthor: Codable, Sendable, Equatable {
+    let name: String
+    let url: String?
+}
+
+struct TemplateContents: Codable, Sendable, Equatable {
+    let dashboard: Bool
+    let agentsMd: Bool
+    let instructions: [String]?
+    let skills: [String]?
+    let cron: Int?
+    let memory: TemplateMemoryClaim?
+    /// Number of configuration fields the template ships (schemaVersion 2+).
+    /// Cross-checked against `manifest.config?.fields.count` by the
+    /// validator so a bundle can't hide a schema from the preview.
+    /// `nil` or `0` means schema-less (v1-compatible behaviour).
+    let config: Int?
+}
+
+struct TemplateMemoryClaim: Codable, Sendable, Equatable {
+    let append: Bool
+}
+
+// MARK: - Inspection (what we learn by unpacking the zip)
+
+/// Result of unpacking a `.scarftemplate` into a temp directory and validating
+/// it. Callers hand this to `buildInstallPlan` to produce the concrete
+/// filesystem plan.
+struct TemplateInspection: Sendable {
+    let manifest: ProjectTemplateManifest
+    /// Absolute path to the temp directory holding the unpacked bundle. The
+    /// installer reads files from here; the caller is responsible for
+    /// cleaning it up after install (or cancel).
+    let unpackedDir: String
+    /// Every file found in the unpacked dir, as paths relative to
+    /// `unpackedDir`. Verified against the manifest's `contents` claim.
+    let files: [String]
+    /// Parsed cron jobs (may be empty even if the manifest claims some —
+    /// verification catches that mismatch).
+    let cronJobs: [TemplateCronJobSpec]
+}
+
+/// The subset of a Hermes cron job that a template can ship. Only the fields
+/// the `hermes cron create` CLI accepts are included; runtime state
+/// (`enabled`, `state`, `next_run_at`, …) is deliberately omitted so a
+/// template can't arrive already-running.
+struct TemplateCronJobSpec: Codable, Sendable, Equatable {
+    let name: String
+    let schedule: String
+    let prompt: String?
+    let deliver: String?
+    let skills: [String]?
+    let repeatCount: Int?
+
+    enum CodingKeys: String, CodingKey {
+        case name, schedule, prompt, deliver, skills
+        case repeatCount = "repeat"
+    }
+}
+
+// MARK: - Install Plan (the preview sheet reads this)
+
+/// Concrete, reviewed-before-apply filesystem operations the installer will
+/// perform. Every side effect the installer can cause is represented here so
+/// the preview sheet is an honest accounting of what's about to happen.
+struct TemplateInstallPlan: Sendable {
+    let manifest: ProjectTemplateManifest
+    let unpackedDir: String
+
+    /// Absolute path of the new project directory. Installer refuses if this
+    /// already exists.
+    let projectDir: String
+    /// Files that will be created under `projectDir`, keyed by relative path.
+    let projectFiles: [TemplateFileCopy]
+
+    /// Absolute path of the skills namespace dir
+    /// (`~/.hermes/skills/templates/<slug>/`). Created if skills are present.
+    let skillsNamespaceDir: String?
+    /// Files that will be created under the skills namespace dir.
+    let skillsFiles: [TemplateFileCopy]
+
+    /// Cron job definitions to register via `hermes cron create`. Each job's
+    /// name is already prefixed with the template tag. All will be paused
+    /// immediately after creation.
+    let cronJobs: [TemplateCronJobSpec]
+
+    /// Memory appendix text (already wrapped in begin/end markers). `nil`
+    /// means no memory write happens.
+    let memoryAppendix: String?
+    /// Target memory path (`~/.hermes/memories/MEMORY.md`). Only used when
+    /// `memoryAppendix` is non-nil.
+    let memoryPath: String
+
+    /// `ProjectEntry.name` that will be appended to the projects registry.
+    let projectRegistryName: String
+
+    /// Configuration schema declared by the template (manifest schemaVersion 2).
+    /// `nil` means the template is schema-less — the installer skips the
+    /// config sheet and writes no `.scarf/config.json` or manifest cache.
+    let configSchema: TemplateConfigSchema?
+
+    /// Values the user entered in the configure sheet. Populated by the
+    /// VM just before `install()` runs; empty when `configSchema` is nil.
+    /// Secrets appear here as `.keychainRef(...)` — the bytes themselves
+    /// were routed straight from the form field into the Keychain and
+    /// never held in memory past that point.
+    var configValues: [String: TemplateConfigValue]
+
+    /// Path at which the installer will stash a copy of `template.json`
+    /// so the post-install Configuration editor can render the form
+    /// offline. `nil` when `configSchema` is nil.
+    let manifestCachePath: String?
+
+    /// Convenience: total number of writes (files + cron jobs + optional
+    /// memory append + registry append + optional config.json + one
+    /// entry per secret written to the Keychain). Displayed in the
+    /// preview sheet.
+    nonisolated var totalWriteCount: Int {
+        let configFileCount = (configSchema?.isEmpty ?? true) ? 0 : 1
+        let secretCount = configValues.values.filter {
+            if case .keychainRef = $0 { return true } else { return false }
+        }.count
+        return projectFiles.count
+            + skillsFiles.count
+            + cronJobs.count
+            + (memoryAppendix == nil ? 0 : 1)
+            + 1  // registry entry
+            + configFileCount
+            + secretCount
+    }
+}
+
+/// A single file to copy from the unpacked bundle into a target directory.
+struct TemplateFileCopy: Sendable, Equatable {
+    /// Path inside `unpackedDir`, e.g. `"AGENTS.md"` or
+    /// `"skills/timer/SKILL.md"`.
+    let sourceRelativePath: String
+    /// Absolute path where the file should land.
+    let destinationPath: String
+}
+
+// MARK: - Lock file (uninstall manifest, dropped into <project>/.scarf/)
+
+/// Dropped at `<project>/.scarf/template.lock.json` after a successful
+/// install. Records exactly what was written so a future "Uninstall Template"
+/// action can reverse it without guessing.
+struct TemplateLock: Codable, Sendable {
+    let templateId: String
+    let templateVersion: String
+    let templateName: String
+    let installedAt: String
+    let projectFiles: [String]
+    let skillsNamespaceDir: String?
+    let skillsFiles: [String]
+    let cronJobNames: [String]
+    let memoryBlockId: String?
+    /// Every `keychain://service/account` URI the installer stored in
+    /// the Keychain for this project's secret fields. Empty/nil for
+    /// schema-less (v1-style) installs. The uninstaller iterates this
+    /// list and calls `SecItemDelete` for each entry; absent on older
+    /// lock files so Codable's optional decoding keeps pre-2.3 installs
+    /// uninstallable.
+    let configKeychainItems: [String]?
+    /// Field keys the installer wrote to `<project>/.scarf/config.json`.
+    /// Informational — the actual removal of config.json rides on
+    /// `projectFiles`. Optional for back-compat.
+    let configFields: [String]?
+
+    enum CodingKeys: String, CodingKey {
+        case templateId = "template_id"
+        case templateVersion = "template_version"
+        case templateName = "template_name"
+        case installedAt = "installed_at"
+        case projectFiles = "project_files"
+        case skillsNamespaceDir = "skills_namespace_dir"
+        case skillsFiles = "skills_files"
+        case cronJobNames = "cron_job_names"
+        case memoryBlockId = "memory_block_id"
+        case configKeychainItems = "config_keychain_items"
+        case configFields = "config_fields"
+    }
+}
+
+// MARK: - Uninstall Plan (the uninstall-preview sheet reads this)
+
+/// Symmetric with `TemplateInstallPlan` but for removal. Built from the
+/// `<project>/.scarf/template.lock.json` the installer wrote. The preview
+/// sheet lists every path the uninstall would touch; the uninstaller
+/// executes the listed ops and nothing else.
+struct TemplateUninstallPlan: Sendable {
+    /// The parsed lock file that seeded this plan. Kept so the sheet can
+    /// display the template id, version, and install timestamp.
+    let lock: TemplateLock
+    /// The registry entry that will be removed on success.
+    let project: ProjectEntry
+
+    /// Lock-tracked files still present on disk that will be removed.
+    let projectFilesToRemove: [String]
+    /// Lock-tracked files that were already missing (e.g. user deleted them
+    /// after install). Shown in the sheet so the user isn't surprised that
+    /// a file isn't removed; uninstaller skips these.
+    let projectFilesAlreadyGone: [String]
+    /// User-added files/dirs in the project dir that are NOT in the lock.
+    /// These are preserved — the sheet lists them so the user knows the
+    /// project dir stays if any exist.
+    let extraProjectEntries: [String]
+    /// If `true`, the project dir ends up empty after removal and will be
+    /// removed along with its files. `false` means user content lives in
+    /// the dir and we leave it.
+    let projectDirBecomesEmpty: Bool
+
+    /// Lock-recorded skills namespace dir. `nil` means the template never
+    /// installed skills. Uninstaller removes the entire dir recursively.
+    let skillsNamespaceDir: String?
+
+    /// Cron jobs that will be removed, as (id, name) pairs. Ids were looked
+    /// up at plan time by matching lock names against the live cron list.
+    let cronJobsToRemove: [(id: String, name: String)]
+    /// Names recorded in the lock that we couldn't find in the current cron
+    /// list (user-deleted, renamed, etc.). Shown in the sheet; skipped on
+    /// uninstall.
+    let cronJobsAlreadyGone: [String]
+
+    /// `true` if MEMORY.md still contains the template's begin/end markers
+    /// and those bytes will be stripped on uninstall. `false` means no
+    /// memory block was ever installed OR the user removed it by hand.
+    let memoryBlockPresent: Bool
+    /// Hermes-side path to MEMORY.md. Only touched when
+    /// `memoryBlockPresent` is true.
+    let memoryPath: String
+
+    nonisolated var totalRemoveCount: Int {
+        projectFilesToRemove.count
+            + (skillsNamespaceDir == nil ? 0 : 1)
+            + cronJobsToRemove.count
+            + (memoryBlockPresent ? 1 : 0)
+            + 1 // registry entry
+    }
+}
+
+// MARK: - Errors
+
+enum ProjectTemplateError: LocalizedError, Sendable {
+    case unzipFailed(String)
+    case manifestMissing
+    case manifestParseFailed(String)
+    case unsupportedSchemaVersion(Int)
+    case requiredFileMissing(String)
+    case contentClaimMismatch(String)
+    case projectDirExists(String)
+    case conflictingFile(String)
+    case memoryBlockAlreadyExists(String)
+    case cronCreateFailed(job: String, output: String)
+    case unsafeZipEntry(String)
+    case lockFileMissing(String)
+    case lockFileParseFailed(String)
+
+    var errorDescription: String? {
+        switch self {
+        case .unzipFailed(let s):
+            return "Couldn't unpack template archive: \(s)"
+        case .manifestMissing:
+            return "Template is missing template.json at the archive root."
+        case .manifestParseFailed(let s):
+            return "Template manifest couldn't be parsed: \(s)"
+        case .unsupportedSchemaVersion(let v):
+            return "Template uses schemaVersion \(v), which this version of Scarf doesn't understand."
+        case .requiredFileMissing(let f):
+            return "Template is missing a required file: \(f)"
+        case .contentClaimMismatch(let s):
+            return "Template manifest doesn't match its contents: \(s)"
+        case .projectDirExists(let p):
+            return "A directory already exists at \(p). Refusing to overwrite — choose a different parent folder."
+        case .conflictingFile(let p):
+            return "An existing file would be overwritten at \(p). Refusing to clobber."
+        case .memoryBlockAlreadyExists(let id):
+            return "A memory block for template '\(id)' already exists in MEMORY.md. Remove it first or install a fresh copy."
+        case .cronCreateFailed(let job, let output):
+            return "Failed to register cron job '\(job)': \(output)"
+        case .unsafeZipEntry(let p):
+            return "Template archive contains an unsafe entry: \(p)"
+        case .lockFileMissing(let path):
+            return "No template.lock.json found at \(path). This project wasn't installed by Scarf's template system — remove it by hand."
+        case .lockFileParseFailed(let s):
+            return "Couldn't read template.lock.json: \(s)"
+        }
+    }
+}

scarf/scarf/Core/Models/TemplateConfig.swift

@@ -0,0 +1,278 @@
+import Foundation
+
+// MARK: - Schema (ships inside template.json as manifest.config)
+
+/// Author-declared configuration schema for a template. Published as the
+/// `config` block of `template.json` (manifest schemaVersion 2). Users fill
+/// in values at install time via `TemplateConfigSheet`; values land in
+/// `<project>/.scarf/config.json` with secrets resolved through the
+/// macOS Keychain.
+struct TemplateConfigSchema: Codable, Sendable, Equatable {
+    let fields: [TemplateConfigField]
+    let modelRecommendation: TemplateModelRecommendation?
+
+    enum CodingKeys: String, CodingKey {
+        case fields = "schema"
+        case modelRecommendation
+    }
+
+    nonisolated var isEmpty: Bool { fields.isEmpty }
+
+    /// Fast lookup by key. Validators guarantee keys are unique within a
+    /// schema at manifest-parse time, so this is safe.
+    nonisolated func field(for key: String) -> TemplateConfigField? {
+        fields.first { $0.key == key }
+    }
+}
+
+/// One configurable field the user fills in. Discriminated by `type`.
+/// We keep one flat struct rather than an enum-associated-value encoding
+/// so JSON reads cleanly as a record and authors can hand-edit manifests
+/// without fighting Swift's `"case"` discriminator syntax.
+struct TemplateConfigField: Codable, Sendable, Equatable, Identifiable {
+    nonisolated var id: String { key }
+
+    let key: String
+    let type: FieldType
+    let label: String
+    let description: String?
+    let required: Bool
+    let placeholder: String?
+
+    // Type-specific constraints — all optional. The validator enforces
+    // only the ones that apply to `type`; extras are ignored.
+    let defaultValue: TemplateConfigValue?
+    let options: [EnumOption]?        // type == .enum
+    let minLength: Int?               // type == .string / .text
+    let maxLength: Int?
+    let pattern: String?              // type == .string (regex)
+    let minNumber: Double?            // type == .number
+    let maxNumber: Double?
+    let step: Double?
+    let itemType: String?             // type == .list — only "string" supported in v1
+    let minItems: Int?
+    let maxItems: Int?
+
+    enum CodingKeys: String, CodingKey {
+        case key, type, label, description, required, placeholder
+        case defaultValue = "default"
+        case options
+        case minLength, maxLength, pattern
+        case minNumber = "min"
+        case maxNumber = "max"
+        case step
+        case itemType, minItems, maxItems
+    }
+
+    enum FieldType: String, Codable, Sendable, Equatable {
+        case string
+        case text
+        case number
+        case bool
+        case `enum`
+        case list
+        case secret
+    }
+
+    /// One option of an `enum` field. `value` is what ends up in
+    /// `config.json`; `label` is the human-readable text shown in the UI.
+    struct EnumOption: Codable, Sendable, Equatable, Identifiable {
+        nonisolated var id: String { value }
+        let value: String
+        let label: String
+    }
+}
+
+/// Author's model-of-choice hint, shown in the install preview + on the
+/// catalog detail page. Purely advisory — Scarf never auto-switches the
+/// active model. Individual cron jobs can override via
+/// `HermesCronJob.model` if the author wants enforcement.
+struct TemplateModelRecommendation: Codable, Sendable, Equatable {
+    let preferred: String
+    let rationale: String?
+    let alternatives: [String]?
+}
+
+// MARK: - Values (what lands in config.json and the Keychain)
+
+/// One configured value. Secrets don't carry their raw bytes — only a
+/// Keychain reference of the form `"keychain://<service>/<account>"` so
+/// serialising config.json to disk never leaks the secret into git or
+/// into backups.
+enum TemplateConfigValue: Codable, Sendable, Equatable {
+    case string(String)
+    case number(Double)
+    case bool(Bool)
+    case list([String])
+    case keychainRef(String)
+
+    /// Convenience: the string representation suitable for display or
+    /// for writing into a placeholder that the agent reads. Keychain
+    /// refs return the ref string, not the resolved secret — callers
+    /// resolve through `ProjectConfigKeychain` explicitly when they
+    /// actually need the plaintext.
+    nonisolated var displayString: String {
+        switch self {
+        case .string(let s): return s
+        case .number(let n):
+            return n.truncatingRemainder(dividingBy: 1) == 0
+                ? String(Int(n))
+                : String(n)
+        case .bool(let b): return b ? "true" : "false"
+        case .list(let items): return items.joined(separator: ", ")
+        case .keychainRef(let ref): return ref
+        }
+    }
+
+    init(from decoder: Decoder) throws {
+        let container = try decoder.singleValueContainer()
+        if let s = try? container.decode(String.self) {
+            // Preserve the keychain:// scheme so secrets round-trip as
+            // references, not as plaintext.
+            if s.hasPrefix("keychain://") {
+                self = .keychainRef(s)
+            } else {
+                self = .string(s)
+            }
+        } else if let b = try? container.decode(Bool.self) {
+            self = .bool(b)
+        } else if let n = try? container.decode(Double.self) {
+            self = .number(n)
+        } else if let arr = try? container.decode([String].self) {
+            self = .list(arr)
+        } else {
+            throw DecodingError.typeMismatch(
+                TemplateConfigValue.self,
+                .init(codingPath: decoder.codingPath,
+                      debugDescription: "Expected String, Bool, Number, or [String]")
+            )
+        }
+    }
+
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.singleValueContainer()
+        switch self {
+        case .string(let s): try container.encode(s)
+        case .number(let n): try container.encode(n)
+        case .bool(let b): try container.encode(b)
+        case .list(let items): try container.encode(items)
+        case .keychainRef(let ref): try container.encode(ref)
+        }
+    }
+}
+
+// MARK: - On-disk shape (what's in <project>/.scarf/config.json)
+
+/// The JSON file the installer writes + the editor reads. Non-secret
+/// values appear inline; secrets are `"keychain://<service>/<account>"`
+/// references that `ProjectConfigService` resolves through the Keychain
+/// on demand.
+struct ProjectConfigFile: Codable, Sendable {
+    let schemaVersion: Int
+    let templateId: String
+    var values: [String: TemplateConfigValue]
+    let updatedAt: String
+
+    enum CodingKeys: String, CodingKey {
+        case schemaVersion
+        case templateId
+        case values
+        case updatedAt
+    }
+}
+
+// MARK: - Keychain reference helpers
+
+/// One secret stored via `ProjectConfigKeychain`. We derive both halves
+/// (service + account) from the template slug + project-path hash so two
+/// installs of the same template in different dirs don't collide in the
+/// login Keychain.
+struct TemplateKeychainRef: Sendable, Equatable {
+    /// Macro service name, e.g. `com.scarf.template.awizemann-site-status-checker`.
+    let service: String
+    /// Account name: `<fieldKey>:<projectPathHashShort>`. The hash suffix
+    /// guarantees uniqueness across multiple installs of the same template.
+    let account: String
+
+    /// `"keychain://<service>/<account>"` — what lands in `config.json`.
+    nonisolated var uri: String { "keychain://\(service)/\(account)" }
+
+    /// Parse a `keychain://…` URI back into a ref. Returns `nil` when the
+    /// input isn't well-formed so callers can distinguish a missing ref
+    /// from a malformed one.
+    nonisolated static func parse(_ uri: String) -> TemplateKeychainRef? {
+        guard uri.hasPrefix("keychain://") else { return nil }
+        let rest = String(uri.dropFirst("keychain://".count))
+        guard let slash = rest.firstIndex(of: "/") else { return nil }
+        let service = String(rest[..<slash])
+        let account = String(rest[rest.index(after: slash)...])
+        guard !service.isEmpty, !account.isEmpty else { return nil }
+        return TemplateKeychainRef(service: service, account: account)
+    }
+
+    /// Build a ref from a template slug + field key + project path.
+    /// The hash suffix is a SHA-256-truncated-to-8-hex-chars fingerprint
+    /// of the absolute project path. Stable across launches, different
+    /// between `/Users/a/proj1` and `/Users/a/proj2`.
+    nonisolated static func make(
+        templateSlug: String,
+        fieldKey: String,
+        projectPath: String
+    ) -> TemplateKeychainRef {
+        TemplateKeychainRef(
+            service: "com.scarf.template.\(templateSlug)",
+            account: "\(fieldKey):\(Self.shortHash(of: projectPath))"
+        )
+    }
+
+    nonisolated static func shortHash(of string: String) -> String {
+        // 8 hex chars is 32 bits of uniqueness — plenty for
+        // distinguishing a handful of project dirs per template install.
+        let data = Data(string.utf8)
+        var hash: UInt32 = 0x811c9dc5
+        for byte in data {
+            hash ^= UInt32(byte)
+            hash &*= 0x01000193
+        }
+        return String(format: "%08x", hash)
+    }
+}
+
+// MARK: - Validation
+
+/// One schema- or value-validation problem. Carries `fieldKey` so the
+/// UI can surface the error inline with the field rather than at the
+/// top of the form.
+struct TemplateConfigValidationError: Error, Sendable, Equatable {
+    let fieldKey: String?
+    let message: String
+}
+
+enum TemplateConfigSchemaError: LocalizedError, Sendable {
+    case duplicateKey(String)
+    case unsupportedType(String)
+    case emptyEnumOptions(String)
+    case duplicateEnumValue(key: String, value: String)
+    case unsupportedListItemType(key: String, itemType: String)
+    case secretFieldHasDefault(String)
+    case emptyModelPreferred
+
+    var errorDescription: String? {
+        switch self {
+        case .duplicateKey(let k):
+            return "Config schema has duplicate key: \(k)"
+        case .unsupportedType(let t):
+            return "Config schema uses unsupported field type: \(t)"
+        case .emptyEnumOptions(let k):
+            return "Enum field '\(k)' must declare at least one option"
+        case .duplicateEnumValue(let k, let v):
+            return "Enum field '\(k)' has duplicate option value: \(v)"
+        case .unsupportedListItemType(let k, let t):
+            return "List field '\(k)' uses unsupported itemType '\(t)'. Only 'string' is supported in v1."
+        case .secretFieldHasDefault(let k):
+            return "Secret field '\(k)' cannot declare a default value — secrets belong only in the Keychain."
+        case .emptyModelPreferred:
+            return "modelRecommendation.preferred must be a non-empty model id."
+        }
+    }
+}

scarf/scarf/Core/Persistence/ServerRegistry.swift

@@ -9,8 +9,10 @@ struct ServerEntry: Identifiable, Codable, Hashable, Sendable {
     var id: ServerID
     var displayName: String
     var kind: ServerKind
-    /// User preference: open this server in a window on launch. Phase 3
+    /// User preference: this server is the one Scarf opens into when a
-    /// multi-window uses this; Phase 2 ignores it.
+    /// fresh window has no prior binding (first launch or File → New).
+    /// At most one entry should have this set — `ServerRegistry` enforces
+    /// mutual exclusivity. If none do, Local is the implicit default.
     var openOnLaunch: Bool = false
 
     var context: ServerContext {
@@ -69,6 +71,36 @@ final class ServerRegistry {
         return nil
     }
 
+    /// The server a fresh window should open into. Returns the ID of the
+    /// remote entry flagged `openOnLaunch`, or Local's ID if none is
+    /// flagged (or if the flagged entry was removed out from under us).
+    /// Consumed by the `WindowGroup`'s `defaultValue` closure.
+    var defaultServerID: ServerID {
+        entries.first(where: { $0.openOnLaunch })?.id ?? ServerContext.local.id
+    }
+
+    /// Flip the default server to `id`. Passing `ServerContext.local.id`
+    /// clears the flag on every remote entry, making Local the implicit
+    /// default. Passing an unknown ID is a no-op. Persisted on return.
+    ///
+    /// Intentionally doesn't fire `onEntriesChanged` — that hook means "the
+    /// set of servers changed" and drives the menu-bar fanout rebuild. A
+    /// default-flag flip doesn't change the set; SwiftUI views reading
+    /// `defaultServerID` redraw via `@Observable`'s tracking of `entries`.
+    func setDefaultServer(_ id: ServerID) {
+        var changed = false
+        for idx in entries.indices {
+            let shouldBeDefault = (entries[idx].id == id)
+            if entries[idx].openOnLaunch != shouldBeDefault {
+                entries[idx].openOnLaunch = shouldBeDefault
+                changed = true
+            }
+        }
+        if changed {
+            save()
+        }
+    }
+
     // MARK: - Mutations
 
     /// Optional callback fired whenever `entries` changes. The app wires

scarf/scarf/Core/Services/ModelCatalogService.swift

@@ -20,7 +20,8 @@ struct HermesModelInfo: Sendable, Identifiable, Hashable {
     /// Display-friendly cost string, or nil if cost is unknown.
     var costDisplay: String? {
         guard let input = costInput, let output = costOutput else { return nil }
-        return String(format: "$%.2f / $%.2f", input, output)
+        let currency = FloatingPointFormatStyle<Double>.Currency.currency(code: "USD").precision(.fractionLength(2))
+        return "\(input.formatted(currency)) / \(output.formatted(currency))"
     }
 
     /// Display-friendly context window ("200K", "1M", etc.).

scarf/scarf/Core/Services/ProjectConfigKeychain.swift

@@ -0,0 +1,154 @@
+import Foundation
+import Security
+import os
+
+/// Thin wrapper around the macOS Keychain for template-config secrets.
+/// Scarf doesn't have other Keychain users yet so this file is the one
+/// place that touches the `Security` framework; keep it small and
+/// auditable so a reader can tell at a glance what we store, under what
+/// identifiers, and when items are removed.
+///
+/// **What we store.** Generic passwords (kSecClassGenericPassword) in
+/// the login Keychain. Each item is identified by a (service, account)
+/// pair derived from the template slug + field key + project-path hash
+/// — see `TemplateKeychainRef.make`. The stored Data is the user's
+/// raw secret bytes; we never transform or encode them.
+///
+/// **When items are written.** By `ProjectTemplateInstaller` after the
+/// install preview is confirmed and the user has filled in the
+/// configure sheet. By `TemplateConfigSheet` when the user edits a
+/// secret field post-install.
+///
+/// **When items are removed.** By `ProjectTemplateUninstaller`,
+/// iterating the lock file's `configKeychainItems` list. The login
+/// Keychain is never swept for stray entries — if the lock is out of
+/// sync we log + skip rather than guess which items are ours.
+///
+/// **What shows to the user.** macOS prompts "Scarf wants to access
+/// the Keychain" the first time we read a secret in a given session.
+/// User approves; subsequent reads in that session are silent. We
+/// never bypass this — the prompt is the user's trust boundary.
+struct ProjectConfigKeychain: Sendable {
+    private static let logger = Logger(subsystem: "com.scarf", category: "ProjectConfigKeychain")
+
+    /// Which Keychain to target. The default is the login Keychain
+    /// (`nil` uses the user's default chain). Tests pass an explicit
+    /// namespace suffix via `testServiceSuffix` — see `TemplateConfigTests` —
+    /// so integration tests can roundtrip without polluting real
+    /// user state.
+    let testServiceSuffix: String?
+
+    nonisolated init(testServiceSuffix: String? = nil) {
+        self.testServiceSuffix = testServiceSuffix
+    }
+
+    /// Write or overwrite the secret for (service, account). Tests
+    /// route their items through a distinct service prefix via
+    /// `testServiceSuffix` so they can't leak into the user's real
+    /// Keychain.
+    nonisolated func set(service: String, account: String, secret: Data) throws {
+        let svc = resolved(service: service)
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: svc,
+            kSecAttrAccount as String: account,
+        ]
+        // Try update first — cheaper than delete-then-add and doesn't
+        // trip macOS's "item already exists" if another thread raced us.
+        let update: [String: Any] = [
+            kSecValueData as String: secret,
+        ]
+        let updateStatus = SecItemUpdate(query as CFDictionary, update as CFDictionary)
+        if updateStatus == errSecSuccess { return }
+        if updateStatus != errSecItemNotFound {
+            throw Self.error(status: updateStatus, op: "update")
+        }
+        var insert = query
+        insert[kSecValueData as String] = secret
+        // kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly — stays in
+        // this device's Keychain, not synced via iCloud, usable after
+        // first unlock (so background cron triggers can read).
+        insert[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+        let addStatus = SecItemAdd(insert as CFDictionary, nil)
+        if addStatus != errSecSuccess {
+            throw Self.error(status: addStatus, op: "add")
+        }
+    }
+
+    /// Retrieve the secret for (service, account). Returns `nil` when
+    /// the item simply doesn't exist (user never set it, or an
+    /// uninstall already removed it). Throws on every other Keychain
+    /// error so callers don't silently treat "access denied" or
+    /// "corrupt keychain" as "no value."
+    nonisolated func get(service: String, account: String) throws -> Data? {
+        let svc = resolved(service: service)
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: svc,
+            kSecAttrAccount as String: account,
+            kSecReturnData as String: true,
+            kSecMatchLimit as String: kSecMatchLimitOne,
+        ]
+        var result: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &result)
+        if status == errSecItemNotFound { return nil }
+        if status != errSecSuccess {
+            throw Self.error(status: status, op: "get")
+        }
+        return result as? Data
+    }
+
+    /// Delete the secret for (service, account). Absent item is a
+    /// no-op; any other failure throws. Called by
+    /// `ProjectTemplateUninstaller` for every item in
+    /// `TemplateLock.configKeychainItems`.
+    nonisolated func delete(service: String, account: String) throws {
+        let svc = resolved(service: service)
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: svc,
+            kSecAttrAccount as String: account,
+        ]
+        let status = SecItemDelete(query as CFDictionary)
+        if status == errSecItemNotFound || status == errSecSuccess { return }
+        throw Self.error(status: status, op: "delete")
+    }
+
+    /// Convenience: apply the test suffix when in test mode.
+    nonisolated private func resolved(service: String) -> String {
+        guard let suffix = testServiceSuffix, !suffix.isEmpty else { return service }
+        return "\(service).\(suffix)"
+    }
+
+    /// Build a useful NSError from a Keychain OSStatus. Logs at warning
+    /// — callers decide whether the failure is fatal.
+    nonisolated private static func error(status: OSStatus, op: String) -> NSError {
+        let description = (SecCopyErrorMessageString(status, nil) as String?) ?? "Keychain error"
+        logger.warning("Keychain \(op, privacy: .public) failed: \(status) \(description, privacy: .public)")
+        return NSError(
+            domain: "com.scarf.keychain",
+            code: Int(status),
+            userInfo: [
+                NSLocalizedDescriptionKey: "Keychain \(op) failed (\(status)): \(description)"
+            ]
+        )
+    }
+}
+
+// MARK: - Ref-shaped convenience layer
+
+extension ProjectConfigKeychain {
+    /// Set a secret using a pre-built `TemplateKeychainRef`. Mirrors the
+    /// service/account plumbing every caller would otherwise repeat.
+    nonisolated func set(ref: TemplateKeychainRef, secret: Data) throws {
+        try set(service: ref.service, account: ref.account, secret: secret)
+    }
+
+    nonisolated func get(ref: TemplateKeychainRef) throws -> Data? {
+        try get(service: ref.service, account: ref.account)
+    }
+
+    nonisolated func delete(ref: TemplateKeychainRef) throws {
+        try delete(service: ref.service, account: ref.account)
+    }
+}

scarf/scarf/Core/Services/ProjectConfigService.swift

@@ -0,0 +1,318 @@
+import Foundation
+import os
+
+/// Per-project configuration I/O: reads `<project>/.scarf/config.json`
+/// into typed values, writes them back, resolves Keychain-backed secrets
+/// on demand, and validates user-entered values against the schema.
+///
+/// Separation of concerns:
+///
+/// - **Schema authority.** `TemplateConfigSchema` lives in the bundle's
+///   `template.json` and a copy is stashed at `<project>/.scarf/manifest.json`
+///   at install time so the post-install editor works offline. This
+///   service treats the schema as read-only input; `validateSchema`
+///   checks structural invariants and is called by
+///   `ProjectTemplateService` during install-plan building.
+/// - **Value storage.** Non-secret values live inline in `config.json`;
+///   secret values are Keychain references of the form
+///   `"keychain://<service>/<account>"`. The service owns both halves
+///   of that storage — callers never open `config.json` or touch the
+///   Keychain directly.
+/// - **Remote readiness.** All file I/O goes through
+///   `ServerContext.makeTransport()` so when `ProjectTemplateInstaller`
+///   eventually supports remote contexts, the config store comes along
+///   for the ride. Keychain access stays local (it's a macOS-side thing
+///   by definition — agents on remote Hermes installs would fetch
+///   values via Scarf's channel, same as today).
+struct ProjectConfigService: Sendable {
+    private static let logger = Logger(subsystem: "com.scarf", category: "ProjectConfigService")
+
+    let context: ServerContext
+    let keychain: ProjectConfigKeychain
+
+    nonisolated init(
+        context: ServerContext = .local,
+        keychain: ProjectConfigKeychain = ProjectConfigKeychain()
+    ) {
+        self.context = context
+        self.keychain = keychain
+    }
+
+    // MARK: - Paths
+
+    nonisolated static func configPath(for project: ProjectEntry) -> String {
+        project.path + "/.scarf/config.json"
+    }
+
+    nonisolated static func manifestCachePath(for project: ProjectEntry) -> String {
+        project.path + "/.scarf/manifest.json"
+    }
+
+    // MARK: - Load / save on-disk config
+
+    /// Read + decode `<project>/.scarf/config.json`. Returns `nil`
+    /// cleanly when the file is absent (e.g. a project installed from
+    /// a schema-less template, or a hand-added project). Throws on
+    /// malformed JSON so the caller can surface a concrete error
+    /// rather than silently treating a corrupt file as missing.
+    nonisolated func load(project: ProjectEntry) throws -> ProjectConfigFile? {
+        let transport = context.makeTransport()
+        let path = Self.configPath(for: project)
+        guard transport.fileExists(path) else { return nil }
+        let data = try transport.readFile(path)
+        do {
+            return try JSONDecoder().decode(ProjectConfigFile.self, from: data)
+        } catch {
+            Self.logger.error("couldn't decode config.json at \(path, privacy: .public): \(error.localizedDescription, privacy: .public)")
+            throw error
+        }
+    }
+
+    /// Write `<project>/.scarf/config.json`. Secrets should already be
+    /// represented as `TemplateConfigValue.keychainRef` references here
+    /// — this service never inspects their plaintext.
+    nonisolated func save(
+        project: ProjectEntry,
+        templateId: String,
+        values: [String: TemplateConfigValue]
+    ) throws {
+        let transport = context.makeTransport()
+        let file = ProjectConfigFile(
+            schemaVersion: 2,
+            templateId: templateId,
+            values: values,
+            updatedAt: ISO8601DateFormatter().string(from: Date())
+        )
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        let data = try encoder.encode(file)
+        let parent = (Self.configPath(for: project) as NSString).deletingLastPathComponent
+        try transport.createDirectory(parent)
+        try transport.writeFile(Self.configPath(for: project), data: data)
+    }
+
+    // MARK: - Manifest cache (schema used by post-install editor)
+
+    /// Copy a template's `template.json` into `<project>/.scarf/manifest.json`
+    /// so the post-install "Configuration" button can render the form
+    /// offline. Called once by the installer after unpack + validate.
+    nonisolated func cacheManifest(project: ProjectEntry, manifestData: Data) throws {
+        let transport = context.makeTransport()
+        let path = Self.manifestCachePath(for: project)
+        let parent = (path as NSString).deletingLastPathComponent
+        try transport.createDirectory(parent)
+        try transport.writeFile(path, data: manifestData)
+    }
+
+    /// Load the cached manifest into a `ProjectTemplateManifest` so the
+    /// editor can look up field types + labels. Returns `nil` when the
+    /// project wasn't installed from a schemaful template.
+    nonisolated func loadCachedManifest(project: ProjectEntry) throws -> ProjectTemplateManifest? {
+        let transport = context.makeTransport()
+        let path = Self.manifestCachePath(for: project)
+        guard transport.fileExists(path) else { return nil }
+        let data = try transport.readFile(path)
+        return try JSONDecoder().decode(ProjectTemplateManifest.self, from: data)
+    }
+
+    // MARK: - Secrets
+
+    /// Resolve a `keychainRef` value into the actual secret bytes.
+    /// Returns `nil` if the Keychain entry has been removed (e.g.
+    /// external user cleanup, a previous uninstall that didn't finish).
+    nonisolated func resolveSecret(ref value: TemplateConfigValue) throws -> Data? {
+        guard case .keychainRef(let uri) = value,
+              let ref = TemplateKeychainRef.parse(uri) else {
+            return nil
+        }
+        return try keychain.get(ref: ref)
+    }
+
+    /// Store a freshly-entered secret. Returns the `keychainRef` value
+    /// suitable for writing into `config.json`.
+    nonisolated func storeSecret(
+        templateSlug: String,
+        fieldKey: String,
+        project: ProjectEntry,
+        secret: Data
+    ) throws -> TemplateConfigValue {
+        let ref = TemplateKeychainRef.make(
+            templateSlug: templateSlug,
+            fieldKey: fieldKey,
+            projectPath: project.path
+        )
+        try keychain.set(ref: ref, secret: secret)
+        return .keychainRef(ref.uri)
+    }
+
+    /// Delete every Keychain item tracked in `refs`. Absent items are
+    /// fine (uninstall may run after the user manually cleaned an
+    /// entry). Any other failure is logged and re-thrown so the
+    /// uninstaller can surface it.
+    nonisolated func deleteSecrets(refs: [TemplateKeychainRef]) throws {
+        for ref in refs {
+            try keychain.delete(ref: ref)
+        }
+    }
+
+    // MARK: - Schema validation (author-facing; called at bundle inspect time)
+
+    /// Verify structural invariants on a schema: unique keys, known
+    /// types, enum options, secret-without-default rule, model
+    /// recommendation non-empty when present. Called by
+    /// `ProjectTemplateService.inspect` before buildPlan runs.
+    nonisolated static func validateSchema(_ schema: TemplateConfigSchema) throws {
+        var seen = Set<String>()
+        for field in schema.fields {
+            if !seen.insert(field.key).inserted {
+                throw TemplateConfigSchemaError.duplicateKey(field.key)
+            }
+            switch field.type {
+            case .enum:
+                let opts = field.options ?? []
+                guard !opts.isEmpty else {
+                    throw TemplateConfigSchemaError.emptyEnumOptions(field.key)
+                }
+                var seenValues = Set<String>()
+                for opt in opts {
+                    if !seenValues.insert(opt.value).inserted {
+                        throw TemplateConfigSchemaError.duplicateEnumValue(key: field.key, value: opt.value)
+                    }
+                }
+            case .list:
+                let item = field.itemType ?? "string"
+                if item != "string" {
+                    throw TemplateConfigSchemaError.unsupportedListItemType(key: field.key, itemType: item)
+                }
+            case .secret:
+                if field.defaultValue != nil {
+                    throw TemplateConfigSchemaError.secretFieldHasDefault(field.key)
+                }
+            case .string, .text, .number, .bool:
+                break
+            }
+        }
+        if let rec = schema.modelRecommendation {
+            if rec.preferred.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                throw TemplateConfigSchemaError.emptyModelPreferred
+            }
+        }
+    }
+
+    // MARK: - Value validation (runs on user input in the configure sheet)
+
+    /// Validate user-entered values against the schema. Returns one
+    /// `TemplateConfigValidationError` per problem. Empty array means
+    /// the form is submittable.
+    nonisolated static func validateValues(
+        _ values: [String: TemplateConfigValue],
+        against schema: TemplateConfigSchema
+    ) -> [TemplateConfigValidationError] {
+        var errors: [TemplateConfigValidationError] = []
+        for field in schema.fields {
+            let value = values[field.key]
+            if field.required && !Self.hasMeaningfulValue(value, type: field.type) {
+                errors.append(.init(fieldKey: field.key, message: "\(field.label) is required."))
+                continue
+            }
+            guard let value else { continue }
+            switch field.type {
+            case .string, .text:
+                if case .string(let s) = value {
+                    if let min = field.minLength, s.count < min {
+                        errors.append(.init(fieldKey: field.key,
+                                            message: "\(field.label) must be at least \(min) characters."))
+                    }
+                    if let max = field.maxLength, s.count > max {
+                        errors.append(.init(fieldKey: field.key,
+                                            message: "\(field.label) must be at most \(max) characters."))
+                    }
+                    if let pattern = field.pattern,
+                       s.range(of: pattern, options: .regularExpression) == nil {
+                        errors.append(.init(fieldKey: field.key,
+                                            message: "\(field.label) doesn't match the expected format."))
+                    }
+                } else {
+                    errors.append(.init(fieldKey: field.key,
+                                        message: "\(field.label) must be a string."))
+                }
+
+            case .number:
+                if case .number(let n) = value {
+                    if let min = field.minNumber, n < min {
+                        errors.append(.init(fieldKey: field.key,
+                                            message: "\(field.label) must be ≥ \(min)."))
+                    }
+                    if let max = field.maxNumber, n > max {
+                        errors.append(.init(fieldKey: field.key,
+                                            message: "\(field.label) must be ≤ \(max)."))
+                    }
+                } else {
+                    errors.append(.init(fieldKey: field.key,
+                                        message: "\(field.label) must be a number."))
+                }
+
+            case .bool:
+                if case .bool = value { /* ok */ } else {
+                    errors.append(.init(fieldKey: field.key,
+                                        message: "\(field.label) must be true or false."))
+                }
+
+            case .enum:
+                if case .string(let s) = value {
+                    let options = (field.options ?? []).map(\.value)
+                    if !options.contains(s) {
+                        errors.append(.init(fieldKey: field.key,
+                                            message: "\(field.label) must be one of \(options.joined(separator: ", "))."))
+                    }
+                } else {
+                    errors.append(.init(fieldKey: field.key,
+                                        message: "\(field.label) must be one of the predefined options."))
+                }
+
+            case .list:
+                if case .list(let items) = value {
+                    if let min = field.minItems, items.count < min {
+                        errors.append(.init(fieldKey: field.key,
+                                            message: "\(field.label) needs at least \(min) item(s)."))
+                    }
+                    if let max = field.maxItems, items.count > max {
+                        errors.append(.init(fieldKey: field.key,
+                                            message: "\(field.label) accepts at most \(max) item(s)."))
+                    }
+                } else {
+                    errors.append(.init(fieldKey: field.key,
+                                        message: "\(field.label) must be a list."))
+                }
+
+            case .secret:
+                if case .keychainRef = value { /* opaque — trust it */ } else {
+                    errors.append(.init(fieldKey: field.key,
+                                        message: "\(field.label) must be supplied (Keychain entry missing)."))
+                }
+            }
+        }
+        return errors
+    }
+
+    nonisolated private static func hasMeaningfulValue(
+        _ value: TemplateConfigValue?,
+        type: TemplateConfigField.FieldType
+    ) -> Bool {
+        guard let value else { return false }
+        switch (type, value) {
+        case (.string, .string(let s)), (.text, .string(let s)), (.enum, .string(let s)):
+            return !s.isEmpty
+        case (.number, .number):
+            return true
+        case (.bool, .bool):
+            return true
+        case (.list, .list(let arr)):
+            return !arr.isEmpty
+        case (.secret, .keychainRef):
+            return true
+        default:
+            return false
+        }
+    }
+}

scarf/scarf/Core/Services/ProjectDashboardService.swift

@@ -1,6 +1,8 @@
 import Foundation
+import os
 
 struct ProjectDashboardService: Sendable {
+    private static let logger = Logger(subsystem: "com.scarf", category: "ProjectDashboardService")
 
     let context: ServerContext
     let transport: any ServerTransport
@@ -19,23 +21,28 @@ struct ProjectDashboardService: Sendable {
         do {
             return try JSONDecoder().decode(ProjectRegistry.self, from: data)
         } catch {
-            print("[Scarf] Failed to decode project registry: \(error.localizedDescription)")
+            Self.logger.error("Failed to decode project registry: \(error.localizedDescription, privacy: .public)")
             return ProjectRegistry(projects: [])
         }
     }
 
-    func saveRegistry(_ registry: ProjectRegistry) {
+    /// Persist the project registry to `~/.hermes/scarf/projects.json`.
+    ///
+    /// **Throws** on every non-success path — the previous version of
+    /// this method silently swallowed `createDirectory` and `writeFile`
+    /// failures with `try?`, which meant the installer could return a
+    /// valid-looking `ProjectEntry` while the registry on disk never
+    /// received the new row (project would complete install, show a
+    /// success screen, then be invisible in the sidebar). Callers that
+    /// want fire-and-forget behaviour can still use `try?`, but the
+    /// choice is now theirs.
+    func saveRegistry(_ registry: ProjectRegistry) throws {
         let dir = context.paths.scarfDir
         if !transport.fileExists(dir) {
-            do {
+            try transport.createDirectory(dir)
-                try transport.createDirectory(dir)
-            } catch {
-                print("[Scarf] Failed to create scarf directory: \(error.localizedDescription)")
-                return
-            }
         }
-        guard let data = try? JSONEncoder().encode(registry) else { return }
+        let data = try JSONEncoder().encode(registry)
-        // Pretty-print for readability (agents may read this file)
+        // Pretty-print for readability (agents may read this file).
         let writeData: Data
         if let pretty = try? JSONSerialization.jsonObject(with: data),
            let formatted = try? JSONSerialization.data(withJSONObject: pretty, options: [.prettyPrinted, .sortedKeys]) {
@@ -43,7 +50,7 @@ struct ProjectDashboardService: Sendable {
         } else {
             writeData = data
         }
-        try? transport.writeFile(context.paths.projectsRegistry, data: writeData)
+        try transport.writeFile(context.paths.projectsRegistry, data: writeData)
     }
 
     // MARK: - Dashboard

scarf/scarf/Core/Services/ProjectTemplateExporter.swift

@@ -0,0 +1,336 @@
+import Foundation
+import os
+
+/// Builds a `.scarftemplate` bundle from an existing Scarf project plus the
+/// caller's selection of skills and cron jobs. Symmetric with the
+/// `ProjectTemplateService` + `ProjectTemplateInstaller` pair — the output
+/// of this exporter can be fed straight back to `inspect()` + `install()`.
+struct ProjectTemplateExporter: Sendable {
+    private static let logger = Logger(subsystem: "com.scarf", category: "ProjectTemplateExporter")
+
+    let context: ServerContext
+
+    nonisolated init(context: ServerContext = .local) {
+        self.context = context
+    }
+
+    /// Known filenames in the project root that map to specific agents. When
+    /// the author opts to include them, each is copied verbatim into
+    /// `instructions/` in the bundle.
+    nonisolated static let knownInstructionFiles: [String] = [
+        "CLAUDE.md",
+        "GEMINI.md",
+        ".cursorrules",
+        ".github/copilot-instructions.md"
+    ]
+
+    /// Author-facing description of what `export` will do with the given
+    /// selections. Shown in the export sheet so the user knows exactly
+    /// what's about to go into the bundle before saving.
+    struct ExportPlan: Sendable {
+        let templateId: String
+        let templateName: String
+        let templateVersion: String
+        let projectDir: String
+        let dashboardPresent: Bool
+        let agentsMdPresent: Bool
+        let readmePresent: Bool
+        let instructionFiles: [String]
+        let skillIds: [String]
+        let cronJobs: [HermesCronJob]
+        let memoryAppendix: String?
+    }
+
+    /// Inputs collected by the export sheet.
+    struct ExportInputs: Sendable {
+        let project: ProjectEntry
+        let templateId: String
+        let templateName: String
+        let templateVersion: String
+        let description: String
+        let authorName: String?
+        let authorUrl: String?
+        let category: String?
+        let tags: [String]
+        let includeSkillIds: [String]
+        let includeCronJobIds: [String]
+        /// Raw markdown the author wants appended to installers' MEMORY.md.
+        /// `nil` to skip.
+        let memoryAppendix: String?
+    }
+
+    /// Scan the project dir and report what a fresh export would include
+    /// given the caller's inputs. Does not write anything.
+    ///
+    /// Existence checks go through the context's transport — the project
+    /// path comes from the registry on the active server and may be on a
+    /// remote filesystem (future remote-install support), where
+    /// `FileManager.default.fileExists` would silently return `false`.
+    nonisolated func previewPlan(for inputs: ExportInputs) -> ExportPlan {
+        let dir = inputs.project.path
+        let transport = context.makeTransport()
+        let dashboard = transport.fileExists(dir + "/.scarf/dashboard.json")
+        let readme = transport.fileExists(dir + "/README.md")
+        let agents = transport.fileExists(dir + "/AGENTS.md")
+        let instructions = Self.knownInstructionFiles.filter {
+            transport.fileExists(dir + "/" + $0)
+        }
+        let allJobs = HermesFileService(context: context).loadCronJobs()
+        let picked = allJobs.filter { inputs.includeCronJobIds.contains($0.id) }
+        return ExportPlan(
+            templateId: inputs.templateId,
+            templateName: inputs.templateName,
+            templateVersion: inputs.templateVersion,
+            projectDir: dir,
+            dashboardPresent: dashboard,
+            agentsMdPresent: agents,
+            readmePresent: readme,
+            instructionFiles: instructions,
+            skillIds: inputs.includeSkillIds,
+            cronJobs: picked,
+            memoryAppendix: inputs.memoryAppendix
+        )
+    }
+
+    /// Build the bundle and write it to `outputZipPath`. Throws if any
+    /// required file is missing or the zip step fails.
+    nonisolated func export(
+        inputs: ExportInputs,
+        outputZipPath: String
+    ) throws {
+        let stagingDir = NSTemporaryDirectory() + "scarf-template-export-" + UUID().uuidString
+        try FileManager.default.createDirectory(atPath: stagingDir, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(atPath: stagingDir) }
+
+        let plan = previewPlan(for: inputs)
+
+        guard plan.dashboardPresent else {
+            throw ProjectTemplateError.requiredFileMissing("dashboard.json (expected at \(plan.projectDir)/.scarf/dashboard.json)")
+        }
+        guard plan.readmePresent else {
+            throw ProjectTemplateError.requiredFileMissing("README.md (expected at \(plan.projectDir)/README.md)")
+        }
+        guard plan.agentsMdPresent else {
+            throw ProjectTemplateError.requiredFileMissing("AGENTS.md (expected at \(plan.projectDir)/AGENTS.md)")
+        }
+
+        // Required files. All source reads go through the context's
+        // transport — project paths come from the registry on the active
+        // server and may be on a remote filesystem. Destinations are in
+        // the local staging dir so Foundation writes are correct.
+        let transport = context.makeTransport()
+        try copyFromHermes(plan.projectDir + "/.scarf/dashboard.json", to: stagingDir + "/dashboard.json", transport: transport)
+        try copyFromHermes(plan.projectDir + "/README.md", to: stagingDir + "/README.md", transport: transport)
+        try copyFromHermes(plan.projectDir + "/AGENTS.md", to: stagingDir + "/AGENTS.md", transport: transport)
+
+        // Optional per-agent instruction shims
+        for relative in plan.instructionFiles {
+            let source = plan.projectDir + "/" + relative
+            let destination = stagingDir + "/instructions/" + relative
+            try createParent(of: destination)
+            try copyFromHermes(source, to: destination, transport: transport)
+        }
+
+        // Skills (copied from the global skills dir)
+        if !plan.skillIds.isEmpty {
+            let skillsRoot = stagingDir + "/skills"
+            try FileManager.default.createDirectory(atPath: skillsRoot, withIntermediateDirectories: true)
+            let allSkills = HermesFileService(context: context).loadSkills()
+                .flatMap(\.skills)
+            for skillId in plan.skillIds {
+                guard let skill = allSkills.first(where: { $0.id == skillId }) else {
+                    throw ProjectTemplateError.requiredFileMissing("skills/" + skillId)
+                }
+                // The bundle uses a flat `skills/<name>/` layout (no
+                // category), matching what the installer expects. If two
+                // categories ship skills with the same `name`, the second
+                // collides — warn by refusing rather than silently
+                // overwriting.
+                let targetDir = skillsRoot + "/" + skill.name
+                if FileManager.default.fileExists(atPath: targetDir) {
+                    throw ProjectTemplateError.conflictingFile(targetDir)
+                }
+                try FileManager.default.createDirectory(atPath: targetDir, withIntermediateDirectories: true)
+                for file in skill.files {
+                    try copyFromHermes(skill.path + "/" + file, to: targetDir + "/" + file, transport: transport)
+                }
+            }
+        }
+
+        // Cron jobs (stripped to the create-CLI-shaped spec)
+        if !plan.cronJobs.isEmpty {
+            let specs = plan.cronJobs.map { Self.strip($0) }
+            let encoder = JSONEncoder()
+            encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+            let data = try encoder.encode(specs)
+            let cronDir = stagingDir + "/cron"
+            try FileManager.default.createDirectory(atPath: cronDir, withIntermediateDirectories: true)
+            try data.write(to: URL(fileURLWithPath: cronDir + "/jobs.json"))
+        }
+
+        // Memory appendix. A write failure here would silently produce a
+        // bundle whose manifest claims `memory.append = true` but ships an
+        // empty/missing file — installers would then fail on
+        // contentClaimMismatch with no breadcrumb pointing back at the
+        // export step. Let the error propagate.
+        if let appendix = plan.memoryAppendix, !appendix.isEmpty {
+            let memDir = stagingDir + "/memory"
+            try FileManager.default.createDirectory(atPath: memDir, withIntermediateDirectories: true)
+            guard let data = appendix.data(using: .utf8) else {
+                throw ProjectTemplateError.requiredFileMissing("memory/append.md (non-UTF8)")
+            }
+            try data.write(to: URL(fileURLWithPath: memDir + "/append.md"))
+        }
+
+        // If the source project was itself installed from a schemaful
+        // template, its `.scarf/manifest.json` carries the schema we
+        // want to forward to the exported bundle. We carry only the
+        // SCHEMA — never user values. Exporting must be safe on a
+        // project with live config: the schema is author-supplied
+        // metadata; the values in `config.json` are the current user's
+        // secrets or personal settings.
+        let forwardedSchema: TemplateConfigSchema? = try Self.readCachedSchema(
+            from: plan.projectDir
+        )
+
+        // Bump schemaVersion to 2 when a schema is carried through;
+        // remain on 1 otherwise so schema-less exports stay
+        // byte-compatible with existing v2.2 catalog validators.
+        let schemaVersion = forwardedSchema == nil ? 1 : 2
+
+        // Manifest — claims exactly what we just wrote
+        let manifest = ProjectTemplateManifest(
+            schemaVersion: schemaVersion,
+            id: inputs.templateId,
+            name: inputs.templateName,
+            version: inputs.templateVersion,
+            minScarfVersion: nil,
+            minHermesVersion: nil,
+            author: inputs.authorName.map {
+                TemplateAuthor(name: $0, url: inputs.authorUrl)
+            },
+            description: inputs.description,
+            category: inputs.category,
+            tags: inputs.tags.isEmpty ? nil : inputs.tags,
+            icon: nil,
+            screenshots: nil,
+            contents: TemplateContents(
+                dashboard: true,
+                agentsMd: true,
+                instructions: plan.instructionFiles.isEmpty ? nil : plan.instructionFiles,
+                skills: plan.skillIds.isEmpty ? nil : plan.skillIds.compactMap { $0.split(separator: "/").last.map(String.init) },
+                cron: plan.cronJobs.isEmpty ? nil : plan.cronJobs.count,
+                memory: (inputs.memoryAppendix?.isEmpty == false) ? TemplateMemoryClaim(append: true) : nil,
+                config: forwardedSchema?.fields.count
+            ),
+            config: forwardedSchema
+        )
+        let manifestEncoder = JSONEncoder()
+        manifestEncoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        let manifestData = try manifestEncoder.encode(manifest)
+        try manifestData.write(to: URL(fileURLWithPath: stagingDir + "/template.json"))
+
+        try zip(stagingDir: stagingDir, outputPath: outputZipPath)
+    }
+
+    // MARK: - Private
+
+    /// Copy a file whose source lives on the Hermes side (possibly remote)
+    /// into a local destination path under the staging dir. Using the
+    /// transport for the read keeps the exporter remote-ready; the write
+    /// goes through Foundation because the staging dir is always local to
+    /// the Mac running Scarf.
+    nonisolated private func copyFromHermes(
+        _ source: String,
+        to destination: String,
+        transport: any ServerTransport
+    ) throws {
+        let data = try transport.readFile(source)
+        try createParent(of: destination)
+        try data.write(to: URL(fileURLWithPath: destination))
+    }
+
+    nonisolated private func createParent(of path: String) throws {
+        let parent = (path as NSString).deletingLastPathComponent
+        if !FileManager.default.fileExists(atPath: parent) {
+            try FileManager.default.createDirectory(atPath: parent, withIntermediateDirectories: true)
+        }
+    }
+
+    /// Read the cached manifest from `<project>/.scarf/manifest.json` (if
+    /// present) and pull out just the config schema. Values in
+    /// `.scarf/config.json` are intentionally ignored — an exported
+    /// bundle carries the schema's shape, never the current user's
+    /// configured values.
+    nonisolated private static func readCachedSchema(from projectDir: String) throws -> TemplateConfigSchema? {
+        let manifestPath = projectDir + "/.scarf/manifest.json"
+        guard FileManager.default.fileExists(atPath: manifestPath) else { return nil }
+        let data = try Data(contentsOf: URL(fileURLWithPath: manifestPath))
+        // Use a bespoke decode rather than ProjectTemplateManifest so
+        // this helper stays resilient if the manifest shape evolves
+        // incompatibly in a future release.
+        struct OnlyConfig: Decodable { let config: TemplateConfigSchema? }
+        let onlyConfig = try JSONDecoder().decode(OnlyConfig.self, from: data)
+        return onlyConfig.config
+    }
+
+    /// Convert a live cron job (with runtime state) into the spec the
+    /// installer will feed back to `hermes cron create`. Only preserves
+    /// fields the CLI accepts.
+    nonisolated private static func strip(_ job: HermesCronJob) -> TemplateCronJobSpec {
+        let schedule: String = {
+            if let expr = job.schedule.expression, !expr.isEmpty { return expr }
+            if let runAt = job.schedule.runAt, !runAt.isEmpty { return runAt }
+            return job.schedule.display ?? ""
+        }()
+        return TemplateCronJobSpec(
+            name: job.name,
+            schedule: schedule,
+            prompt: job.prompt.isEmpty ? nil : job.prompt,
+            deliver: job.deliver?.isEmpty == false ? job.deliver : nil,
+            skills: (job.skills?.isEmpty == false) ? job.skills : nil,
+            repeatCount: nil
+        )
+    }
+
+    /// Shell out to `/usr/bin/zip -r` so the file ordering is deterministic
+    /// and the archive is standard — Apple-provided tools (and the system
+    /// `unzip` the installer uses) will read it without trouble.
+    nonisolated private func zip(stagingDir: String, outputPath: String) throws {
+        // `zip` writes relative paths based on the cwd it's invoked in. Chdir
+        // via Process.currentDirectoryURL so entries are `template.json`,
+        // `AGENTS.md`, etc., not absolute paths.
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/usr/bin/zip")
+        process.currentDirectoryURL = URL(fileURLWithPath: stagingDir)
+        process.arguments = ["-qq", "-r", outputPath, "."]
+
+        let outPipe = Pipe()
+        let errPipe = Pipe()
+        process.standardOutput = outPipe
+        process.standardError = errPipe
+
+        // Close both ends of each Pipe so we don't leak 4 fds per zip call.
+        func closePipes() {
+            try? outPipe.fileHandleForReading.close()
+            try? outPipe.fileHandleForWriting.close()
+            try? errPipe.fileHandleForReading.close()
+            try? errPipe.fileHandleForWriting.close()
+        }
+
+        do {
+            try process.run()
+        } catch {
+            closePipes()
+            throw ProjectTemplateError.unzipFailed("zip failed to launch: \(error.localizedDescription)")
+        }
+        process.waitUntilExit()
+        let errData = try? errPipe.fileHandleForReading.readToEnd()
+        closePipes()
+
+        guard process.terminationStatus == 0 else {
+            let err = errData.flatMap { String(data: $0, encoding: .utf8) } ?? ""
+            throw ProjectTemplateError.unzipFailed(err.isEmpty ? "exit \(process.terminationStatus)" : err)
+        }
+    }
+}

scarf/scarf/Core/Services/ProjectTemplateInstaller.swift

@@ -0,0 +1,303 @@
+import Foundation
+import os
+
+/// Executes a `TemplateInstallPlan`. All writes happen in one pass with
+/// early-fail semantics: if any step throws, later steps don't run (but
+/// earlier ones aren't reversed — v1 doesn't ship an atomic rollback). The
+/// plan has already verified `projectDir` doesn't exist and no conflicting
+/// file exists at target paths, so by the time we start writing, the
+/// expected-error surface is small (mostly I/O failures).
+struct ProjectTemplateInstaller: Sendable {
+    private static let logger = Logger(subsystem: "com.scarf", category: "ProjectTemplateInstaller")
+
+    let context: ServerContext
+
+    nonisolated init(context: ServerContext = .local) {
+        self.context = context
+    }
+
+    /// Apply the plan. On success, returns the `ProjectEntry` that was added
+    /// to the registry so the caller can set `AppCoordinator.selectedProjectName`.
+    @discardableResult
+    nonisolated func install(plan: TemplateInstallPlan) throws -> ProjectEntry {
+        try preflight(plan: plan)
+        try createProjectFiles(plan: plan)
+        try createSkillsFiles(plan: plan)
+        try appendMemoryIfNeeded(plan: plan)
+        let cronJobNames = try createCronJobs(plan: plan)
+        let entry = try registerProject(plan: plan)
+        try writeLockFile(plan: plan, cronJobNames: cronJobNames)
+        Self.logger.info("installed template \(plan.manifest.id, privacy: .public) v\(plan.manifest.version, privacy: .public) into \(plan.projectDir, privacy: .public)")
+        return entry
+    }
+
+    // MARK: - Preflight
+
+    nonisolated private func preflight(plan: TemplateInstallPlan) throws {
+        // Plan was built on a recent snapshot of the filesystem; re-check the
+        // invariants at install time so concurrent activity between
+        // preview-and-confirm can't slip past us.
+        //
+        // All existence and read checks for paths that come from
+        // `context.paths` go through the transport — not `FileManager` —
+        // so this code works identically against a future remote
+        // `ServerContext`. See the warning on `ServerContext.readText`:
+        // "Foundation file APIs are LOCAL ONLY — using them with a remote
+        // path silently returns nil because the remote path doesn't exist
+        // on this Mac."
+        let transport = context.makeTransport()
+        if transport.fileExists(plan.projectDir) {
+            throw ProjectTemplateError.projectDirExists(plan.projectDir)
+        }
+        for copy in plan.projectFiles where transport.fileExists(copy.destinationPath) {
+            throw ProjectTemplateError.conflictingFile(copy.destinationPath)
+        }
+        for copy in plan.skillsFiles where transport.fileExists(copy.destinationPath) {
+            throw ProjectTemplateError.conflictingFile(copy.destinationPath)
+        }
+        // Memory appendix collision: re-scan MEMORY.md for an existing block
+        // with the same template id so two installs of v1.0.0 can't
+        // double-append. A missing MEMORY.md is fine (treated as empty),
+        // but any *other* read failure (permissions, bad file type) gets
+        // logged + surfaced so we don't silently pretend MEMORY.md is empty
+        // and append over a broken file.
+        if plan.memoryAppendix != nil {
+            let existing: String
+            if transport.fileExists(plan.memoryPath) {
+                do {
+                    let data = try transport.readFile(plan.memoryPath)
+                    existing = String(data: data, encoding: .utf8) ?? ""
+                } catch {
+                    Self.logger.error("failed to read MEMORY.md at \(plan.memoryPath, privacy: .public): \(error.localizedDescription, privacy: .public)")
+                    throw error
+                }
+            } else {
+                existing = ""
+            }
+            let marker = ProjectTemplateService.memoryBlockBeginMarker(templateId: plan.manifest.id)
+            if existing.contains(marker) {
+                throw ProjectTemplateError.memoryBlockAlreadyExists(plan.manifest.id)
+            }
+        }
+    }
+
+    // MARK: - Project files
+
+    nonisolated private func createProjectFiles(plan: TemplateInstallPlan) throws {
+        let transport = context.makeTransport()
+        try transport.createDirectory(plan.projectDir)
+        for copy in plan.projectFiles {
+            let parent = (copy.destinationPath as NSString).deletingLastPathComponent
+            try transport.createDirectory(parent)
+
+            // Empty `sourceRelativePath` is the "synthesized content"
+            // sentinel used by `buildPlan` for `.scarf/config.json`.
+            // The installer materialises config.json from
+            // `plan.configValues` here rather than copying a bundle
+            // file that doesn't exist.
+            if copy.sourceRelativePath.isEmpty {
+                if copy.destinationPath.hasSuffix("/.scarf/config.json") {
+                    let data = try encodeConfigFile(plan: plan)
+                    try transport.writeFile(copy.destinationPath, data: data)
+                    continue
+                }
+                throw ProjectTemplateError.requiredFileMissing(
+                    "synthesized file with unknown destination: \(copy.destinationPath)"
+                )
+            }
+
+            let source = plan.unpackedDir + "/" + copy.sourceRelativePath
+            let data = try Data(contentsOf: URL(fileURLWithPath: source))
+            try transport.writeFile(copy.destinationPath, data: data)
+        }
+    }
+
+    /// Serialise `plan.configValues` into the `<project>/.scarf/config.json`
+    /// shape. Secrets appear as `keychainRef` URIs — the raw bytes were
+    /// routed into the Keychain by the VM before `install()` was called.
+    nonisolated private func encodeConfigFile(plan: TemplateInstallPlan) throws -> Data {
+        let file = ProjectConfigFile(
+            schemaVersion: 2,
+            templateId: plan.manifest.id,
+            values: plan.configValues,
+            updatedAt: ISO8601DateFormatter().string(from: Date())
+        )
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        return try encoder.encode(file)
+    }
+
+    // MARK: - Skills
+
+    nonisolated private func createSkillsFiles(plan: TemplateInstallPlan) throws {
+        guard let namespaceDir = plan.skillsNamespaceDir else { return }
+        let transport = context.makeTransport()
+        try transport.createDirectory(namespaceDir)
+        for copy in plan.skillsFiles {
+            let source = plan.unpackedDir + "/" + copy.sourceRelativePath
+            let data = try Data(contentsOf: URL(fileURLWithPath: source))
+            let parent = (copy.destinationPath as NSString).deletingLastPathComponent
+            try transport.createDirectory(parent)
+            try transport.writeFile(copy.destinationPath, data: data)
+        }
+    }
+
+    // MARK: - Memory
+
+    nonisolated private func appendMemoryIfNeeded(plan: TemplateInstallPlan) throws {
+        guard let appendix = plan.memoryAppendix else { return }
+        let transport = context.makeTransport()
+        let existing = (try? transport.readFile(plan.memoryPath)).flatMap { String(data: $0, encoding: .utf8) } ?? ""
+        let combined = existing + appendix
+        guard let data = combined.data(using: .utf8) else {
+            throw ProjectTemplateError.requiredFileMissing("memory/append.md (non-UTF8)")
+        }
+        let parent = (plan.memoryPath as NSString).deletingLastPathComponent
+        try transport.createDirectory(parent)
+        try transport.writeFile(plan.memoryPath, data: data)
+    }
+
+    // MARK: - Cron
+
+    /// Create each cron job via `hermes cron create`, then immediately pause
+    /// it (Hermes creates jobs enabled). Returns the list of resolved job
+    /// names, which is what the lock file records — we don't know the job
+    /// ids without parsing the create output, but the name is enough to
+    /// find + remove them later.
+    nonisolated private func createCronJobs(plan: TemplateInstallPlan) throws -> [String] {
+        guard !plan.cronJobs.isEmpty else { return [] }
+
+        let existingBefore = Set(HermesFileService(context: context).loadCronJobs().map(\.id))
+        var createdNames: [String] = []
+
+        for job in plan.cronJobs {
+            var args = ["cron", "create", "--name", job.name]
+            if let deliver = job.deliver, !deliver.isEmpty { args += ["--deliver", deliver] }
+            if let repeatCount = job.repeatCount { args += ["--repeat", String(repeatCount)] }
+            for skill in job.skills ?? [] where !skill.isEmpty {
+                args += ["--skill", skill]
+            }
+            args.append(job.schedule)
+            if let prompt = job.prompt, !prompt.isEmpty {
+                // Substitute template-author tokens with install-time
+                // values. Hermes doesn't set a CWD for cron runs — when
+                // the agent fires the prompt, any relative path
+                // (`.scarf/config.json`, `status-log.md`, etc.) resolves
+                // against the agent's own dir, not the project. Templates
+                // use `{{PROJECT_DIR}}` as a placeholder for the absolute
+                // path; we swap in the real project dir here so the
+                // registered cron job carries a fully-qualified prompt
+                // that works regardless of CWD.
+                let resolvedPrompt = Self.substituteCronTokens(prompt, plan: plan)
+                args.append(resolvedPrompt)
+            }
+
+            let (output, exit) = context.runHermes(args)
+            guard exit == 0 else {
+                throw ProjectTemplateError.cronCreateFailed(job: job.name, output: output)
+            }
+            createdNames.append(job.name)
+        }
+
+        // Diff the current job set against the snapshot we took before
+        // creating — anything new belongs to this install and gets paused.
+        // We pause by id (not name) because `cron pause` takes an id.
+        let currentJobs = HermesFileService(context: context).loadCronJobs()
+        let newJobs = currentJobs.filter { !existingBefore.contains($0.id) && createdNames.contains($0.name) }
+        for job in newJobs {
+            let (_, exit) = context.runHermes(["cron", "pause", job.id])
+            if exit != 0 {
+                Self.logger.warning("couldn't pause newly-created cron job \(job.id, privacy: .public) — leaving enabled")
+            }
+        }
+
+        return createdNames
+    }
+
+    // MARK: - Registry
+
+    nonisolated private func registerProject(plan: TemplateInstallPlan) throws -> ProjectEntry {
+        let service = ProjectDashboardService(context: context)
+        var registry = service.loadRegistry()
+        let entry = ProjectEntry(name: plan.projectRegistryName, path: plan.projectDir)
+        registry.projects.append(entry)
+        // Must throw on failure — silent failure here used to make the
+        // installer return a valid entry while the registry on disk
+        // never got updated, producing the "install completed but the
+        // project doesn't show up in the sidebar" bug. If the registry
+        // write fails, the whole install is surfaced as failed so the
+        // user can see + address the underlying problem.
+        try service.saveRegistry(registry)
+        return entry
+    }
+
+    // MARK: - Token substitution (install-time placeholder resolution)
+
+    /// Supported placeholders for template-author prompts. Keep the set
+    /// intentionally small — every token here becomes a load-bearing
+    /// part of the template format that we can't rename without
+    /// breaking existing bundles.
+    ///
+    /// - `{{PROJECT_DIR}}`: absolute path of the newly-created project
+    ///   directory. Required for cron prompts because Hermes doesn't
+    ///   establish a CWD when firing cron jobs; relative paths would
+    ///   resolve against whatever dir Hermes happens to be in.
+    ///
+    /// - `{{TEMPLATE_ID}}`: the `owner/name` id from the manifest.
+    ///   Less load-bearing; occasionally useful for tagging or
+    ///   delivery targets that reference the template.
+    ///
+    /// - `{{TEMPLATE_SLUG}}`: the sanitised slug the installer used
+    ///   for the skills namespace and project dir name.
+    nonisolated static func substituteCronTokens(
+        _ prompt: String,
+        plan: TemplateInstallPlan
+    ) -> String {
+        var out = prompt
+        out = out.replacingOccurrences(of: "{{PROJECT_DIR}}", with: plan.projectDir)
+        out = out.replacingOccurrences(of: "{{TEMPLATE_ID}}", with: plan.manifest.id)
+        out = out.replacingOccurrences(of: "{{TEMPLATE_SLUG}}", with: plan.manifest.slug)
+        return out
+    }
+
+    // MARK: - Lock file
+
+    nonisolated private func writeLockFile(
+        plan: TemplateInstallPlan,
+        cronJobNames: [String]
+    ) throws {
+        // Every value that ended up as a keychainRef in config.json gets
+        // tracked in the lock so the uninstaller can SecItemDelete each
+        // entry. Field keys are recorded separately for informational
+        // display in the uninstall preview sheet.
+        let keychainItems: [String]? = {
+            let refs = plan.configValues.compactMap { (_, value) -> String? in
+                if case .keychainRef(let uri) = value { return uri } else { return nil }
+            }
+            return refs.isEmpty ? nil : refs.sorted()
+        }()
+        let configFields: [String]? = {
+            guard let schema = plan.configSchema, !schema.isEmpty else { return nil }
+            return schema.fields.map(\.key)
+        }()
+
+        let lock = TemplateLock(
+            templateId: plan.manifest.id,
+            templateVersion: plan.manifest.version,
+            templateName: plan.manifest.name,
+            installedAt: ISO8601DateFormatter().string(from: Date()),
+            projectFiles: plan.projectFiles.map(\.destinationPath),
+            skillsNamespaceDir: plan.skillsNamespaceDir,
+            skillsFiles: plan.skillsFiles.map(\.destinationPath),
+            cronJobNames: cronJobNames,
+            memoryBlockId: plan.memoryAppendix == nil ? nil : plan.manifest.id,
+            configKeychainItems: keychainItems,
+            configFields: configFields
+        )
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        let data = try encoder.encode(lock)
+        let path = plan.projectDir + "/.scarf/template.lock.json"
+        try context.makeTransport().writeFile(path, data: data)
+    }
+}

scarf/scarf/Core/Services/ProjectTemplateService.swift

@@ -0,0 +1,500 @@
+import Foundation
+import os
+
+/// Reads, validates, and plans the install of a `.scarftemplate` bundle. Pure
+/// — owns no state across calls. The installer (see
+/// `ProjectTemplateInstaller`) consumes the `TemplateInstallPlan` this
+/// produces.
+///
+/// Responsibilities:
+/// 1. Unpack a `.scarftemplate` zip into a caller-owned temp directory.
+/// 2. Parse `template.json` and validate it against the schema we know about.
+/// 3. Walk the unpacked contents and verify they match the manifest's
+///    `contents` claim (so a malicious bundle can't hide files from the
+///    preview sheet).
+/// 4. Produce a `TemplateInstallPlan` describing every concrete filesystem
+///    op the installer will perform, given a parent directory the user
+///    picked.
+struct ProjectTemplateService: Sendable {
+    private static let logger = Logger(subsystem: "com.scarf", category: "ProjectTemplateService")
+
+    let context: ServerContext
+
+    nonisolated init(context: ServerContext = .local) {
+        self.context = context
+    }
+
+    // MARK: - Inspection
+
+    /// Unpack the zip at `zipPath` into a fresh temp directory, parse and
+    /// validate the manifest, and walk the contents. Throws on any
+    /// inconsistency. On success, the caller owns `inspection.unpackedDir`
+    /// and must remove it once they're done.
+    nonisolated func inspect(zipPath: String) throws -> TemplateInspection {
+        let unpackedDir = try makeTempDir()
+        try unzip(zipPath: zipPath, intoDir: unpackedDir)
+
+        let manifestPath = unpackedDir + "/template.json"
+        guard FileManager.default.fileExists(atPath: manifestPath) else {
+            throw ProjectTemplateError.manifestMissing
+        }
+
+        let manifestData: Data
+        do {
+            manifestData = try Data(contentsOf: URL(fileURLWithPath: manifestPath))
+        } catch {
+            throw ProjectTemplateError.manifestParseFailed(error.localizedDescription)
+        }
+        let manifest: ProjectTemplateManifest
+        do {
+            manifest = try JSONDecoder().decode(ProjectTemplateManifest.self, from: manifestData)
+        } catch {
+            throw ProjectTemplateError.manifestParseFailed(error.localizedDescription)
+        }
+
+        // schemaVersion 1 is the original v2.2 bundle; 2 adds the
+        // optional `config` block. Both are valid. Newer versions get
+        // refused so the installer never silently misinterprets a
+        // future-shape bundle.
+        guard manifest.schemaVersion == 1 || manifest.schemaVersion == 2 else {
+            throw ProjectTemplateError.unsupportedSchemaVersion(manifest.schemaVersion)
+        }
+
+        // Validate the optional config schema at inspect time — a
+        // malformed schema (duplicate keys, secret-with-default, etc.)
+        // gets rejected before the user ever sees the preview sheet.
+        if let schema = manifest.config {
+            do {
+                try ProjectConfigService.validateSchema(schema)
+            } catch {
+                throw ProjectTemplateError.manifestParseFailed(
+                    "invalid config schema: \(error.localizedDescription)"
+                )
+            }
+        }
+
+        let files = try Self.walk(unpackedDir)
+        let cronJobs = try Self.readCronJobs(unpackedDir: unpackedDir)
+        try Self.verifyClaims(manifest: manifest, files: files, cronJobCount: cronJobs.count)
+
+        return TemplateInspection(
+            manifest: manifest,
+            unpackedDir: unpackedDir,
+            files: files,
+            cronJobs: cronJobs
+        )
+    }
+
+    // MARK: - Planning
+
+    /// Turn an inspection into a concrete install plan given the parent
+    /// directory the user picked. The plan is deterministic — two calls with
+    /// the same inputs produce the same ops.
+    nonisolated func buildPlan(
+        inspection: TemplateInspection,
+        parentDir: String
+    ) throws -> TemplateInstallPlan {
+        let manifest = inspection.manifest
+        let slug = manifest.slug
+        let projectDir = parentDir + "/" + slug
+
+        if FileManager.default.fileExists(atPath: projectDir) {
+            throw ProjectTemplateError.projectDirExists(projectDir)
+        }
+
+        var projectFiles: [TemplateFileCopy] = [
+            TemplateFileCopy(
+                sourceRelativePath: "README.md",
+                destinationPath: projectDir + "/README.md"
+            ),
+            TemplateFileCopy(
+                sourceRelativePath: "AGENTS.md",
+                destinationPath: projectDir + "/AGENTS.md"
+            ),
+            TemplateFileCopy(
+                sourceRelativePath: "dashboard.json",
+                destinationPath: projectDir + "/.scarf/dashboard.json"
+            )
+        ]
+
+        // Optional per-agent instruction shims. Each is copied verbatim to
+        // its conventional project-root path; we don't try to be clever.
+        let instructionRoot = "instructions"
+        for relative in (manifest.contents.instructions ?? []) {
+            let source = instructionRoot + "/" + relative
+            guard inspection.files.contains(source) else {
+                throw ProjectTemplateError.requiredFileMissing(source)
+            }
+            projectFiles.append(
+                TemplateFileCopy(
+                    sourceRelativePath: source,
+                    destinationPath: projectDir + "/" + relative
+                )
+            )
+        }
+
+        // Namespaced skills: copied wholesale from skills/<name>/** into
+        // ~/.hermes/skills/templates/<slug>/<name>/**.
+        var skillsFiles: [TemplateFileCopy] = []
+        var skillsNamespaceDir: String? = nil
+        if let skillNames = manifest.contents.skills, !skillNames.isEmpty {
+            let namespaceDir = context.paths.skillsDir + "/templates/" + slug
+            skillsNamespaceDir = namespaceDir
+            for skillName in skillNames {
+                let prefix = "skills/" + skillName + "/"
+                let skillFiles = inspection.files.filter { $0.hasPrefix(prefix) }
+                guard !skillFiles.isEmpty else {
+                    throw ProjectTemplateError.requiredFileMissing(prefix)
+                }
+                for relative in skillFiles {
+                    let suffix = String(relative.dropFirst("skills/".count))
+                    skillsFiles.append(
+                        TemplateFileCopy(
+                            sourceRelativePath: relative,
+                            destinationPath: namespaceDir + "/" + suffix
+                        )
+                    )
+                }
+            }
+        }
+
+        // Cron jobs: always prefix name with the template tag so users can
+        // find and remove them later. Jobs ship disabled — the installer
+        // pauses each one immediately after `cron create`.
+        let cronJobs: [TemplateCronJobSpec] = inspection.cronJobs.map { job in
+            TemplateCronJobSpec(
+                name: "[tmpl:\(manifest.id)] \(job.name)",
+                schedule: job.schedule,
+                prompt: job.prompt,
+                deliver: job.deliver,
+                skills: job.skills,
+                repeatCount: job.repeatCount
+            )
+        }
+
+        // Memory appendix: wrap whatever the template ships in
+        // begin/end markers so an uninstall can find and remove exactly the
+        // bytes this template added. `verifyClaims` already guaranteed the
+        // file is present — so a read error here means something unusual
+        // (permissions, encoding, etc.); surface it with the real
+        // `error.localizedDescription` rather than hiding behind a
+        // generic "file missing."
+        var memoryAppendix: String? = nil
+        if manifest.contents.memory?.append == true {
+            let appendSource = inspection.unpackedDir + "/memory/append.md"
+            let raw: String
+            do {
+                raw = try String(contentsOf: URL(fileURLWithPath: appendSource), encoding: .utf8)
+            } catch {
+                Self.logger.error("failed to read memory/append.md in unpacked bundle: \(error.localizedDescription, privacy: .public)")
+                throw ProjectTemplateError.manifestParseFailed("memory/append.md: \(error.localizedDescription)")
+            }
+            memoryAppendix = Self.wrapMemoryBlock(
+                templateId: manifest.id,
+                templateVersion: manifest.version,
+                body: raw.trimmingCharacters(in: .whitespacesAndNewlines)
+            )
+        }
+
+        // Configuration schema + manifest cache. The installer writes
+        // `.scarf/config.json` (non-secret values) + `.scarf/manifest.json`
+        // (schema cache used by the post-install editor) when the
+        // template declares a non-empty schema. Both paths go into
+        // projectFiles so the uninstaller picks them up via the lock.
+        var configSchema: TemplateConfigSchema? = nil
+        var manifestCachePath: String? = nil
+        if let schema = manifest.config, !schema.isEmpty {
+            configSchema = schema
+            let configPath = projectDir + "/.scarf/config.json"
+            projectFiles.append(
+                // Source is synthesized by the installer from configValues;
+                // no file in the unpacked bundle maps to this entry. We use
+                // an empty `sourceRelativePath` as the "no physical source"
+                // sentinel — the installer special-cases it below (see
+                // ProjectTemplateInstaller.createProjectFiles).
+                TemplateFileCopy(
+                    sourceRelativePath: "",
+                    destinationPath: configPath
+                )
+            )
+            let cachePath = projectDir + "/.scarf/manifest.json"
+            manifestCachePath = cachePath
+            projectFiles.append(
+                TemplateFileCopy(
+                    sourceRelativePath: "template.json",
+                    destinationPath: cachePath
+                )
+            )
+        }
+
+        return TemplateInstallPlan(
+            manifest: manifest,
+            unpackedDir: inspection.unpackedDir,
+            projectDir: projectDir,
+            projectFiles: projectFiles,
+            skillsNamespaceDir: skillsNamespaceDir,
+            skillsFiles: skillsFiles,
+            cronJobs: cronJobs,
+            memoryAppendix: memoryAppendix,
+            memoryPath: context.paths.memoryMD,
+            projectRegistryName: Self.uniqueProjectName(preferred: manifest.name, context: context),
+            configSchema: configSchema,
+            configValues: [:],   // filled in by TemplateInstallerViewModel before install()
+            manifestCachePath: manifestCachePath
+        )
+    }
+
+    // MARK: - Cleanup
+
+    /// Remove a temp dir created by `inspect`. Safe to call if it already
+    /// doesn't exist (install or cancel flows both end here).
+    nonisolated func cleanupTempDir(_ path: String) {
+        try? FileManager.default.removeItem(atPath: path)
+    }
+
+    // MARK: - Memory block helpers (installer + future uninstaller share these)
+
+    nonisolated static func memoryBlockBeginMarker(templateId: String) -> String {
+        "<!-- scarf-template:\(templateId):begin -->"
+    }
+
+    nonisolated static func memoryBlockEndMarker(templateId: String) -> String {
+        "<!-- scarf-template:\(templateId):end -->"
+    }
+
+    nonisolated static func wrapMemoryBlock(
+        templateId: String,
+        templateVersion: String,
+        body: String
+    ) -> String {
+        let begin = memoryBlockBeginMarker(templateId: templateId)
+        let end = memoryBlockEndMarker(templateId: templateId)
+        return "\n\n\(begin) v\(templateVersion)\n\(body)\n\(end)\n"
+    }
+
+    // MARK: - Private
+
+    private nonisolated func makeTempDir() throws -> String {
+        let base = NSTemporaryDirectory() + "scarf-template-" + UUID().uuidString
+        try FileManager.default.createDirectory(
+            atPath: base,
+            withIntermediateDirectories: true
+        )
+        return base
+    }
+
+    /// Shell out to `/usr/bin/unzip` — matches the existing profile-export
+    /// pattern (`hermes profile import` shells to `unzip`) and avoids
+    /// pulling in a third-party zip library.
+    private nonisolated func unzip(zipPath: String, intoDir: String) throws {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/usr/bin/unzip")
+        process.arguments = ["-qq", "-o", zipPath, "-d", intoDir]
+
+        let outPipe = Pipe()
+        let errPipe = Pipe()
+        process.standardOutput = outPipe
+        process.standardError = errPipe
+
+        // Foundation dup()s these handles into the child on `run()`, but the
+        // parent copies stay open until explicitly released. Both ends must
+        // be closed or each Process spawn leaks 4 fds.
+        func closePipes() {
+            try? outPipe.fileHandleForReading.close()
+            try? outPipe.fileHandleForWriting.close()
+            try? errPipe.fileHandleForReading.close()
+            try? errPipe.fileHandleForWriting.close()
+        }
+
+        do {
+            try process.run()
+        } catch {
+            closePipes()
+            throw ProjectTemplateError.unzipFailed(error.localizedDescription)
+        }
+        process.waitUntilExit()
+        let errData = try? errPipe.fileHandleForReading.readToEnd()
+        closePipes()
+
+        guard process.terminationStatus == 0 else {
+            let err = errData.flatMap { String(data: $0, encoding: .utf8) } ?? ""
+            throw ProjectTemplateError.unzipFailed(err.isEmpty ? "exit \(process.terminationStatus)" : err)
+        }
+    }
+
+    /// Recursively walk `dir` and return every file (not directory) as a
+    /// path relative to `dir`. Skips symlinks entirely — templates should
+    /// never contain them, and following them could escape the unpack dir.
+    ///
+    /// Both the base dir and the enumerated URLs are resolved via
+    /// `resolvingSymlinksInPath` before comparison. On macOS, temp dirs
+    /// under `/var/folders/…` resolve to `/private/var/folders/…`, so a
+    /// naive string-prefix check would produce malformed relative paths
+    /// when the base is unresolved but enumerated URLs are resolved.
+    nonisolated private static func walk(_ dir: String) throws -> [String] {
+        var results: [String] = []
+        let baseURL = URL(fileURLWithPath: dir).resolvingSymlinksInPath()
+        let basePath = baseURL.path.hasSuffix("/") ? baseURL.path : baseURL.path + "/"
+        let enumerator = FileManager.default.enumerator(
+            at: baseURL,
+            includingPropertiesForKeys: [.isRegularFileKey, .isSymbolicLinkKey],
+            options: [.skipsHiddenFiles]
+        )
+        while let url = enumerator?.nextObject() as? URL {
+            let values = try url.resourceValues(forKeys: [.isRegularFileKey, .isSymbolicLinkKey])
+            if values.isSymbolicLink == true {
+                throw ProjectTemplateError.unsafeZipEntry(url.path)
+            }
+            guard values.isRegularFile == true else { continue }
+            var full = url.resolvingSymlinksInPath().path
+            if full.hasPrefix(basePath) {
+                full.removeFirst(basePath.count)
+            }
+            if full.contains("..") {
+                throw ProjectTemplateError.unsafeZipEntry(full)
+            }
+            results.append(full)
+        }
+        return results
+    }
+
+    nonisolated private static func readCronJobs(unpackedDir: String) throws -> [TemplateCronJobSpec] {
+        let path = unpackedDir + "/cron/jobs.json"
+        guard FileManager.default.fileExists(atPath: path) else { return [] }
+        let data: Data
+        do {
+            data = try Data(contentsOf: URL(fileURLWithPath: path))
+        } catch {
+            throw ProjectTemplateError.requiredFileMissing("cron/jobs.json")
+        }
+        do {
+            return try JSONDecoder().decode([TemplateCronJobSpec].self, from: data)
+        } catch {
+            throw ProjectTemplateError.manifestParseFailed("cron/jobs.json: \(error.localizedDescription)")
+        }
+    }
+
+    /// Verify the manifest's `contents` claim exactly matches the unpacked
+    /// files. Any mismatch — claimed-but-missing or present-but-unclaimed —
+    /// throws, so the preview sheet the user sees is always accurate.
+    nonisolated private static func verifyClaims(
+        manifest: ProjectTemplateManifest,
+        files: [String],
+        cronJobCount: Int
+    ) throws {
+        let fileSet = Set(files)
+
+        if manifest.contents.dashboard {
+            if !fileSet.contains("dashboard.json") {
+                throw ProjectTemplateError.requiredFileMissing("dashboard.json")
+            }
+        }
+        if manifest.contents.agentsMd {
+            if !fileSet.contains("AGENTS.md") {
+                throw ProjectTemplateError.requiredFileMissing("AGENTS.md")
+            }
+        }
+        // README and AGENTS are always required; dashboard is always required
+        // per spec. `contents.dashboard`/`contents.agentsMd` exist so a future
+        // schema can relax those rules; for v1 we hard-require them regardless.
+        if !fileSet.contains("README.md") {
+            throw ProjectTemplateError.requiredFileMissing("README.md")
+        }
+        if !fileSet.contains("AGENTS.md") {
+            throw ProjectTemplateError.requiredFileMissing("AGENTS.md")
+        }
+        if !fileSet.contains("dashboard.json") {
+            throw ProjectTemplateError.requiredFileMissing("dashboard.json")
+        }
+
+        if let claimed = manifest.contents.instructions {
+            for rel in claimed {
+                let full = "instructions/" + rel
+                if !fileSet.contains(full) {
+                    throw ProjectTemplateError.contentClaimMismatch(
+                        "manifest lists \(full) but the file is missing from the bundle"
+                    )
+                }
+            }
+            let present = fileSet.filter { $0.hasPrefix("instructions/") }
+            let claimedFull = Set(claimed.map { "instructions/" + $0 })
+            if let extra = present.first(where: { !claimedFull.contains($0) }) {
+                throw ProjectTemplateError.contentClaimMismatch(
+                    "bundle contains \(extra) but it's not listed in manifest.contents.instructions"
+                )
+            }
+        } else if fileSet.contains(where: { $0.hasPrefix("instructions/") }) {
+            throw ProjectTemplateError.contentClaimMismatch(
+                "bundle has instructions/ files but manifest.contents.instructions is missing"
+            )
+        }
+
+        if let claimed = manifest.contents.skills {
+            for name in claimed {
+                let prefix = "skills/" + name + "/"
+                if !fileSet.contains(where: { $0.hasPrefix(prefix) }) {
+                    throw ProjectTemplateError.contentClaimMismatch(
+                        "manifest lists skill \(name) but skills/\(name)/ has no files"
+                    )
+                }
+            }
+            let presentSkills = Set(fileSet.compactMap { path -> String? in
+                guard path.hasPrefix("skills/") else { return nil }
+                let rest = path.dropFirst("skills/".count)
+                return rest.split(separator: "/", maxSplits: 1).first.map(String.init)
+            })
+            let claimedSet = Set(claimed)
+            if let extra = presentSkills.subtracting(claimedSet).first {
+                throw ProjectTemplateError.contentClaimMismatch(
+                    "bundle contains skills/\(extra)/ but it's not listed in manifest.contents.skills"
+                )
+            }
+        } else if fileSet.contains(where: { $0.hasPrefix("skills/") }) {
+            throw ProjectTemplateError.contentClaimMismatch(
+                "bundle contains skills/ but manifest.contents.skills is missing"
+            )
+        }
+
+        let claimedCron = manifest.contents.cron ?? 0
+        if claimedCron != cronJobCount {
+            throw ProjectTemplateError.contentClaimMismatch(
+                "manifest.contents.cron=\(claimedCron) but bundle contains \(cronJobCount) cron jobs"
+            )
+        }
+
+        let hasMemoryFile = fileSet.contains("memory/append.md")
+        let claimsMemory = manifest.contents.memory?.append == true
+        if claimsMemory != hasMemoryFile {
+            throw ProjectTemplateError.contentClaimMismatch(
+                "manifest.contents.memory.append=\(claimsMemory) disagrees with memory/append.md presence=\(hasMemoryFile)"
+            )
+        }
+
+        // Config claim must match the schema's actual field count so
+        // the preview sheet is honest about the size of the configure
+        // step. `nil` in contents means "no schema" just like `0`;
+        // we normalise both to 0 before comparing.
+        let claimedConfig = manifest.contents.config ?? 0
+        let actualConfig = manifest.config?.fields.count ?? 0
+        if claimedConfig != actualConfig {
+            throw ProjectTemplateError.contentClaimMismatch(
+                "manifest.contents.config=\(claimedConfig) but config.schema has \(actualConfig) field(s)"
+            )
+        }
+    }
+
+    /// Resolve a project-registry name that doesn't collide. Deterministic
+    /// — given the same existing registry, always returns the same answer.
+    nonisolated private static func uniqueProjectName(
+        preferred: String,
+        context: ServerContext
+    ) -> String {
+        let existing = Set(ProjectDashboardService(context: context).loadRegistry().projects.map(\.name))
+        if !existing.contains(preferred) { return preferred }
+        var i = 2
+        while existing.contains("\(preferred) \(i)") {
+            i += 1
+        }
+        return "\(preferred) \(i)"
+    }
+}

scarf/scarf/Core/Services/ProjectTemplateUninstaller.swift

@@ -0,0 +1,329 @@
+import Foundation
+import os
+
+/// Reverses the work of `ProjectTemplateInstaller`, driven by the
+/// `<project>/.scarf/template.lock.json` the installer dropped. Symmetric
+/// with the installer: `loadUninstallPlan(for:)` builds a plan the preview
+/// sheet can display honestly; `uninstall(plan:)` executes it. No hidden
+/// side effects — every path the uninstaller touches is in the plan.
+///
+/// **User-added files are preserved.** The lock records exactly what the
+/// installer wrote; any file the user created in the project dir after
+/// install (e.g. a `sites.txt` or `status-log.md` authored by the agent
+/// on first run) is listed as an "extra entry" in the plan and left on
+/// disk. If the project dir ends up empty after removing lock-tracked
+/// files, the dir itself is removed; otherwise the dir (with user content)
+/// stays.
+struct ProjectTemplateUninstaller: Sendable {
+    private static let logger = Logger(subsystem: "com.scarf", category: "ProjectTemplateUninstaller")
+
+    let context: ServerContext
+
+    nonisolated init(context: ServerContext = .local) {
+        self.context = context
+    }
+
+    // MARK: - Detection
+
+    /// Is the given project installed from a template that we can
+    /// uninstall cleanly? Cheap — just a file-existence check on the lock
+    /// path.
+    nonisolated func isTemplateInstalled(project: ProjectEntry) -> Bool {
+        context.makeTransport().fileExists(lockPath(for: project))
+    }
+
+    // MARK: - Planning
+
+    /// Read the lock file, walk the filesystem + cron list, and produce a
+    /// plan listing every op the uninstaller will perform. Does not
+    /// modify anything.
+    nonisolated func loadUninstallPlan(for project: ProjectEntry) throws -> TemplateUninstallPlan {
+        let transport = context.makeTransport()
+        let path = lockPath(for: project)
+        guard transport.fileExists(path) else {
+            throw ProjectTemplateError.lockFileMissing(path)
+        }
+        let lockData: Data
+        do {
+            lockData = try transport.readFile(path)
+        } catch {
+            throw ProjectTemplateError.lockFileParseFailed(error.localizedDescription)
+        }
+        let lock: TemplateLock
+        do {
+            lock = try JSONDecoder().decode(TemplateLock.self, from: lockData)
+        } catch {
+            throw ProjectTemplateError.lockFileParseFailed(error.localizedDescription)
+        }
+
+        // Partition tracked project files into present vs. already-gone.
+        // The lock file itself is always in `projectFiles` — the installer
+        // doesn't explicitly record it, but the preview sheet and the
+        // execute step must remove it.
+        var lockTrackedFiles = lock.projectFiles
+        lockTrackedFiles.append(path)
+        var toRemove: [String] = []
+        var alreadyGone: [String] = []
+        for file in lockTrackedFiles {
+            if transport.fileExists(file) {
+                toRemove.append(file)
+            } else {
+                alreadyGone.append(file)
+            }
+        }
+
+        // Scan the project dir for entries that AREN'T in the lock — these
+        // are user-added and we preserve them. An empty project dir (after
+        // removing lock-tracked files) gets removed too.
+        let trackedSet = Set(lockTrackedFiles)
+        let extras = try enumerateProjectDirExtras(
+            projectDir: project.path,
+            trackedPaths: trackedSet,
+            transport: transport
+        )
+        let projectDirBecomesEmpty = extras.isEmpty
+
+        // Resolve cron job ids by matching lock names against the live
+        // list. Names that no longer exist go into the already-gone bucket
+        // — the user likely removed them by hand.
+        let currentJobs = HermesFileService(context: context).loadCronJobs()
+        var cronToRemove: [(id: String, name: String)] = []
+        var cronGone: [String] = []
+        for name in lock.cronJobNames {
+            if let match = currentJobs.first(where: { $0.name == name }) {
+                cronToRemove.append((id: match.id, name: match.name))
+            } else {
+                cronGone.append(name)
+            }
+        }
+
+        // Memory block detection. The installer wraps its appendix between
+        // `<!-- scarf-template:<id>:begin -->` / `:end -->` markers; look
+        // for the begin marker in the current MEMORY.md. If it's missing
+        // (never installed, or removed by hand) we simply skip the memory
+        // strip step.
+        let memoryPath = context.paths.memoryMD
+        var memoryBlockPresent = false
+        if lock.memoryBlockId != nil {
+            if transport.fileExists(memoryPath),
+               let data = try? transport.readFile(memoryPath),
+               let text = String(data: data, encoding: .utf8) {
+                let beginMarker = ProjectTemplateService.memoryBlockBeginMarker(
+                    templateId: lock.memoryBlockId!
+                )
+                memoryBlockPresent = text.contains(beginMarker)
+            }
+        }
+
+        return TemplateUninstallPlan(
+            lock: lock,
+            project: project,
+            projectFilesToRemove: toRemove,
+            projectFilesAlreadyGone: alreadyGone,
+            extraProjectEntries: extras,
+            projectDirBecomesEmpty: projectDirBecomesEmpty,
+            skillsNamespaceDir: lock.skillsNamespaceDir,
+            cronJobsToRemove: cronToRemove,
+            cronJobsAlreadyGone: cronGone,
+            memoryBlockPresent: memoryBlockPresent,
+            memoryPath: memoryPath
+        )
+    }
+
+    // MARK: - Execution
+
+    /// Execute the plan. Non-atomic: steps run in order, and if any step
+    /// throws, later steps don't run. v1 doesn't ship rollback — the lock
+    /// file itself is only removed at the very end, so a mid-flight
+    /// failure leaves enough breadcrumbs for the user to retry or finish
+    /// by hand.
+    nonisolated func uninstall(plan: TemplateUninstallPlan) throws {
+        let transport = context.makeTransport()
+
+        // 1. Project files (tracked only — user additions untouched).
+        for file in plan.projectFilesToRemove {
+            do {
+                try transport.removeFile(file)
+            } catch {
+                Self.logger.warning("couldn't remove project file \(file, privacy: .public): \(error.localizedDescription, privacy: .public)")
+                // keep going — partial cleanup is better than bailing and
+                // leaving orphan skills/cron state
+            }
+        }
+        if plan.projectDirBecomesEmpty, transport.fileExists(plan.project.path) {
+            do {
+                try transport.removeFile(plan.project.path)
+            } catch {
+                Self.logger.warning("couldn't remove empty project dir \(plan.project.path, privacy: .public): \(error.localizedDescription, privacy: .public)")
+            }
+        }
+
+        // 2. Skills namespace dir (always removed wholesale — it's
+        // isolated, never mixed with user skills).
+        if let skillsDir = plan.skillsNamespaceDir, transport.fileExists(skillsDir) {
+            try removeRecursively(skillsDir, transport: transport)
+        }
+
+        // 3. Cron jobs via CLI — `hermes cron remove <id>`. A non-zero
+        // exit gets logged but doesn't abort the uninstall; leaving a
+        // stray cron job is better than leaving it AND the skills/memory
+        // state that was supposed to pair with it.
+        for job in plan.cronJobsToRemove {
+            let (output, exit) = context.runHermes(["cron", "remove", job.id])
+            if exit != 0 {
+                Self.logger.warning("failed to remove cron job \(job.id, privacy: .public) \(job.name, privacy: .public): \(output, privacy: .public)")
+            }
+        }
+
+        // 4. Memory block — strip the bracketed block in place. Safe
+        // when the block is absent; we already decided presence in the
+        // plan and only come here when `memoryBlockPresent` was true
+        // AND the plan recorded a memoryBlockId.
+        if plan.memoryBlockPresent, let blockId = plan.lock.memoryBlockId {
+            try stripMemoryBlock(blockId: blockId, memoryPath: plan.memoryPath, transport: transport)
+        }
+
+        // 4a. Config Keychain items — remove every secret the template's
+        // install step stashed in the login Keychain. Items that were
+        // already deleted (e.g. user cleaned them with Keychain Access)
+        // hit the `errSecItemNotFound` no-op path inside the wrapper, so
+        // a stale lock doesn't abort the rest of the uninstall.
+        let keychain = ProjectConfigKeychain()
+        for uri in plan.lock.configKeychainItems ?? [] {
+            guard let ref = TemplateKeychainRef.parse(uri) else {
+                Self.logger.warning("lock recorded unparseable keychain uri \(uri, privacy: .public); skipping")
+                continue
+            }
+            do {
+                try keychain.delete(ref: ref)
+            } catch {
+                Self.logger.warning("couldn't delete keychain item \(uri, privacy: .public): \(error.localizedDescription, privacy: .public)")
+            }
+        }
+
+        // 5. Projects registry — remove the entry by path (more stable
+        // than name: user may have renamed the project in the UI).
+        let dashboardService = ProjectDashboardService(context: context)
+        var registry = dashboardService.loadRegistry()
+        registry.projects.removeAll { $0.path == plan.project.path }
+        // saveRegistry throws now — log a write failure but don't abort
+        // the uninstall. Every earlier step already completed (files
+        // removed, skills removed, cron jobs removed, memory stripped,
+        // Keychain cleared); failing here leaves a stale registry row
+        // pointing at a deleted project — cosmetic and easy to fix
+        // from the sidebar.
+        do {
+            try dashboardService.saveRegistry(registry)
+        } catch {
+            Self.logger.warning("uninstall couldn't rewrite projects registry: \(error.localizedDescription, privacy: .public)")
+        }
+
+        Self.logger.info("uninstalled template \(plan.lock.templateId, privacy: .public) from \(plan.project.path, privacy: .public)")
+    }
+
+    // MARK: - Helpers
+
+    nonisolated private func lockPath(for project: ProjectEntry) -> String {
+        project.path + "/.scarf/template.lock.json"
+    }
+
+    /// Walk the project dir and return the absolute paths of every entry
+    /// not in `trackedPaths`. `.scarf/` (and its remaining contents after
+    /// the lock is recorded) is filtered out because the installer owns
+    /// that directory entirely — if the user dropped a file into it,
+    /// that's on them, but the common case is that `.scarf/` only holds
+    /// our dashboard.json + template.lock.json.
+    nonisolated private func enumerateProjectDirExtras(
+        projectDir: String,
+        trackedPaths: Set<String>,
+        transport: any ServerTransport
+    ) throws -> [String] {
+        guard transport.fileExists(projectDir) else { return [] }
+        var extras: [String] = []
+        let entries: [String]
+        do {
+            entries = try transport.listDirectory(projectDir)
+        } catch {
+            return []
+        }
+        for entry in entries {
+            let full = projectDir + "/" + entry
+            // Skip the .scarf/ dir entirely when deciding "does the
+            // project dir have user content?" — the only files we put
+            // there (dashboard.json + lock) are tracked already, and
+            // if they're still there the overall project is not yet
+            // "empty."
+            if entry == ".scarf" { continue }
+            if trackedPaths.contains(full) { continue }
+            extras.append(full)
+        }
+        return extras
+    }
+
+    /// Recursively delete a directory via the transport. The transport's
+    /// `removeFile` works on files and on empty directories; we walk
+    /// children first, then remove the now-empty parent.
+    nonisolated private func removeRecursively(
+        _ path: String,
+        transport: any ServerTransport
+    ) throws {
+        guard transport.fileExists(path) else { return }
+        if transport.stat(path)?.isDirectory != true {
+            try transport.removeFile(path)
+            return
+        }
+        let entries = (try? transport.listDirectory(path)) ?? []
+        for entry in entries {
+            try removeRecursively(path + "/" + entry, transport: transport)
+        }
+        try transport.removeFile(path)
+    }
+
+    /// Remove the `<!-- scarf-template:<id>:begin --> … :end -->` block
+    /// from MEMORY.md, preserving everything else. A missing end marker
+    /// is logged but doesn't fail — we strip from the begin marker to
+    /// EOF in that case, on the theory that a broken template block is
+    /// worse than a slightly aggressive strip.
+    nonisolated private func stripMemoryBlock(
+        blockId: String,
+        memoryPath: String,
+        transport: any ServerTransport
+    ) throws {
+        let beginMarker = ProjectTemplateService.memoryBlockBeginMarker(templateId: blockId)
+        let endMarker = ProjectTemplateService.memoryBlockEndMarker(templateId: blockId)
+
+        let data = try transport.readFile(memoryPath)
+        guard let text = String(data: data, encoding: .utf8) else { return }
+        guard let beginRange = text.range(of: beginMarker) else { return }
+
+        let stripRange: Range<String.Index>
+        if let endRange = text.range(of: endMarker, range: beginRange.upperBound..<text.endIndex) {
+            // Include the end marker and one trailing newline if present.
+            var upper = endRange.upperBound
+            if upper < text.endIndex, text[upper] == "\n" {
+                upper = text.index(after: upper)
+            }
+            stripRange = beginRange.lowerBound..<upper
+        } else {
+            Self.logger.warning("memory block for \(blockId, privacy: .public) has begin marker but no end marker; stripping to EOF")
+            stripRange = beginRange.lowerBound..<text.endIndex
+        }
+
+        // Also consume one leading blank line that the installer inserts
+        // before the begin marker, so repeated install/uninstall cycles
+        // don't accumulate blank lines at the insertion site.
+        var lower = stripRange.lowerBound
+        if lower > text.startIndex {
+            let prev = text.index(before: lower)
+            if text[prev] == "\n", prev > text.startIndex {
+                let prevPrev = text.index(before: prev)
+                if text[prevPrev] == "\n" {
+                    lower = prev
+                }
+            }
+        }
+        let updated = text.replacingCharacters(in: lower..<stripRange.upperBound, with: "")
+        guard let outData = updated.data(using: .utf8) else { return }
+        try transport.writeFile(memoryPath, data: outData)
+    }
+}

scarf/scarf/Core/Services/TemplateURLRouter.swift

@@ -0,0 +1,87 @@
+import Foundation
+import Observation
+import os
+
+/// Process-wide router for `scarf://install?url=…` URLs. The app delegate's
+/// `onOpenURL` hands the URL in here; the Projects feature observes
+/// `pendingInstallURL` and presents the install sheet when it flips non-nil.
+///
+/// Lives outside SwiftUI so a URL can arrive before any window exists (cold
+/// launch from a browser link) and still be picked up by the first
+/// `ProjectsView` that appears.
+@Observable
+@MainActor
+final class TemplateURLRouter {
+    private static let logger = Logger(subsystem: "com.scarf", category: "TemplateURLRouter")
+
+    static let shared = TemplateURLRouter()
+
+    /// Non-nil when an install request is waiting to be handled. Can be
+    /// either a remote `https://…` URL (from a `scarf://install?url=…` deep
+    /// link) or a local `file://…` URL (from a Finder double-click on a
+    /// `.scarftemplate` file, or a drag onto the app icon). Observers read
+    /// this, dispatch by scheme, present the install sheet, then call
+    /// `consume` to clear it. Only one pending install at a time — if a
+    /// second arrives before the first is consumed, it replaces the first
+    /// (matches browser-link intuition where the latest click wins).
+    var pendingInstallURL: URL?
+
+    private init() {}
+
+    /// Parse and validate an inbound URL. Returns `true` if the URL was
+    /// recognized and staged for handling. Unknown schemes or malformed
+    /// payloads return `false` so the caller can log/ignore. Supports:
+    ///
+    /// - `scarf://install?url=https://…` — remote template URL from a web link.
+    /// - `file:///…/foo.scarftemplate` — local file from a Finder
+    ///   double-click or a drag onto the app icon.
+    @discardableResult
+    func handle(_ url: URL) -> Bool {
+        if url.isFileURL {
+            return handleFileURL(url)
+        }
+        if url.scheme?.lowercased() == "scarf" {
+            return handleScarfURL(url)
+        }
+        Self.logger.warning("Ignored URL with unknown scheme: \(url.absoluteString, privacy: .public)")
+        return false
+    }
+
+    private func handleFileURL(_ url: URL) -> Bool {
+        guard url.pathExtension.lowercased() == "scarftemplate" else {
+            Self.logger.warning("file:// URL handed to Scarf but not a .scarftemplate: \(url.absoluteString, privacy: .public)")
+            return false
+        }
+        pendingInstallURL = url
+        Self.logger.info("file:// install staged \(url.path, privacy: .public)")
+        return true
+    }
+
+    private func handleScarfURL(_ url: URL) -> Bool {
+        guard url.host?.lowercased() == "install" else {
+            Self.logger.warning("Ignored unknown scarf:// host: \(url.absoluteString, privacy: .public)")
+            return false
+        }
+        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
+              let raw = components.queryItems?.first(where: { $0.name == "url" })?.value,
+              let remote = URL(string: raw) else {
+            Self.logger.warning("scarf://install missing or invalid ?url=: \(url.absoluteString, privacy: .public)")
+            return false
+        }
+        // Refuse anything but https — defense-in-depth against a browser or
+        // mail client that would happily hand us a javascript: or http://
+        // URL pointing at something unexpected.
+        guard remote.scheme?.lowercased() == "https" else {
+            Self.logger.warning("scarf://install refused non-https url=\(remote.absoluteString, privacy: .public)")
+            return false
+        }
+        pendingInstallURL = remote
+        Self.logger.info("scarf://install staged \(remote.absoluteString, privacy: .public)")
+        return true
+    }
+
+    /// Called by the install sheet once it has picked up the URL.
+    func consume() {
+        pendingInstallURL = nil
+    }
+}

scarf/scarf/Features/Activity/Views/ActivityView.swift

@@ -114,7 +114,7 @@ struct ActivityView: View {
                         VStack(alignment: .leading, spacing: 2) {
                             Text(entry.toolName)
                                 .font(.title3.bold().monospaced())
-                            Text(entry.kind.rawValue.capitalized)
+                            Text(entry.kind.displayName)
                                 .font(.caption)
                                 .foregroundStyle(.secondary)
                         }

scarf/scarf/Features/Chat/ViewModels/ChatViewModel.swift

@@ -50,6 +50,23 @@ final class ChatViewModel {
     private var isHandlingDisconnect = false
     var isACPConnected: Bool { acpClient != nil && hasActiveProcess }
     var acpStatus: String = ""
+
+    /// True while a session is being established or restored — from the user
+    /// kicking off "start chat" or "resume session" until the ACP session is
+    /// ready for messages. The chat pane uses this to show a loader in place
+    /// of the empty-state placeholder.
+    var isPreparingSession: Bool {
+        guard hasActiveProcess else { return false }
+        switch acpStatus {
+        case "Starting...",
+             "Creating session...",
+             "Creating new session...",
+             "Loading session...":
+            return true
+        default:
+            return acpStatus.hasPrefix("Reconnecting")
+        }
+    }
     var acpError: String?
     /// Human-readable hint derived from error + stderr (e.g. "set ANTHROPIC_API_KEY").
     /// Shown above the raw error in the UI when present.

scarf/scarf/Features/Chat/ViewModels/RichChatViewModel.swift

@@ -31,6 +31,7 @@ final class RichChatViewModel {
     init(context: ServerContext = .local) {
         self.context = context
         self.dataService = HermesDataService(context: context)
+        loadQuickCommands()
     }
 
 
@@ -49,9 +50,21 @@ final class RichChatViewModel {
     private(set) var acpCachedReadTokens = 0
 
     /// Slash commands advertised by the ACP server via `available_commands_update`.
-    private(set) var availableCommandNames: Set<String> = []
+    private(set) var acpCommands: [HermesSlashCommand] = []
+    /// User-defined commands parsed from `config.yaml` `quick_commands`.
+    private(set) var quickCommands: [HermesSlashCommand] = []
 
-    var supportsCompress: Bool { availableCommandNames.contains("compress") }
+    /// Merged list, ACP-first, de-duplicated by name.
+    var availableCommands: [HermesSlashCommand] {
+        let acpNames = Set(acpCommands.map(\.name))
+        return acpCommands + quickCommands.filter { !acpNames.contains($0.name) }
+    }
+
+    var supportsCompress: Bool { availableCommands.contains { $0.name == "compress" } }
+
+    /// True when the menu carries more than just `/compress` — used to hide
+    /// the dedicated compress button in favor of the full slash menu.
+    var hasBroaderCommandMenu: Bool { availableCommands.count > 1 }
 
     var hasMessages: Bool { !messages.isEmpty }
 
@@ -105,8 +118,9 @@ final class RichChatViewModel {
         acpOutputTokens = 0
         acpThoughtTokens = 0
         acpCachedReadTokens = 0
-        availableCommandNames = []
+        acpCommands = []
         pendingPermission = nil
+        loadQuickCommands()
     }
 
     func setSessionId(_ id: String?) {
@@ -156,6 +170,11 @@ final class RichChatViewModel {
         streamingThinkingText = ""
         streamingToolCalls = []
         buildMessageGroups()
+        // User just submitted — jump to the bottom so they see their message
+        // and the incoming response. `.defaultScrollAnchor(.bottom)` handles
+        // slow streaming fine, but rapid responses (slash commands especially)
+        // arrive faster than the anchor can track.
+        requestScrollToBottom()
     }
 
     /// Process a streaming ACP event and update the message list.
@@ -181,19 +200,59 @@ final class RichChatViewModel {
         case .connectionLost(let reason):
             handleConnectionLost(reason: reason)
         case .availableCommands(_, let commands):
-            var names: Set<String> = []
+            acpCommands = parseACPCommands(commands)
-            for entry in commands {
-                if let name = entry["name"] as? String {
-                    // Hermes sends names either as "compress" or "/compress"
-                    names.insert(name.trimmingCharacters(in: CharacterSet(charactersIn: "/")))
-                }
-            }
-            availableCommandNames = names
         case .unknown:
             break
         }
     }
 
+    private func parseACPCommands(_ commands: [[String: Any]]) -> [HermesSlashCommand] {
+        var result: [HermesSlashCommand] = []
+        for entry in commands {
+            guard let rawName = entry["name"] as? String else { continue }
+            // Hermes sends names either as "compress" or "/compress"
+            let name = rawName.trimmingCharacters(in: CharacterSet(charactersIn: "/"))
+            guard !name.isEmpty else { continue }
+            let description = (entry["description"] as? String) ?? ""
+            var hint: String? = nil
+            if let input = entry["input"] as? [String: Any],
+               let h = input["hint"] as? String,
+               !h.isEmpty {
+                hint = h
+            }
+            result.append(HermesSlashCommand(
+                name: name,
+                description: description,
+                argumentHint: hint,
+                source: .acp
+            ))
+        }
+        return result
+    }
+
+    /// Load `quick_commands` from `config.yaml` off the main actor and publish
+    /// them as slash commands. Safe to call repeatedly — replaces the existing list.
+    func loadQuickCommands() {
+        let ctx = context
+        Task.detached { [weak self] in
+            let loaded = QuickCommandsViewModel.loadQuickCommands(context: ctx)
+            let mapped = loaded.map { qc -> HermesSlashCommand in
+                let truncated = qc.command.count > 60
+                    ? String(qc.command.prefix(60)) + "…"
+                    : qc.command
+                return HermesSlashCommand(
+                    name: qc.name,
+                    description: "Run: \(truncated)",
+                    argumentHint: nil,
+                    source: .quickCommand
+                )
+            }
+            await MainActor.run { [weak self] in
+                self?.quickCommands = mapped
+            }
+        }
+    }
+
     private func appendMessageChunk(text: String) {
         streamingAssistantText += text
         upsertStreamingMessage()
@@ -283,6 +342,10 @@ final class RichChatViewModel {
         acpCachedReadTokens += response.cachedReadTokens
         isAgentWorking = false
         buildMessageGroups()
+        // Final position after the prompt settles. Catches fast responses
+        // (slash commands, short replies) where `.defaultScrollAnchor(.bottom)`
+        // didn't quite track the abrupt content growth.
+        requestScrollToBottom()
     }
 
     private func handleConnectionLost(reason: String) {

scarf/scarf/Features/Chat/Views/ChatView.swift

@@ -122,7 +122,7 @@ struct ChatView: View {
                 Circle()
                     .fill(.green)
                     .frame(width: 6, height: 6)
-                Text(viewModel.acpStatus.isEmpty ? "Active" : viewModel.acpStatus)
+                (viewModel.acpStatus.isEmpty ? Text("Active") : Text(viewModel.acpStatus))
                     .font(.caption)
                     .foregroundStyle(.secondary)
                     .lineLimit(1)
@@ -238,7 +238,7 @@ struct ChatView: View {
                 HStack(spacing: 4) {
                     Image(systemName: viewModel.voiceEnabled ? "mic.fill" : "mic.slash")
                         .foregroundStyle(viewModel.voiceEnabled ? .green : .secondary)
-                    Text(viewModel.voiceEnabled ? "Voice On" : "Voice Off")
+                    (viewModel.voiceEnabled ? Text("Voice On") : Text("Voice Off"))
                         .font(.caption)
                         .foregroundStyle(viewModel.voiceEnabled ? .primary : .secondary)
                 }
@@ -253,7 +253,7 @@ struct ChatView: View {
                     HStack(spacing: 4) {
                         Image(systemName: viewModel.ttsEnabled ? "speaker.wave.2.fill" : "speaker.slash")
                             .foregroundStyle(viewModel.ttsEnabled ? .green : .secondary)
-                        Text(viewModel.ttsEnabled ? "TTS On" : "TTS Off")
+                        (viewModel.ttsEnabled ? Text("TTS On") : Text("TTS Off"))
                             .font(.caption)
                             .foregroundStyle(viewModel.ttsEnabled ? .primary : .secondary)
                     }
@@ -268,7 +268,7 @@ struct ChatView: View {
                         Image(systemName: viewModel.isRecording ? "waveform.circle.fill" : "waveform.circle")
                             .foregroundStyle(viewModel.isRecording ? .red : Color.accentColor)
                             .symbolEffect(.pulse, isActive: viewModel.isRecording)
-                        Text(viewModel.isRecording ? "Recording..." : "Push to Talk")
+                        (viewModel.isRecording ? Text("Recording…") : Text("Push to Talk"))
                             .font(.caption)
                     }
                 }

scarf/scarf/Features/Chat/Views/RichChatInputBar.swift

@@ -3,70 +3,127 @@ import SwiftUI
 struct RichChatInputBar: View {
     let onSend: (String) -> Void
     let isEnabled: Bool
-    var supportsCompress: Bool = false
+    var commands: [HermesSlashCommand] = []
+    var showCompressButton: Bool = false
 
     @State private var text = ""
     @State private var showCompressSheet = false
     @State private var compressFocus = ""
+    @State private var showMenu = false
+    @State private var selectedIndex = 0
     @FocusState private var isFocused: Bool
 
     var body: some View {
-        HStack(alignment: .bottom, spacing: 8) {
+        VStack(alignment: .leading, spacing: 0) {
-            if supportsCompress {
+            if showMenu {
+                SlashCommandMenu(
+                    commands: filteredCommands,
+                    agentHasCommands: !commands.isEmpty,
+                    selectedIndex: $selectedIndex,
+                    onSelect: insertCommand
+                )
+                .id(menuQuery)
+                .background(.regularMaterial)
+                .overlay(
+                    RoundedRectangle(cornerRadius: 10)
+                        .strokeBorder(.separator, lineWidth: 0.5)
+                )
+                .clipShape(RoundedRectangle(cornerRadius: 10))
+                .shadow(color: .black.opacity(0.2), radius: 8, x: 0, y: 2)
+                .padding(.horizontal, 12)
+                .padding(.top, 8)
+            }
+
+            HStack(alignment: .bottom, spacing: 8) {
+                if showCompressButton {
+                    Button {
+                        compressFocus = ""
+                        showCompressSheet = true
+                    } label: {
+                        Image(systemName: "rectangle.compress.vertical")
+                            .font(.title3)
+                            .foregroundStyle(.secondary)
+                    }
+                    .buttonStyle(.plain)
+                    .disabled(!isEnabled)
+                    .help("Compress conversation (/compress)")
+                }
+
+                TextEditor(text: $text)
+                    .font(.body)
+                    .scrollContentBackground(.hidden)
+                    .focused($isFocused)
+                    .frame(minHeight: 28, maxHeight: 120)
+                    .fixedSize(horizontal: false, vertical: true)
+                    .padding(.horizontal, 8)
+                    .padding(.vertical, 4)
+                    .background(.quaternary.opacity(0.5))
+                    .clipShape(RoundedRectangle(cornerRadius: 12))
+                    .overlay(alignment: .topLeading) {
+                        if text.isEmpty {
+                            Text("Message Hermes...")
+                                .foregroundStyle(.tertiary)
+                                .padding(.horizontal, 12)
+                                .padding(.vertical, 8)
+                                .allowsHitTesting(false)
+                        }
+                    }
+                    .onKeyPress(.upArrow, phases: .down) { _ in
+                        guard showMenu, !filteredCommands.isEmpty else { return .ignored }
+                        let n = filteredCommands.count
+                        selectedIndex = (selectedIndex - 1 + n) % n
+                        return .handled
+                    }
+                    .onKeyPress(.downArrow, phases: .down) { _ in
+                        guard showMenu, !filteredCommands.isEmpty else { return .ignored }
+                        let n = filteredCommands.count
+                        selectedIndex = (selectedIndex + 1) % n
+                        return .handled
+                    }
+                    .onKeyPress(.tab, phases: .down) { _ in
+                        guard showMenu,
+                              let command = filteredCommands[safe: selectedIndex] else { return .ignored }
+                        insertCommand(command)
+                        return .handled
+                    }
+                    .onKeyPress(.escape, phases: .down) { _ in
+                        guard showMenu else { return .ignored }
+                        showMenu = false
+                        return .handled
+                    }
+                    .onKeyPress(.return, phases: .down) { press in
+                        if press.modifiers.contains(.shift) {
+                            return .ignored
+                        }
+                        if showMenu, let command = filteredCommands[safe: selectedIndex] {
+                            insertCommand(command)
+                            return .handled
+                        }
+                        send()
+                        return .handled
+                    }
+
                 Button {
-                    compressFocus = ""
+                    send()
-                    showCompressSheet = true
                 } label: {
-                    Image(systemName: "rectangle.compress.vertical")
+                    Image(systemName: "arrow.up.circle.fill")
-                        .font(.title3)
+                        .font(.title2)
-                        .foregroundStyle(.secondary)
+                        .foregroundStyle(canSend ? Color.accentColor : .secondary)
                 }
                 .buttonStyle(.plain)
-                .disabled(!isEnabled)
+                .disabled(!canSend)
-                .help("Compress conversation (/compress)")
+                .help("Send message (Enter)")
             }
-
+            .padding(.horizontal, 12)
-            TextEditor(text: $text)
+            .padding(.vertical, 8)
-                .font(.body)
-                .scrollContentBackground(.hidden)
-                .focused($isFocused)
-                .frame(minHeight: 28, maxHeight: 120)
-                .fixedSize(horizontal: false, vertical: true)
-                .padding(.horizontal, 8)
-                .padding(.vertical, 4)
-                .background(.quaternary.opacity(0.5))
-                .clipShape(RoundedRectangle(cornerRadius: 12))
-                .overlay(alignment: .topLeading) {
-                    if text.isEmpty {
-                        Text("Message Hermes...")
-                            .foregroundStyle(.tertiary)
-                            .padding(.horizontal, 12)
-                            .padding(.vertical, 8)
-                            .allowsHitTesting(false)
-                    }
-                }
-                .onKeyPress(.return, phases: .down) { press in
-                    if press.modifiers.contains(.shift) {
-                        return .ignored
-                    }
-                    send()
-                    return .handled
-                }
-
-            Button {
-                send()
-            } label: {
-                Image(systemName: "arrow.up.circle.fill")
-                    .font(.title2)
-                    .foregroundStyle(canSend ? Color.accentColor : .secondary)
-            }
-            .buttonStyle(.plain)
-            .disabled(!canSend)
-            .help("Send message (Enter)")
         }
-        .padding(.horizontal, 12)
-        .padding(.vertical, 8)
         .background(.bar)
+        .onChange(of: text) { _, _ in
+            updateMenuState()
+        }
+        .onChange(of: commands.map(\.id)) { _, _ in
+            updateMenuState()
+        }
         .sheet(isPresented: $showCompressSheet) {
             compressSheet
         }
@@ -101,10 +158,61 @@ struct RichChatInputBar: View {
         isEnabled && !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
     }
 
+    /// Show the slash menu only while the user is typing the command token:
+    /// text starts with `/` and contains no whitespace (space or newline).
+    private var shouldShowMenu: Bool {
+        guard text.hasPrefix("/") else { return false }
+        return !text.contains(" ") && !text.contains("\n")
+    }
+
+    private var menuQuery: String {
+        guard text.hasPrefix("/") else { return "" }
+        return String(text.dropFirst())
+    }
+
+    private var filteredCommands: [HermesSlashCommand] {
+        SlashCommandMenu.filter(commands: commands, query: menuQuery)
+    }
+
+    private func updateMenuState() {
+        let shouldShow = shouldShowMenu
+        if shouldShow != showMenu {
+            showMenu = shouldShow
+        }
+        // Re-clamp selection whenever the filtered list may have shrunk.
+        let count = filteredCommands.count
+        if count == 0 {
+            selectedIndex = 0
+        } else if selectedIndex >= count {
+            selectedIndex = count - 1
+        } else if selectedIndex < 0 {
+            selectedIndex = 0
+        }
+    }
+
+    private func insertCommand(_ command: HermesSlashCommand) {
+        if command.argumentHint != nil {
+            text = "/\(command.name) "
+        } else {
+            text = "/\(command.name)"
+        }
+        showMenu = false
+        selectedIndex = 0
+        isFocused = true
+    }
+
     private func send() {
         let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !trimmed.isEmpty, isEnabled else { return }
         onSend(trimmed)
         text = ""
+        showMenu = false
+        selectedIndex = 0
+    }
+}
+
+private extension Array {
+    subscript(safe index: Int) -> Element? {
+        indices.contains(index) ? self[index] : nil
     }
 }

scarf/scarf/Features/Chat/Views/RichChatMessageList.swift

@@ -3,32 +3,52 @@ import SwiftUI
 struct RichChatMessageList: View {
     let groups: [MessageGroup]
     let isWorking: Bool
+    /// True while the ACP session is being established or restored — used to
+    /// swap the empty-state placeholder for a progress indicator so the user
+    /// knows something is happening while history loads.
+    var isLoadingSession: Bool = false
     /// External trigger to force a scroll-to-bottom (e.g., from "Return to Active Session").
     var scrollTrigger: UUID = UUID()
 
-    /// Why `.defaultScrollAnchor(.bottom)` *alone* and no `proxy.scrollTo`.
+    /// Scrolling strategy: plain `VStack` (not `LazyVStack`) plus
+    /// `.defaultScrollAnchor(.bottom)`.
     ///
-    /// `.defaultScrollAnchor(.bottom)` tells SwiftUI to pin the viewport to
+    /// `LazyVStack` was causing the classic "loaded session shows whitespace
-    /// the bottom of the content automatically — as messages stream in or
+    /// and the chat is above" bug: lazy rows return estimated heights before
-    /// new turns arrive, the scroll position tracks the bottom edge.
+    /// they render, `.defaultScrollAnchor(.bottom)` positions the viewport
+    /// at the *estimated* bottom (which overshoots the real content), and
+    /// when rows materialize and real heights land, the viewport ends up
+    /// past the content. Attempts to correct via `proxy.scrollTo(lastID)`
+    /// failed because unrendered rows have no resolvable ID.
     ///
-    /// We used to also call `proxy.scrollTo(lastID, anchor: .bottom)` from
+    /// Switching to `VStack` materializes every row immediately, so
-    /// six different `onChange` handlers during streaming. The two
+    /// `.defaultScrollAnchor(.bottom)` has real heights to work with and
-    /// mechanisms fought each other: the ScrollViewReader can resolve an ID
+    /// can't overshoot. For typical Hermes sessions (<500 messages) the
-    /// to a position **before** LazyVStack has finished laying out that
+    /// first-render cost is acceptable. If ever needed for huge sessions
-    /// row, so `scrollTo` would land past the actual content — the
+    /// we can reintroduce lazy with a preference-key-based height
-    /// "viewport showing whitespace, chat is above" symptom. Removing the
+    /// measurement, but that's a much larger change.
-    /// manual scroll and trusting `defaultScrollAnchor` eliminates the race.
-    ///
-    /// The only remaining explicit scroll is `scrollTrigger` for the "Return
-    /// to Active Session" button; that fires rarely, after layout has
-    /// settled, so the overshoot doesn't happen.
     var body: some View {
         ScrollViewReader { proxy in
             ScrollView {
-                LazyVStack(alignment: .leading, spacing: 16) {
+                VStack(alignment: .leading, spacing: 16) {
                     if groups.isEmpty && !isWorking {
-                        emptyState
+                        // Fill the scroll view's visible height so Spacers
+                        // can vertically center the placeholder. Previously
+                        // `.padding(.vertical, 80)` left the placeholder
+                        // floating at whatever y-offset `.defaultScrollAnchor(.bottom)`
+                        // settled on — usually near the bottom of the pane.
+                        VStack {
+                            Spacer(minLength: 0)
+                            if isLoadingSession {
+                                loadingState
+                            } else {
+                                emptyState
+                            }
+                            Spacer(minLength: 0)
+                        }
+                        .frame(maxWidth: .infinity)
+                        .containerRelativeFrame(.vertical)
+                        .transition(.opacity)
                     }
 
                     ForEach(groups) { group in
@@ -42,6 +62,8 @@ struct RichChatMessageList: View {
                     }
                 }
                 .padding()
+                .animation(.easeInOut(duration: 0.15), value: isLoadingSession)
+                .animation(.easeInOut(duration: 0.15), value: groups.isEmpty)
             }
             .defaultScrollAnchor(.bottom)
             .onChange(of: scrollTrigger) {
@@ -75,8 +97,16 @@ struct RichChatMessageList: View {
                 .foregroundStyle(.secondary)
                 .multilineTextAlignment(.center)
         }
-        .frame(maxWidth: .infinity)
+    }
-        .padding(.vertical, 80)
+
+    private var loadingState: some View {
+        VStack(spacing: 14) {
+            ProgressView()
+                .controlSize(.large)
+            Text("Loading session…")
+                .font(.callout)
+                .foregroundStyle(.secondary)
+        }
     }
 
     private var typingIndicator: some View {

scarf/scarf/Features/Chat/Views/RichChatView.swift

@@ -28,6 +28,7 @@ struct RichChatView: View {
             RichChatMessageList(
                 groups: richChat.messageGroups,
                 isWorking: richChat.isAgentWorking,
+                isLoadingSession: chatViewModel.isPreparingSession,
                 scrollTrigger: richChat.scrollTrigger
             )
 
@@ -37,7 +38,8 @@ struct RichChatView: View {
                     onSend(text)
                 },
                 isEnabled: isEnabled,
-                supportsCompress: richChat.supportsCompress
+                commands: richChat.availableCommands,
+                showCompressButton: richChat.supportsCompress && !richChat.hasBroaderCommandMenu
             )
         }
         // DB polling fallback for terminal mode only — never overwrite ACP messages

scarf/scarf/Features/Chat/Views/SessionInfoBar.swift

@@ -45,7 +45,8 @@ struct SessionInfoBar: View {
                 }
 
                 if let cost = session.displayCostUSD {
-                    Label(String(format: "$%.4f%@", cost, session.costIsActual ? "" : " est."), systemImage: "dollarsign.circle")
+                    let formattedCost = cost.formatted(.currency(code: "USD").precision(.fractionLength(4)))
+                    Label(session.costIsActual ? formattedCost : "\(formattedCost) est.", systemImage: "dollarsign.circle")
                         .contentTransition(.numericText())
                 }
 
@@ -75,11 +76,6 @@ struct SessionInfoBar: View {
     }
 
     private func formatTokens(_ count: Int) -> String {
-        if count >= 1_000_000 {
+        count.formatted(.number.notation(.compactName).precision(.fractionLength(0...1)))
-            return String(format: "%.1fM", Double(count) / 1_000_000)
-        } else if count >= 1_000 {
-            return String(format: "%.1fK", Double(count) / 1_000)
-        }
-        return "\(count)"
     }
 }

scarf/scarf/Features/Chat/Views/SlashCommandMenu.swift

@@ -0,0 +1,114 @@
+import SwiftUI
+
+/// Floating menu of available slash commands shown above the chat input when
+/// the user types `/` as the first character. Purely presentational — the
+/// parent filters the list and owns selection state.
+struct SlashCommandMenu: View {
+    /// Pre-filtered commands to display.
+    let commands: [HermesSlashCommand]
+    /// Whether the agent advertised any commands at all. Lets us distinguish
+    /// "agent hasn't sent commands yet" from "filter matched nothing".
+    let agentHasCommands: Bool
+    @Binding var selectedIndex: Int
+    var onSelect: (HermesSlashCommand) -> Void
+
+    /// Case-insensitive prefix match on the command name. Exposed as a static
+    /// helper so the parent can share filter logic with its key handlers.
+    static func filter(commands: [HermesSlashCommand], query: String) -> [HermesSlashCommand] {
+        let q = query.lowercased()
+        if q.isEmpty { return commands }
+        return commands.filter { $0.name.lowercased().hasPrefix(q) }
+    }
+
+    var body: some View {
+        if !agentHasCommands {
+            VStack(alignment: .leading, spacing: 4) {
+                Text("No commands available")
+                    .font(.callout)
+                    .foregroundStyle(.secondary)
+                Text("The agent hasn't advertised any slash commands yet. Keep typing to send as a message, or press Esc.")
+                    .font(.caption)
+                    .foregroundStyle(.tertiary)
+            }
+            .padding(12)
+            .frame(minWidth: 360, alignment: .leading)
+        } else if commands.isEmpty {
+            VStack(alignment: .leading, spacing: 4) {
+                Text("No matching commands")
+                    .font(.callout)
+                    .foregroundStyle(.secondary)
+                Text("Keep typing to send as a message, or press Esc.")
+                    .font(.caption)
+                    .foregroundStyle(.tertiary)
+            }
+            .padding(12)
+            .frame(minWidth: 360, alignment: .leading)
+        } else {
+            ScrollViewReader { proxy in
+                ScrollView {
+                    LazyVStack(spacing: 0) {
+                        ForEach(Array(commands.enumerated()), id: \.element.id) { index, command in
+                            SlashCommandRow(
+                                command: command,
+                                isSelected: index == selectedIndex
+                            )
+                            .id(index)
+                            .contentShape(Rectangle())
+                            .onTapGesture {
+                                selectedIndex = index
+                                onSelect(command)
+                            }
+                        }
+                    }
+                }
+                .frame(minWidth: 360, maxHeight: 260)
+                .onChange(of: selectedIndex) { _, newValue in
+                    withAnimation(.easeOut(duration: 0.1)) {
+                        proxy.scrollTo(newValue, anchor: .center)
+                    }
+                }
+            }
+        }
+    }
+}
+
+private struct SlashCommandRow: View {
+    let command: HermesSlashCommand
+    let isSelected: Bool
+
+    var body: some View {
+        HStack(alignment: .firstTextBaseline, spacing: 8) {
+            VStack(alignment: .leading, spacing: 2) {
+                HStack(spacing: 6) {
+                    Text("/\(command.name)")
+                        .font(.system(.body, design: .monospaced))
+                        .fontWeight(.semibold)
+                    if let hint = command.argumentHint {
+                        Text("<\(hint)>")
+                            .font(.system(.caption, design: .monospaced))
+                            .foregroundStyle(.tertiary)
+                    }
+                    if command.source == .quickCommand {
+                        Text("user")
+                            .font(.caption2)
+                            .padding(.horizontal, 6)
+                            .padding(.vertical, 1)
+                            .background(.quaternary.opacity(0.8))
+                            .clipShape(Capsule())
+                            .foregroundStyle(.secondary)
+                    }
+                }
+                if !command.description.isEmpty {
+                    Text(command.description)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .lineLimit(2)
+                }
+            }
+            Spacer(minLength: 0)
+        }
+        .padding(.horizontal, 12)
+        .padding(.vertical, 8)
+        .background(isSelected ? Color.accentColor.opacity(0.15) : Color.clear)
+    }
+}

scarf/scarf/Features/CredentialPools/Views/CredentialPoolsView.swift

@@ -106,7 +106,7 @@ struct CredentialPoolsView: View {
 
     @ViewBuilder
     private func poolSection(_ pool: HermesCredentialPool) -> some View {
-        SettingsSection(title: pool.provider, icon: "key.horizontal") {
+        SettingsSection(title: LocalizedStringKey(pool.provider), icon: "key.horizontal") {
             PickerRow(label: "Rotation", selection: pool.strategy, options: viewModel.strategyOptions) { strategy in
                 viewModel.setStrategy(strategy, for: pool.provider)
             }
@@ -194,6 +194,13 @@ private struct AddCredentialSheet: View {
         case apiKey = "API Key"
         case oauth = "OAuth"
         var id: String { rawValue }
+
+        var displayName: LocalizedStringResource {
+            switch self {
+            case .apiKey: return "API Key"
+            case .oauth: return "OAuth"
+            }
+        }
     }
 
     @State private var providerID: String = ""
@@ -262,7 +269,7 @@ private struct AddCredentialSheet: View {
                 Text("Credential Type").font(.caption).foregroundStyle(.secondary)
                 Picker("", selection: $authType) {
                     ForEach(AuthType.allCases) { type in
-                        Text(type.rawValue).tag(type)
+                        Text(type.displayName).tag(type)
                     }
                 }
                 .pickerStyle(.segmented)

scarf/scarf/Features/Cron/ViewModels/CronViewModel.swift

@@ -65,7 +65,61 @@ final class CronViewModel {
     }
 
     func runNow(_ job: HermesCronJob) {
-        runAndReload(["cron", "run", job.id], success: "Scheduled for next tick")
+        // `hermes cron run <id>` only marks the job as due on the next
+        // scheduler tick — it doesn't actually execute. If the Hermes
+        // gateway's scheduler isn't running (common during dev + right
+        // after install), the user's "Run now" click results in zero
+        // visible effect because the tick never comes. We follow up
+        // with `hermes cron tick` which runs all due jobs once and
+        // exits. Redundant-but-harmless when the gateway is running;
+        // the actual trigger when it isn't.
+        //
+        // Feedback model: show a "Agent started" toast as soon as
+        // `cron run` succeeds, WITHOUT waiting for `cron tick` to
+        // return. Agent jobs routinely run past a minute (network IO +
+        // an LLM call + a file rewrite), and earlier versions with a
+        // 60s tick timeout surfaced a misleading "Run failed" toast
+        // every time while the job kept running in the background.
+        // The app's HermesFileWatcher picks up the dashboard.json
+        // rewrite that the agent lands at the end — that's what the
+        // user actually watches for, not this toast.
+        let svc = fileService
+        let jobID = job.id
+        Task.detached { [weak self] in
+            let runResult = svc.runHermesCLI(args: ["cron", "run", jobID], timeout: 30)
+            await MainActor.run { [weak self] in
+                guard let self else { return }
+                if runResult.exitCode != 0 {
+                    self.message = "Run failed to queue: \(runResult.output.prefix(200))"
+                    self.logger.warning("cron run failed: \(runResult.output)")
+                    self.load()
+                    DispatchQueue.main.asyncAfter(deadline: .now() + 3) { [weak self] in
+                        self?.message = nil
+                    }
+                    return
+                }
+                self.message = "Agent started — dashboard will update when it finishes"
+                self.load()
+            }
+            // `cron run` is queued; now force the tick. The 300s
+            // timeout catches truly stuck processes without killing
+            // the long-but-valid agent case that blew up the 60s
+            // version. A timeout here is survivable — the Hermes
+            // scheduler re-runs due jobs on its own cadence — so we
+            // log but don't surface it as a failure toast.
+            try? await Task.sleep(for: .milliseconds(250))
+            let tickResult = svc.runHermesCLI(args: ["cron", "tick"], timeout: 300)
+            await MainActor.run { [weak self] in
+                guard let self else { return }
+                if tickResult.exitCode != 0 {
+                    self.logger.warning("cron tick exited non-zero (job may still complete via scheduler): \(tickResult.output)")
+                }
+                self.load()
+                DispatchQueue.main.asyncAfter(deadline: .now() + 3) { [weak self] in
+                    self?.message = nil
+                }
+            }
+        }
     }
 
     func deleteJob(_ job: HermesCronJob) {

scarf/scarf/Features/Dashboard/Views/DashboardView.swift

@@ -114,7 +114,7 @@ struct DashboardView: View {
                 StatCard(label: "Tokens", value: formatTokens(viewModel.stats.totalInputTokens + viewModel.stats.totalOutputTokens))
                 let cost = viewModel.stats.totalActualCostUSD > 0 ? viewModel.stats.totalActualCostUSD : viewModel.stats.totalCostUSD
                 if cost > 0 {
-                    StatCard(label: "Cost", value: String(format: "$%.2f", cost))
+                    StatCard(label: "Cost", value: cost.formatted(.currency(code: "USD").precision(.fractionLength(2))))
                 }
             }
         }
@@ -217,7 +217,7 @@ struct SessionRow: View {
                 Label("\(session.messageCount)", systemImage: "bubble.left")
                 Label("\(session.toolCallCount)", systemImage: "wrench")
                 if let cost = session.displayCostUSD, cost > 0 {
-                    Label(String(format: "$%.4f", cost), systemImage: "dollarsign.circle")
+                    Label(cost.formatted(.currency(code: "USD").precision(.fractionLength(4))), systemImage: "dollarsign.circle")
                 }
             }
             .font(.caption)

scarf/scarf/Features/Gateway/Views/GatewayView.swift

@@ -102,7 +102,7 @@ struct GatewayView: View {
                             Image(systemName: platform.icon)
                                 .font(.title2)
                                 .foregroundStyle(platform.isConnected ? Color.accentColor : .secondary)
-                            Text(platform.name.capitalized)
+                            Text(verbatim: platform.name.capitalized)
                                 .font(.caption.bold())
                             StatusBadge(
                                 label: platform.state,

scarf/scarf/Features/Health/Views/HealthView.swift

@@ -132,7 +132,7 @@ struct HealthView: View {
                     Circle()
                         .fill(viewModel.hermesRunning ? .green : .red)
                         .frame(width: 8, height: 8)
-                    Text(viewModel.hermesRunning ? "Hermes Running" : "Hermes Stopped")
+                    (viewModel.hermesRunning ? Text("Hermes Running") : Text("Hermes Stopped"))
                         .font(.caption.bold())
                     if let pid = viewModel.hermesPID {
                         Text("PID \(pid)")

scarf/scarf/Features/Insights/ViewModels/InsightsViewModel.swift

@@ -8,6 +8,15 @@ enum InsightsPeriod: String, CaseIterable, Identifiable {
 
     var id: String { rawValue }
 
+    var displayName: LocalizedStringResource {
+        switch self {
+        case .week: return "7 Days"
+        case .month: return "30 Days"
+        case .quarter: return "90 Days"
+        case .all: return "All Time"
+        }
+    }
+
     var sinceDate: Date {
         let calendar = Calendar.current
         switch self {

scarf/scarf/Features/Insights/Views/InsightsView.swift

@@ -37,7 +37,7 @@ struct InsightsView: View {
     private var periodPicker: some View {
         Picker("Period", selection: $viewModel.period) {
             ForEach(InsightsPeriod.allCases) { period in
-                Text(period.rawValue).tag(period)
+                Text(period.displayName).tag(period)
             }
         }
         .pickerStyle(.segmented)
@@ -61,10 +61,10 @@ struct InsightsView: View {
                 InsightCard(label: "Cache Write", value: formatTokens(viewModel.totalCacheWriteTokens))
                 InsightCard(label: "Reasoning Tokens", value: formatTokens(viewModel.totalReasoningTokens))
                 InsightCard(label: "Total Tokens", value: formatTokens(viewModel.totalTokens))
-                InsightCard(label: "Total Cost", value: String(format: "$%.2f", viewModel.totalCost))
+                InsightCard(label: "Total Cost", value: viewModel.totalCost.formatted(.currency(code: "USD").precision(.fractionLength(2))))
                 InsightCard(label: "Active Time", value: formatDuration(viewModel.activeTime))
                 InsightCard(label: "Avg Session", value: formatDuration(viewModel.avgSessionDuration))
-                InsightCard(label: "Avg Msgs/Session", value: viewModel.sessions.isEmpty ? "0" : String(format: "%.1f", Double(viewModel.totalMessages) / Double(viewModel.sessions.count)))
+                InsightCard(label: "Avg Msgs/Session", value: viewModel.sessions.isEmpty ? "0" : (Double(viewModel.totalMessages) / Double(viewModel.sessions.count)).formatted(.number.precision(.fractionLength(1))))
             }
         }
     }
@@ -90,7 +90,7 @@ struct InsightsView: View {
                         VStack(alignment: .trailing, spacing: 2) {
                             Text("\(model.sessions) sessions")
                                 .font(.caption)
-                            Text(formatTokens(model.totalTokens) + " tokens")
+                            Text("\(formatTokens(model.totalTokens)) tokens")
                                 .font(.caption)
                                 .foregroundStyle(.secondary)
                         }
@@ -164,7 +164,7 @@ struct InsightsView: View {
                             .font(.caption.monospaced())
                             .foregroundStyle(.secondary)
                             .frame(width: 40, alignment: .trailing)
-                        Text(String(format: "%.1f%%", tool.percentage))
+                        Text((tool.percentage / 100).formatted(.percent.precision(.fractionLength(1))))
                             .font(.caption)
                             .foregroundStyle(.tertiary)
                             .frame(width: 50, alignment: .trailing)
@@ -193,12 +193,12 @@ struct InsightsView: View {
             Text("By Day")
                 .font(.caption.bold())
                 .foregroundStyle(.secondary)
-            let dayNames = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+            let dayNames = Calendar.current.shortWeekdaySymbols
             let maxVal = max(1, viewModel.dailyActivity.values.max() ?? 1)
             ForEach(0..<7, id: \.self) { day in
                 let count = viewModel.dailyActivity[day] ?? 0
                 HStack(spacing: 6) {
-                    Text(dayNames[day])
+                    Text(verbatim: dayNames[(day + 1) % 7])
                         .font(.caption.monospaced())
                         .frame(width: 30, alignment: .trailing)
                     RoundedRectangle(cornerRadius: 2)

scarf/scarf/Features/Logs/ViewModels/LogsViewModel.swift

@@ -23,6 +23,14 @@ final class LogsViewModel {
         case gateway = "gateway.log"
 
         var id: String { rawValue }
+
+        var displayName: LocalizedStringResource {
+            switch self {
+            case .agent: return "Agent"
+            case .errors: return "Errors"
+            case .gateway: return "Gateway"
+            }
+        }
     }
 
     private func path(for file: LogFile) -> String {
@@ -43,6 +51,17 @@ final class LogsViewModel {
 
         var id: String { rawValue }
 
+        var displayName: LocalizedStringResource {
+            switch self {
+            case .all: return "All"
+            case .gateway: return "Gateway"
+            case .agent: return "Agent"
+            case .tools: return "Tools"
+            case .cli: return "CLI"
+            case .cron: return "Cron"
+            }
+        }
+
         var loggerPrefix: String? {
             switch self {
             case .all: return nil

scarf/scarf/Features/Logs/Views/LogsView.swift

@@ -27,7 +27,7 @@ struct LogsView: View {
                 set: { file in Task { await viewModel.switchLogFile(file) } }
             )) {
                 ForEach(LogsViewModel.LogFile.allCases) { file in
-                    Text(file.rawValue).tag(file)
+                    Text(file.displayName).tag(file)
                 }
             }
             .pickerStyle(.segmented)
@@ -35,7 +35,7 @@ struct LogsView: View {
 
             Picker("Component", selection: $viewModel.selectedComponent) {
                 ForEach(LogsViewModel.LogComponent.allCases) { component in
-                    Text(component.rawValue).tag(component)
+                    Text(component.displayName).tag(component)
                 }
             }
             .frame(maxWidth: 140)
@@ -45,7 +45,7 @@ struct LogsView: View {
             Picker("Level", selection: $viewModel.filterLevel) {
                 Text("All Levels").tag(LogEntry.LogLevel?.none)
                 ForEach(LogEntry.LogLevel.allCases, id: \.rawValue) { level in
-                    Text(level.rawValue).tag(LogEntry.LogLevel?.some(level))
+                    Text(verbatim: level.rawValue).tag(LogEntry.LogLevel?.some(level))
                 }
             }
             .frame(maxWidth: 150)
@@ -66,7 +66,7 @@ struct LogsView: View {
                         .font(.caption.monospaced())
                         .foregroundStyle(.secondary)
                         .frame(width: 140, alignment: .leading)
-                    Text(entry.level.rawValue)
+                    Text(verbatim: entry.level.rawValue)
                         .font(.caption.monospaced().bold())
                         .foregroundStyle(colorForLevel(entry.level))
                         .frame(width: 60, alignment: .leading)

scarf/scarf/Features/MCPServers/Views/MCPServerDetailView.swift

@@ -154,7 +154,7 @@ struct MCPServerDetailView: View {
                         Text(key)
                             .font(.system(.caption, design: .monospaced))
                         Spacer()
-                        Text(String(repeating: "•", count: 10))
+                        Text("••••••••••")
                             .font(.caption.monospaced())
                             .foregroundStyle(.secondary)
                     }
@@ -182,7 +182,7 @@ struct MCPServerDetailView: View {
                         Text(key)
                             .font(.system(.caption, design: .monospaced))
                         Spacer()
-                        Text(String(repeating: "•", count: 10))
+                        Text("••••••••••")
                             .font(.caption.monospaced())
                             .foregroundStyle(.secondary)
                     }

scarf/scarf/Features/MCPServers/Views/MCPServerPresetPickerView.swift

@@ -33,9 +33,9 @@ struct MCPServerPresetPickerView: View {
                 }
             }
             VStack(alignment: .leading, spacing: 2) {
-                Text(selectedPreset?.displayName ?? "Add from Preset")
+                (selectedPreset.map { Text(verbatim: $0.displayName) } ?? Text("Add from Preset"))
                     .font(.headline)
-                Text(selectedPreset?.description ?? "Pick an MCP server to add.")
+                (selectedPreset.map { Text(verbatim: $0.description) } ?? Text("Pick an MCP server to add."))
                     .font(.caption)
                     .foregroundStyle(.secondary)
                     .lineLimit(1)
@@ -83,14 +83,14 @@ struct MCPServerPresetPickerView: View {
                     Image(systemName: preset.iconSystemName)
                         .font(.title3)
                         .foregroundStyle(Color.accentColor)
-                    Text(preset.displayName)
+                    Text(verbatim: preset.displayName)
                         .font(.body.bold())
                     Spacer()
                     Image(systemName: preset.transport == .http ? "network" : "terminal")
                         .font(.caption)
                         .foregroundStyle(.secondary)
                 }
-                Text(preset.description)
+                Text(verbatim: preset.description)
                     .font(.caption)
                     .foregroundStyle(.secondary)
                     .lineLimit(3)

scarf/scarf/Features/MCPServers/Views/MCPServerTestResultView.swift

@@ -10,9 +10,9 @@ struct MCPServerTestResultView: View {
                 Image(systemName: result.succeeded ? "checkmark.seal.fill" : "xmark.seal.fill")
                     .foregroundStyle(result.succeeded ? .green : .red)
                 VStack(alignment: .leading, spacing: 2) {
-                    Text(result.succeeded ? "Test passed" : "Test failed")
+                    (result.succeeded ? Text("Test passed") : Text("Test failed"))
                         .font(.subheadline.bold())
-                    Text(String(format: "%.1fs · %d tools", result.elapsed, result.tools.count))
+                    Text("\(result.elapsed.formatted(.number.precision(.fractionLength(1))))s · \(result.tools.count) tools")
                         .font(.caption)
                         .foregroundStyle(.secondary)
                 }
@@ -20,8 +20,12 @@ struct MCPServerTestResultView: View {
                 Button {
                     showOutput.toggle()
                 } label: {
-                    Label(showOutput ? "Hide Output" : "Show Output", systemImage: showOutput ? "chevron.up" : "chevron.down")
+                    Label {
-                        .font(.caption)
+                        showOutput ? Text("Hide Output") : Text("Show Output")
+                    } icon: {
+                        Image(systemName: showOutput ? "chevron.up" : "chevron.down")
+                    }
+                    .font(.caption)
                 }
                 .buttonStyle(.borderless)
             }

scarf/scarf/Features/MCPServers/Views/MCPServersView.swift

@@ -128,7 +128,7 @@ struct MCPServersView: View {
             } else if let result = viewModel.testResults[server.name] {
                 Image(systemName: result.succeeded ? "checkmark.circle.fill" : "xmark.circle.fill")
                     .foregroundStyle(result.succeeded ? .green : .red)
-                    .help(result.succeeded ? "\(result.tools.count) tools" : "Test failed")
+                    .help(result.succeeded ? Text("\(result.tools.count) tools") : Text("Test failed"))
             }
         }
     }

scarf/scarf/Features/Platforms/Views/PlatformSetup/SignalSetupView.swift

@@ -51,7 +51,9 @@ struct SignalSetupView: View {
         HStack(spacing: 8) {
             Image(systemName: viewModel.signalCLIInstalled ? "checkmark.circle.fill" : "exclamationmark.triangle.fill")
                 .foregroundStyle(viewModel.signalCLIInstalled ? .green : .orange)
-            Text(viewModel.signalCLIInstalled ? "signal-cli is available on PATH" : "signal-cli not found on PATH — install it first")
+            (viewModel.signalCLIInstalled
+                ? Text("signal-cli is available on PATH")
+                : Text("signal-cli not found on PATH — install it first"))
                 .font(.caption)
                 .foregroundStyle(viewModel.signalCLIInstalled ? Color.primary : Color.orange)
             Spacer()

scarf/scarf/Features/Platforms/Views/PlatformsView.swift

@@ -40,7 +40,7 @@ struct PlatformsView: View {
                     HStack(spacing: 8) {
                         Image(systemName: KnownPlatforms.icon(for: platform.name))
                             .frame(width: 20)
-                        Text(platform.displayName)
+                        Text(verbatim: platform.displayName)
                         Spacer()
                         Circle()
                             .fill(statusColor(viewModel.connectivity(for: platform)))
@@ -88,7 +88,7 @@ struct PlatformsView: View {
             Image(systemName: KnownPlatforms.icon(for: viewModel.selected.name))
                 .font(.title)
             VStack(alignment: .leading) {
-                Text(viewModel.selected.displayName)
+                Text(verbatim: viewModel.selected.displayName)
                     .font(.title2.bold())
                 Text(statusDescription(viewModel.connectivity(for: viewModel.selected)))
                     .font(.caption)
@@ -139,7 +139,7 @@ struct PlatformsView: View {
         case "homeassistant":  HomeAssistantSetupView(context: ctx)
         case "webhook":        WebhookSetupView(context: ctx)
         default:
-            SettingsSection(title: viewModel.selected.displayName, icon: KnownPlatforms.icon(for: viewModel.selected.name)) {
+            SettingsSection(title: LocalizedStringKey(viewModel.selected.displayName), icon: KnownPlatforms.icon(for: viewModel.selected.name)) {
                 ReadOnlyRow(label: "Setup", value: "No setup form for this platform yet.")
             }
         }

scarf/scarf/Features/Profiles/Views/ProfilesView.swift

@@ -142,7 +142,7 @@ struct ProfilesView: View {
                             .font(.title)
                         VStack(alignment: .leading) {
                             Text(profile.name).font(.title2.bold())
-                            Text(profile.isActive ? "Active profile" : "Inactive")
+                            (profile.isActive ? Text("Active profile") : Text("Inactive"))
                                 .font(.caption)
                                 .foregroundStyle(.secondary)
                         }

scarf/scarf/Features/Projects/ViewModels/ProjectsViewModel.swift

@@ -1,7 +1,9 @@
 import Foundation
+import os
 
 @Observable
 final class ProjectsViewModel {
+    private let logger = Logger(subsystem: "com.scarf", category: "ProjectsViewModel")
     let context: ServerContext
     private let service: ProjectDashboardService
 
@@ -39,7 +41,19 @@ final class ProjectsViewModel {
         guard !registry.projects.contains(where: { $0.name == name }) else { return }
         let entry = ProjectEntry(name: name, path: path)
         registry.projects.append(entry)
-        service.saveRegistry(registry)
+        // saveRegistry throws now. The VM doesn't currently have a
+        // surface for user-visible errors (there's no alert/toast in
+        // the Projects view), so log at error level to the unified
+        // log and keep the in-memory state consistent with whatever
+        // landed on disk. If the write fails, the added entry won't
+        // persist across launches — the user sees it appear + work
+        // this session, then it's gone at relaunch. Not ideal, but
+        // matches today's UX and flagged for a proper alert later.
+        do {
+            try service.saveRegistry(registry)
+        } catch {
+            logger.error("addProject couldn't persist registry: \(error.localizedDescription, privacy: .public)")
+        }
         projects = registry.projects
         selectProject(entry)
     }
@@ -47,7 +61,11 @@ final class ProjectsViewModel {
     func removeProject(_ project: ProjectEntry) {
         var registry = service.loadRegistry()
         registry.projects.removeAll { $0.name == project.name }
-        service.saveRegistry(registry)
+        do {
+            try service.saveRegistry(registry)
+        } catch {
+            logger.error("removeProject couldn't persist registry: \(error.localizedDescription, privacy: .public)")
+        }
         projects = registry.projects
         if selectedProject?.name == project.name {
             selectedProject = nil

scarf/scarf/Features/Projects/Views/ProjectsView.swift

@@ -1,18 +1,54 @@
 import SwiftUI
+import UniformTypeIdentifiers
 
 private enum DashboardTab: String, CaseIterable {
     case dashboard = "Dashboard"
     case site = "Site"
+
+    var displayName: LocalizedStringResource {
+        switch self {
+        case .dashboard: return "Dashboard"
+        case .site: return "Site"
+        }
+    }
 }
 
 struct ProjectsView: View {
     @State private var viewModel: ProjectsViewModel
+    @State private var installerViewModel: TemplateInstallerViewModel
+    @State private var uninstallerViewModel: TemplateUninstallerViewModel
     @Environment(AppCoordinator.self) private var coordinator
     @Environment(HermesFileWatcher.self) private var fileWatcher
+    @Environment(\.serverContext) private var serverContext
     @State private var showingAddSheet = false
+    @State private var showingInstallSheet = false
+    @State private var exportSheetProject: ProjectEntry?
+    @State private var showingInstallURLPrompt = false
+    @State private var installURLInput = ""
+    @State private var showingUninstallSheet = false
+    @State private var configEditorProject: ProjectEntry?
+    /// Project queued for the "remove from list" confirmation dialog.
+    /// Non-nil while the dialog is up; the `confirmationDialog` binding
+    /// flips based on presence. We store the full entry (not just a
+    /// flag) so the dialog's action closure knows which project to
+    /// drop from the registry.
+    @State private var pendingRemoveFromList: ProjectEntry?
+
+    private let uninstaller: ProjectTemplateUninstaller
 
     init(context: ServerContext) {
         _viewModel = State(initialValue: ProjectsViewModel(context: context))
+        _installerViewModel = State(initialValue: TemplateInstallerViewModel(context: context))
+        _uninstallerViewModel = State(initialValue: TemplateUninstallerViewModel(context: context))
+        self.uninstaller = ProjectTemplateUninstaller(context: context)
+    }
+
+    /// True when the given project has a cached manifest (i.e. was
+    /// installed from a schemaful template). Cheap — just a file
+    /// existence check via the transport.
+    private func isConfigurable(_ project: ProjectEntry) -> Bool {
+        let path = ProjectConfigService.manifestCachePath(for: project)
+        return serverContext.makeTransport().fileExists(path)
     }
 
     @State private var selectedTab: DashboardTab = .dashboard
@@ -25,6 +61,7 @@ struct ProjectsView: View {
                 .frame(maxWidth: .infinity, maxHeight: .infinity)
         }
         .navigationTitle("Projects")
+        .toolbar { templatesToolbar }
         .task {
             viewModel.load()
             if let name = coordinator.selectedProjectName,
@@ -32,11 +69,195 @@ struct ProjectsView: View {
                 viewModel.selectProject(project)
             }
             fileWatcher.updateProjectWatches(viewModel.dashboardPaths)
+            // Cold-launch deep link or Finder double-click: the router may
+            // have a URL staged before this view installed the onChange
+            // observer below. Without this first-appearance check,
+            // SwiftUI's .onChange would never fire (it only reacts to
+            // *changes* after installation) and the URL would sit on the
+            // singleton forever.
+            if let pending = TemplateURLRouter.shared.pendingInstallURL {
+                dispatchPendingInstall(pending)
+            }
         }
         .onChange(of: fileWatcher.lastChangeDate) {
             viewModel.load()
             fileWatcher.updateProjectWatches(viewModel.dashboardPaths)
         }
+        .onChange(of: TemplateURLRouter.shared.pendingInstallURL) { _, new in
+            // A URL landed *while the app was already running*.
+            if let new {
+                dispatchPendingInstall(new)
+            }
+        }
+        .sheet(isPresented: $showingInstallSheet) {
+            TemplateInstallSheet(viewModel: installerViewModel) { entry in
+                viewModel.load()
+                coordinator.selectedProjectName = entry.name
+                if let project = viewModel.projects.first(where: { $0.name == entry.name }) {
+                    viewModel.selectProject(project)
+                }
+                fileWatcher.updateProjectWatches(viewModel.dashboardPaths)
+            }
+        }
+        .sheet(item: $exportSheetProject) { project in
+            TemplateExportSheet(
+                viewModel: TemplateExporterViewModel(context: serverContext, project: project)
+            )
+        }
+        .sheet(isPresented: $showingInstallURLPrompt) {
+            installURLSheet
+        }
+        .sheet(isPresented: $showingUninstallSheet) {
+            TemplateUninstallSheet(viewModel: uninstallerViewModel) { removed in
+                // Refresh the registry and clear selection if we just
+                // removed the project the user was viewing.
+                if viewModel.selectedProject?.path == removed.path {
+                    viewModel.selectedProject = nil
+                }
+                if coordinator.selectedProjectName == removed.name {
+                    coordinator.selectedProjectName = nil
+                }
+                viewModel.load()
+                fileWatcher.updateProjectWatches(viewModel.dashboardPaths)
+            }
+        }
+        .sheet(item: $configEditorProject) { project in
+            ConfigEditorSheet(
+                context: serverContext,
+                project: project
+            )
+        }
+        // Confirmation dialog for the sidebar's "Remove from List" action.
+        // The action is registry-only (doesn't touch disk), but the name
+        // historically confused users into thinking it was a full delete.
+        // A confirmation with explicit wording clarifies scope before the
+        // click is destructive-looking but actually harmless.
+        .confirmationDialog(
+            removeFromListDialogTitle,
+            isPresented: Binding(
+                get: { pendingRemoveFromList != nil },
+                set: { if !$0 { pendingRemoveFromList = nil } }
+            ),
+            titleVisibility: .visible,
+            presenting: pendingRemoveFromList
+        ) { project in
+            Button("Remove from List") {
+                viewModel.removeProject(project)
+                if coordinator.selectedProjectName == project.name {
+                    coordinator.selectedProjectName = nil
+                }
+                pendingRemoveFromList = nil
+            }
+            Button("Cancel", role: .cancel) {
+                pendingRemoveFromList = nil
+            }
+        } message: { project in
+            Text(
+                "\(project.name) will be removed from Scarf's project list. " +
+                "Nothing on disk is touched — the folder, cron job, skills, and memory block all stay. " +
+                "To actually remove installed files, use \"Uninstall Template…\" instead."
+            )
+        }
+    }
+
+    /// Title string for the remove-from-list confirmation dialog. Kept
+    /// as a computed property so the dialog and any future reuse share
+    /// the exact same copy.
+    private var removeFromListDialogTitle: LocalizedStringKey {
+        "Remove from Scarf's project list?"
+    }
+
+    // MARK: - Toolbar
+
+    @ToolbarContentBuilder
+    private var templatesToolbar: some ToolbarContent {
+        ToolbarItem(placement: .primaryAction) {
+            Menu {
+                Button("Install from File…", systemImage: "tray.and.arrow.down") {
+                    openInstallFilePicker()
+                }
+                Button("Install from URL…", systemImage: "link") {
+                    installURLInput = ""
+                    showingInstallURLPrompt = true
+                }
+                Divider()
+                if let selected = viewModel.selectedProject {
+                    Button("Export \"\(selected.name)\" as Template…", systemImage: "tray.and.arrow.up") {
+                        exportSheetProject = selected
+                    }
+                } else {
+                    Button("Export as Template…", systemImage: "tray.and.arrow.up") {}
+                        .disabled(true)
+                }
+            } label: {
+                Label("Templates", systemImage: "shippingbox")
+            }
+        }
+    }
+
+    private var installURLSheet: some View {
+        VStack(alignment: .leading, spacing: 12) {
+            Text("Install Template from URL")
+                .font(.headline)
+            Text("Paste an https URL pointing at a .scarftemplate file.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+            TextField("https://example.com/my.scarftemplate", text: $installURLInput)
+                .textFieldStyle(.roundedBorder)
+            HStack {
+                Button("Cancel") { showingInstallURLPrompt = false }
+                    .keyboardShortcut(.cancelAction)
+                Spacer()
+                Button("Install") {
+                    if let url = URL(string: installURLInput), url.scheme?.lowercased() == "https" {
+                        installerViewModel.openRemoteURL(url)
+                        showingInstallURLPrompt = false
+                        showingInstallSheet = true
+                    }
+                }
+                .keyboardShortcut(.defaultAction)
+                .buttonStyle(.borderedProminent)
+                .disabled(URL(string: installURLInput)?.scheme?.lowercased() != "https")
+            }
+        }
+        .padding()
+        .frame(minWidth: 480)
+    }
+
+    /// Route a pending install URL to the right VM entry point. `file://`
+    /// URLs come from Finder double-clicks + the "Install from File…" flow
+    /// when routed via the router; `https://` URLs come from `scarf://`
+    /// deep links and the "Install from URL…" prompt.
+    private func dispatchPendingInstall(_ url: URL) {
+        if url.isFileURL {
+            installerViewModel.openLocalFile(url.path)
+        } else {
+            installerViewModel.openRemoteURL(url)
+        }
+        TemplateURLRouter.shared.consume()
+        showingInstallSheet = true
+    }
+
+    private func openInstallFilePicker() {
+        let panel = NSOpenPanel()
+        panel.canChooseDirectories = false
+        panel.canChooseFiles = true
+        panel.allowsMultipleSelection = false
+        // Accept both the declared Scarf template UTI and plain zip — the
+        // custom UTI wins for files with the .scarftemplate extension, and
+        // the zip fallback means an author distributing under .zip (e.g.
+        // before the UTI is registered on the receiving Mac) still works.
+        var types: [UTType] = [.zip]
+        if let templateType = UTType("com.scarf.template") {
+            types.insert(templateType, at: 0)
+        }
+        panel.allowedContentTypes = types
+        panel.allowsOtherFileTypes = true
+        panel.prompt = String(localized: "Install Template")
+        if panel.runModal() == .OK, let url = panel.url {
+            installerViewModel.openLocalFile(url.path)
+            showingInstallSheet = true
+        }
     }
 
     // MARK: - Project List
@@ -58,6 +279,32 @@ struct ProjectsView: View {
                     Text(project.name)
                 }
                 .tag(project)
+                .contextMenu {
+                    if isConfigurable(project) {
+                        Button("Configuration…", systemImage: "slider.horizontal.3") {
+                            configEditorProject = project
+                        }
+                    }
+                    if uninstaller.isTemplateInstalled(project: project) {
+                        // "Uninstall Template…" only appears for projects
+                        // installed from a `.scarftemplate`. Trailing
+                        // ellipsis signals a confirmation sheet follows
+                        // (macOS HIG convention); the sheet itself lists
+                        // every file/cron/skill that will be removed.
+                        Button("Uninstall Template (remove installed files)…", systemImage: "trash") {
+                            uninstallerViewModel.begin(project: project)
+                            showingUninstallSheet = true
+                        }
+                        Divider()
+                    }
+                    // "Remove from List" used to be "Remove from Scarf",
+                    // which users read as a full delete. Clarified label +
+                    // ellipsis + confirmation dialog all spell out that
+                    // this is registry-only; nothing on disk is touched.
+                    Button("Remove from List (keep files)…", systemImage: "minus.circle") {
+                        pendingRemoveFromList = project
+                    }
+                }
             }
             .listStyle(.sidebar)
 
@@ -69,10 +316,16 @@ struct ProjectsView: View {
                 .buttonStyle(.borderless)
                 Spacer()
                 if let selected = viewModel.selectedProject {
-                    Button(action: { viewModel.removeProject(selected) }) {
+                    // Route through the same confirmation dialog as the
+                    // context-menu "Remove from List" entry. The minus
+                    // icon is a drive-by click target right next to "+" —
+                    // confirming before mutating the registry stops the
+                    // "I clicked by accident and my project's gone" case.
+                    Button(action: { pendingRemoveFromList = selected }) {
                         Image(systemName: "minus")
                     }
                     .buttonStyle(.borderless)
+                    .help("Remove \(selected.name) from Scarf's project list (files are kept on disk)")
                 }
             }
             .padding(8)
@@ -150,7 +403,7 @@ struct ProjectsView: View {
                     HStack(spacing: 4) {
                         Image(systemName: tab == .dashboard ? "square.grid.2x2" : "globe")
                             .font(.caption)
-                        Text(tab.rawValue)
+                        Text(tab.displayName)
                             .font(.subheadline)
                     }
                     .padding(.horizontal, 12)
@@ -209,6 +462,25 @@ struct ProjectsView: View {
                     Image(systemName: "folder")
                 }
                 .buttonStyle(.borderless)
+                if isConfigurable(project) {
+                    Button {
+                        configEditorProject = project
+                    } label: {
+                        Image(systemName: "slider.horizontal.3")
+                    }
+                    .buttonStyle(.borderless)
+                    .help("Edit configuration")
+                }
+                if uninstaller.isTemplateInstalled(project: project) {
+                    Button {
+                        uninstallerViewModel.begin(project: project)
+                        showingUninstallSheet = true
+                    } label: {
+                        Image(systemName: "shippingbox.and.arrow.backward")
+                    }
+                    .buttonStyle(.borderless)
+                    .help("Uninstall template")
+                }
             }
         }
     }

scarf/scarf/Features/QuickCommands/ViewModels/QuickCommandsViewModel.swift

@@ -25,29 +25,33 @@ final class QuickCommandsViewModel {
     func load() {
         let ctx = context
         Task.detached { [weak self] in
-            let yaml = ctx.readText(ctx.paths.configYAML)
+            let result = Self.loadQuickCommands(context: ctx)
-            let result: [HermesQuickCommand] = {
-                guard let yaml else { return [] }
-                let parsed = HermesFileService.parseNestedYAML(yaml)
-                var byName: [String: (type: String, command: String)] = [:]
-                for (key, value) in parsed.values where key.hasPrefix("quick_commands.") {
-                    let parts = key.split(separator: ".", maxSplits: 2, omittingEmptySubsequences: false)
-                    guard parts.count == 3 else { continue }
-                    let name = String(parts[1])
-                    let field = String(parts[2])
-                    var existing = byName[name] ?? (type: "exec", command: "")
-                    let stripped = HermesFileService.stripYAMLQuotes(value)
-                    if field == "type" { existing.type = stripped }
-                    if field == "command" { existing.command = stripped }
-                    byName[name] = existing
-                }
-                return byName.map { HermesQuickCommand(name: $0.key, type: $0.value.type, command: $0.value.command) }
-                    .sorted { $0.name < $1.name }
-            }()
             await MainActor.run { [weak self] in self?.commands = result }
         }
     }
 
+    /// Parse `quick_commands` from `config.yaml` on the given context. Safe to
+    /// call from any actor — performs synchronous file I/O, so dispatch from a
+    /// detached task when called from `@MainActor`.
+    nonisolated static func loadQuickCommands(context: ServerContext) -> [HermesQuickCommand] {
+        guard let yaml = context.readText(context.paths.configYAML) else { return [] }
+        let parsed = HermesFileService.parseNestedYAML(yaml)
+        var byName: [String: (type: String, command: String)] = [:]
+        for (key, value) in parsed.values where key.hasPrefix("quick_commands.") {
+            let parts = key.split(separator: ".", maxSplits: 2, omittingEmptySubsequences: false)
+            guard parts.count == 3 else { continue }
+            let name = String(parts[1])
+            let field = String(parts[2])
+            var existing = byName[name] ?? (type: "exec", command: "")
+            let stripped = HermesFileService.stripYAMLQuotes(value)
+            if field == "type" { existing.type = stripped }
+            if field == "command" { existing.command = stripped }
+            byName[name] = existing
+        }
+        return byName.map { HermesQuickCommand(name: $0.key, type: $0.value.type, command: $0.value.command) }
+            .sorted { $0.name < $1.name }
+    }
+
     /// Check for obviously destructive shell strings. Display-only; we do not block.
     static func isDangerous(_ command: String) -> Bool {
         let lowered = command.lowercased()

scarf/scarf/Features/QuickCommands/Views/QuickCommandsView.swift

@@ -145,7 +145,7 @@ private struct QuickCommandEditor: View {
 
     var body: some View {
         VStack(alignment: .leading, spacing: 12) {
-            Text(initial == nil ? "Add Quick Command" : "Edit /\(initial!.name)")
+            (initial == nil ? Text("Add Quick Command") : Text("Edit /\(initial!.name)"))
                 .font(.headline)
             VStack(alignment: .leading, spacing: 4) {
                 Text("Name (no leading slash)")

scarf/scarf/Features/Servers/Views/ConnectionStatusPill.swift

@@ -31,7 +31,7 @@ struct ConnectionStatusPill: View {
                 Image(systemName: iconName)
                     .foregroundStyle(color)
                     .symbolRenderingMode(.hierarchical)
-                Text(label)
+                labelText
                     .font(.caption)
                     .foregroundStyle(.secondary)
                     .lineLimit(1)
@@ -39,7 +39,7 @@ struct ConnectionStatusPill: View {
             .padding(.horizontal, 4)
         }
         .buttonStyle(.plain)
-        .help(tooltip)
+        .help(tooltipText)
         .popover(isPresented: $showDetails, arrowEdge: .bottom) {
             errorDetails.frame(width: 400)
         }
@@ -70,27 +70,27 @@ struct ConnectionStatusPill: View {
         }
     }
 
-    private var label: String {
+    private var labelText: Text {
         switch status.status {
-        case .connected: return "Connected"
+        case .connected: return Text("Connected")
-        case .degraded: return "Connected — can't read Hermes state"
+        case .degraded: return Text("Connected — can't read Hermes state")
-        case .idle: return "Checking…"
+        case .idle: return Text("Checking…")
-        case .error(let message, _): return message
+        case .error(let message, _): return Text(verbatim: message)
         }
     }
 
-    private var tooltip: String {
+    private var tooltipText: Text {
         switch status.status {
         case .connected:
             if let ts = status.lastSuccess {
                 let fmt = RelativeDateTimeFormatter()
-                return "Last probe: \(fmt.localizedString(for: ts, relativeTo: Date()))"
+                return Text("Last probe: \(fmt.localizedString(for: ts, relativeTo: Date()))")
             }
-            return "Connected"
+            return Text("Connected")
         case .degraded(let reason):
-            return "SSH works but \(reason). Click for diagnostics."
+            return Text("SSH works but \(reason). Click for diagnostics.")
-        case .idle: return "Waiting for first probe"
+        case .idle: return Text("Waiting for first probe")
-        case .error(_, _): return "Click for details"
+        case .error: return Text("Click for details")
         }
     }
 

scarf/scarf/Features/Servers/Views/ManageServersView.swift

@@ -87,13 +87,32 @@ struct ManageServersView: View {
     }
 
     private var list: some View {
-        List {
+        let defaultID = registry.defaultServerID
+        return List {
+            // Local sits at the top so users can mark it as the open-on-launch
+            // default alongside remote servers. It's synthesized (not in
+            // `registry.entries`), so render it explicitly.
+            HStack(spacing: 10) {
+                defaultStar(for: ServerContext.local.id, currentDefault: defaultID)
+                Image(systemName: "laptopcomputer")
+                    .foregroundStyle(.blue)
+                VStack(alignment: .leading, spacing: 2) {
+                    Text("Local").font(.body)
+                    Text("This Mac")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+                Spacer()
+            }
+            .padding(.vertical, 4)
+
             ForEach(registry.entries) { entry in
                 HStack(spacing: 10) {
+                    defaultStar(for: entry.id, currentDefault: defaultID)
                     Image(systemName: "server.rack")
                         .foregroundStyle(.blue)
                     VStack(alignment: .leading, spacing: 2) {
-                        Text(entry.displayName).font(.body)
+                        Text(verbatim: entry.displayName).font(.body)
                         if case .ssh(let config) = entry.kind {
                             Text(summary(for: config))
                                 .font(.caption)
@@ -123,6 +142,24 @@ struct ManageServersView: View {
         .listStyle(.inset)
     }
 
+    /// A star button that marks the open-on-launch default. Filled + yellow
+    /// on the current default row (disabled, since clicking would be a
+    /// no-op); outline + secondary elsewhere, clicking promotes that row
+    /// to default.
+    @ViewBuilder
+    private func defaultStar(for id: ServerID, currentDefault: ServerID) -> some View {
+        let isDefault = id == currentDefault
+        Button {
+            registry.setDefaultServer(id)
+        } label: {
+            Image(systemName: isDefault ? "star.fill" : "star")
+                .foregroundStyle(isDefault ? .yellow : .secondary)
+        }
+        .buttonStyle(.borderless)
+        .disabled(isDefault)
+        .help(isDefault ? "Opens on launch" : "Set as default — open this server when Scarf launches.")
+    }
+
     private func summary(for config: SSHConfig) -> String {
         var s = ""
         if let user = config.user, !user.isEmpty { s += "\(user)@" }

scarf/scarf/Features/Servers/Views/ServerSwitcherToolbar.swift

@@ -37,7 +37,7 @@ struct ServerSwitcherToolbar: View {
                 Circle()
                     .fill(current.isRemote ? Color.blue : Color.green)
                     .frame(width: 8, height: 8)
-                Text(current.displayName)
+                Text(verbatim: current.displayName)
                     .font(.callout)
                     .lineLimit(1)
                 Image(systemName: "chevron.down")

scarf/scarf/Features/Sessions/ViewModels/SessionsViewModel.swift

@@ -159,12 +159,7 @@ final class SessionsViewModel {
         let dbPath = context.paths.stateDB
         let fileSize: String
         if let stat = context.makeTransport().stat(dbPath) {
-            let size = Double(stat.size)
+            fileSize = Int64(stat.size).formatted(.byteCount(style: .file))
-            if size >= FileSizeUnit.megabyte {
-                fileSize = String(format: "%.1f MB", size / FileSizeUnit.megabyte)
-            } else {
-                fileSize = String(format: "%.0f KB", size / FileSizeUnit.kilobyte)
-            }
         } else {
             fileSize = "unknown"
         }

scarf/scarf/Features/Sessions/Views/SessionDetailView.swift

@@ -60,7 +60,8 @@ struct SessionDetailView: View {
                     Label("\(session.reasoningTokens) reasoning", systemImage: "brain")
                 }
                 if let cost = session.displayCostUSD {
-                    Label(String(format: "$%.4f%@", cost, session.costIsActual ? "" : " est."), systemImage: "dollarsign.circle")
+                    let formattedCost = cost.formatted(.currency(code: "USD").precision(.fractionLength(4)))
+                    Label(session.costIsActual ? formattedCost : "\(formattedCost) est.", systemImage: "dollarsign.circle")
                 }
                 if let date = session.startedAt {
                     Label(date.formatted(.dateTime.month().day().hour().minute()), systemImage: "calendar")

scarf/scarf/Features/Settings/ViewModels/SettingsViewModel.swift

@@ -20,7 +20,6 @@ final class SettingsViewModel {
     var hermesRunning = false
     var rawConfigYAML = ""
     var personalities: [String] = []
-    var providers = ["anthropic", "openrouter", "nous", "openai-codex", "google-ai-studio", "xai", "ollama-cloud", "zai", "kimi-coding", "minimax"]
     var terminalBackends = ["local", "docker", "singularity", "modal", "daytona", "ssh"]
     var browserBackends = ["browseruse", "firecrawl", "local"]
     var ttsProviders = ["edge", "elevenlabs", "openai", "minimax", "mistral", "neutts"]

scarf/scarf/Features/Settings/Views/Components/ModelPickerSheet.swift

@@ -102,7 +102,7 @@ struct ModelPickerSheet: View {
                             .font(.system(.body, design: .default, weight: .medium))
                         Spacer()
                         if let ctx = model.contextDisplay {
-                            Text(ctx + " ctx")
+                            Text("\(ctx) ctx")
                                 .font(.caption2.monospaced())
                                 .foregroundStyle(.secondary)
                         }

scarf/scarf/Features/Settings/Views/Components/SettingsComponents.swift

@@ -6,7 +6,7 @@ import AppKit
 /// on large view bodies (per project guidance in CLAUDE.md).
 
 struct SettingsSection<Content: View>: View {
-    let title: String
+    let title: LocalizedStringKey
     let icon: String
     @ViewBuilder let content: Content
 
@@ -224,7 +224,7 @@ struct DoubleStepperRow: View {
                 .font(.caption)
                 .foregroundStyle(.secondary)
                 .frame(width: 160, alignment: .trailing)
-            Text(String(format: "%.2f", value))
+            Text(value.formatted(.number.precision(.fractionLength(2))))
                 .font(.system(.caption, design: .monospaced))
                 .frame(width: 70, alignment: .leading)
             Stepper("", value: Binding(

scarf/scarf/Features/Settings/Views/SettingsView.swift

@@ -26,6 +26,22 @@ struct SettingsView: View {
         case advanced = "Advanced"
 
         var id: String { rawValue }
+
+        var displayName: LocalizedStringResource {
+            switch self {
+            case .general: return "General"
+            case .display: return "Display"
+            case .agent: return "Agent"
+            case .terminal: return "Terminal"
+            case .browser: return "Browser"
+            case .voice: return "Voice"
+            case .memory: return "Memory"
+            case .auxiliary: return "Aux Models"
+            case .security: return "Security"
+            case .advanced: return "Advanced"
+            }
+        }
+
         var icon: String {
             switch self {
             case .general: return "gear"
@@ -56,7 +72,11 @@ struct SettingsView: View {
                         .frame(maxWidth: .infinity, alignment: .topLeading)
                     }
                     .tabItem {
-                        Label(tab.rawValue, systemImage: tab.icon)
+                        Label {
+                            Text(tab.displayName)
+                        } icon: {
+                            Image(systemName: tab.icon)
+                        }
                     }
                     .tag(tab)
                 }

scarf/scarf/Features/Settings/Views/Tabs/AuxiliaryTab.swift

@@ -6,7 +6,7 @@ struct AuxiliaryTab: View {
     @Bindable var viewModel: SettingsViewModel
 
     // Keyed by the config path name — matches `auxiliary.<task>.*` in config.yaml.
-    private let tasks: [(key: String, title: String, icon: String)] = [
+    private let tasks: [(key: String, title: LocalizedStringKey, icon: String)] = [
         ("vision", "Vision", "eye"),
         ("web_extract", "Web Extract", "doc.richtext"),
         ("compression", "Compression", "arrow.down.right.and.arrow.up.left.circle"),

scarf/scarf/Features/Skills/Views/SkillsView.swift

@@ -14,6 +14,14 @@ struct SkillsView: View {
         case hub = "Browse Hub"
         case updates = "Updates"
         var id: String { rawValue }
+
+        var displayName: LocalizedStringResource {
+            switch self {
+            case .installed: return "Installed"
+            case .hub: return "Browse Hub"
+            case .updates: return "Updates"
+            }
+        }
     }
 
     var body: some View {
@@ -34,7 +42,7 @@ struct SkillsView: View {
         HStack {
             Picker("", selection: $currentTab) {
                 ForEach(Tab.allCases) { tab in
-                    Text(tab.rawValue).tag(tab)
+                    Text(tab.displayName).tag(tab)
                 }
             }
             .pickerStyle(.segmented)

scarf/scarf/Features/Templates/ViewModels/TemplateConfigEditorViewModel.swift

@@ -0,0 +1,118 @@
+import Foundation
+import Observation
+import os
+
+/// Drives the post-install "Configuration" button on the project
+/// dashboard. Loads `<project>/.scarf/manifest.json` + `config.json`,
+/// hands a `TemplateConfigViewModel` seeded with current values to the
+/// sheet, then writes the edited values back on commit.
+///
+/// Smaller surface than `TemplateInstallerViewModel` — no unzipping,
+/// no parent-dir picking, no cron CLI. Just: read → edit → save.
+@Observable
+@MainActor
+final class TemplateConfigEditorViewModel {
+    private static let logger = Logger(subsystem: "com.scarf", category: "TemplateConfigEditorViewModel")
+
+    enum Stage: Sendable {
+        case idle
+        case loading
+        /// Manifest + config loaded; the sheet is displaying the form.
+        case editing
+        case saving
+        case succeeded
+        case failed(String)
+        /// Project wasn't installed from a schemaful template — no
+        /// manifest cache on disk. The dashboard button is hidden in
+        /// this case so we shouldn't hit this stage normally.
+        case notConfigurable
+    }
+
+    let context: ServerContext
+    let project: ProjectEntry
+    private let configService: ProjectConfigService
+
+    init(context: ServerContext, project: ProjectEntry) {
+        self.context = context
+        self.project = project
+        self.configService = ProjectConfigService(context: context)
+    }
+
+    var stage: Stage = .idle
+    var manifest: ProjectTemplateManifest?
+    var currentValues: [String: TemplateConfigValue] = [:]
+
+    /// Non-nil while `.editing`; used to construct the sheet's VM.
+    var formViewModel: TemplateConfigViewModel?
+
+    /// Load the cached manifest + current config values, then move to
+    /// `.editing` so the sheet can render the form.
+    func begin() {
+        stage = .loading
+        let service = configService
+        let project = project
+        Task.detached { [weak self] in
+            do {
+                guard let cachedManifest = try service.loadCachedManifest(project: project),
+                      let schema = cachedManifest.config,
+                      !schema.isEmpty else {
+                    await MainActor.run { [weak self] in
+                        self?.stage = .notConfigurable
+                    }
+                    return
+                }
+                let configFile = try service.load(project: project)
+                await MainActor.run { [weak self] in
+                    guard let self else { return }
+                    self.manifest = cachedManifest
+                    self.currentValues = configFile?.values ?? [:]
+                    self.formViewModel = TemplateConfigViewModel(
+                        schema: schema,
+                        templateId: cachedManifest.id,
+                        templateSlug: cachedManifest.slug,
+                        initialValues: self.currentValues,
+                        mode: .edit(project: project)
+                    )
+                    self.stage = .editing
+                }
+            } catch {
+                Self.logger.error("couldn't load config for \(project.path, privacy: .public): \(error.localizedDescription, privacy: .public)")
+                await MainActor.run { [weak self] in
+                    self?.stage = .failed(error.localizedDescription)
+                }
+            }
+        }
+    }
+
+    /// Called when the sheet's commit succeeded. Persists the edited
+    /// values to `<project>/.scarf/config.json`. Secrets are already
+    /// in the Keychain — the VM's commit step wrote them.
+    func save(values: [String: TemplateConfigValue]) {
+        guard let manifest else { return }
+        stage = .saving
+        let service = configService
+        let project = project
+        Task.detached { [weak self] in
+            do {
+                try service.save(
+                    project: project,
+                    templateId: manifest.id,
+                    values: values
+                )
+                await MainActor.run { [weak self] in
+                    self?.stage = .succeeded
+                }
+            } catch {
+                Self.logger.error("couldn't save config for \(project.path, privacy: .public): \(error.localizedDescription, privacy: .public)")
+                await MainActor.run { [weak self] in
+                    self?.stage = .failed(error.localizedDescription)
+                }
+            }
+        }
+    }
+
+    func cancel() {
+        stage = .idle
+        formViewModel = nil
+    }
+}

scarf/scarf/Features/Templates/ViewModels/TemplateConfigViewModel.swift

@@ -0,0 +1,198 @@
+import Foundation
+import Observation
+import os
+
+/// Drives the configure form for template install + post-install editing.
+///
+/// **Timing of secret storage.** The VM keeps freshly-entered secret bytes
+/// in-memory (`pendingSecrets`) until the user clicks the commit button.
+/// Only then does `commit()` push each secret through
+/// `ProjectConfigService.storeSecret` and get back a `keychainRef` URI.
+/// This means cancelling the sheet never leaves an orphan Keychain
+/// entry behind — the form is transactional from the user's POV.
+///
+/// **Validation.** Runs via `ProjectConfigService.validateValues` every
+/// time the user attempts to commit. Per-field errors are tracked in
+/// `errors` so the sheet can surface them inline with the offending field.
+/// No live validation on every keystroke — that creates a messy
+/// "error appears the moment you start typing" UX.
+@Observable
+@MainActor
+final class TemplateConfigViewModel {
+    private static let logger = Logger(subsystem: "com.scarf", category: "TemplateConfigViewModel")
+
+    enum Mode: Sendable {
+        /// User is filling in values for the first time as part of the
+        /// install flow. Secrets will be written to the Keychain when
+        /// `commit` succeeds.
+        case install
+        /// User is editing values for an already-installed project.
+        /// Existing keychain refs are preserved for fields the user
+        /// doesn't touch; only secrets the user actually changes get
+        /// re-written to the Keychain.
+        case edit(project: ProjectEntry)
+    }
+
+    let schema: TemplateConfigSchema
+    let templateId: String
+    let templateSlug: String
+    let mode: Mode
+    private let configService: ProjectConfigService
+
+    /// Current form values, keyed by field key. Non-secret values live
+    /// here directly; secret fields either hold a `.keychainRef(...)`
+    /// (existing, untouched in edit mode) or nothing at all (user
+    /// hasn't entered a secret yet, or they just cleared it).
+    var values: [String: TemplateConfigValue] = [:]
+
+    /// Raw secret bytes waiting to be written to the Keychain on
+    /// `commit()`. Indexed by field key. `values[key]` stays as its
+    /// current `.keychainRef(...)` (for edit mode) or missing (for
+    /// install mode) until commit swaps it for the freshly-written
+    /// ref URI.
+    var pendingSecrets: [String: Data] = [:]
+
+    /// One error per field with a problem. Populated by `commit()` on
+    /// validation failure; the sheet surfaces the message inline below
+    /// the offending control.
+    var errors: [String: String] = [:]
+
+    init(
+        schema: TemplateConfigSchema,
+        templateId: String,
+        templateSlug: String,
+        initialValues: [String: TemplateConfigValue] = [:],
+        mode: Mode,
+        configService: ProjectConfigService = ProjectConfigService()
+    ) {
+        self.schema = schema
+        self.templateId = templateId
+        self.templateSlug = templateSlug
+        self.mode = mode
+        self.configService = configService
+        self.values = Self.applyDefaults(schema: schema, initial: initialValues)
+    }
+
+    // MARK: - Field setters (the sheet calls these as controls change)
+
+    func setString(_ key: String, _ value: String) {
+        values[key] = .string(value)
+        errors.removeValue(forKey: key)
+    }
+
+    func setNumber(_ key: String, _ value: Double) {
+        values[key] = .number(value)
+        errors.removeValue(forKey: key)
+    }
+
+    func setBool(_ key: String, _ value: Bool) {
+        values[key] = .bool(value)
+        errors.removeValue(forKey: key)
+    }
+
+    func setList(_ key: String, _ items: [String]) {
+        values[key] = .list(items)
+        errors.removeValue(forKey: key)
+    }
+
+    /// Stage a new secret value. Doesn't hit the Keychain until
+    /// `commit()`. An empty `value` clears both the pending secret and
+    /// the field's stored keychainRef — only valid in edit mode, where
+    /// "empty" means "I want to remove this secret."
+    func setSecret(_ key: String, _ value: String) {
+        if value.isEmpty {
+            pendingSecrets.removeValue(forKey: key)
+            values.removeValue(forKey: key)
+        } else {
+            pendingSecrets[key] = Data(value.utf8)
+            // Keep any existing ref around; the sheet can display
+            // "(changed)" while the ref is still the old one. commit()
+            // overwrites on disk.
+        }
+        errors.removeValue(forKey: key)
+    }
+
+    // MARK: - Commit
+
+    /// Validate, persist secrets to the Keychain, and hand back the
+    /// final values dictionary. On validation failure, `errors` is
+    /// populated and the method returns `nil` without touching the
+    /// Keychain — the form is transactional.
+    ///
+    /// In install mode, `project` is required (secrets need a path
+    /// hash for their Keychain account). In edit mode it falls out of
+    /// the `.edit(project:)` associated value.
+    func commit(project: ProjectEntry? = nil) -> [String: TemplateConfigValue]? {
+        // Build the value set we're about to validate. For secrets
+        // that have a pending update, we treat them as present (we'll
+        // write them in a moment); for secrets already stored as
+        // keychainRef, we treat them as present too. Only a completely
+        // empty secret field is "missing."
+        var candidate = values
+        for key in pendingSecrets.keys {
+            // The field is about to have a fresh keychainRef — for
+            // validation purposes, use a placeholder ref so the type
+            // check passes. The real ref replaces it below.
+            candidate[key] = .keychainRef("pending://\(key)")
+        }
+        let validationErrors = ProjectConfigService.validateValues(candidate, against: schema)
+        guard validationErrors.isEmpty else {
+            var byField: [String: String] = [:]
+            for err in validationErrors {
+                guard let key = err.fieldKey else { continue }
+                byField[key] = err.message
+            }
+            self.errors = byField
+            return nil
+        }
+
+        // Validation passed — write the pending secrets to the Keychain.
+        let targetProject: ProjectEntry
+        switch mode {
+        case .install:
+            guard let project else {
+                Self.logger.error("commit(project:) called in install mode without a project")
+                return nil
+            }
+            targetProject = project
+        case .edit(let proj):
+            targetProject = proj
+        }
+
+        for (key, secret) in pendingSecrets {
+            do {
+                let ref = try configService.storeSecret(
+                    templateSlug: templateSlug,
+                    fieldKey: key,
+                    project: targetProject,
+                    secret: secret
+                )
+                values[key] = ref
+            } catch {
+                Self.logger.error("failed to store secret for \(key, privacy: .public): \(error.localizedDescription, privacy: .public)")
+                errors[key] = "Couldn't save secret to the Keychain: \(error.localizedDescription)"
+                return nil
+            }
+        }
+        pendingSecrets.removeAll()
+        errors.removeAll()
+        return values
+    }
+
+    // MARK: - Helpers
+
+    /// Seed the form with any author-supplied defaults for fields that
+    /// don't already have an initial value (from a saved config.json).
+    nonisolated private static func applyDefaults(
+        schema: TemplateConfigSchema,
+        initial: [String: TemplateConfigValue]
+    ) -> [String: TemplateConfigValue] {
+        var out = initial
+        for field in schema.fields where out[field.key] == nil {
+            if let def = field.defaultValue {
+                out[field.key] = def
+            }
+        }
+        return out
+    }
+}

scarf/scarf/Features/Templates/ViewModels/TemplateExporterViewModel.swift

@@ -0,0 +1,131 @@
+import Foundation
+import os
+
+/// Drives the template export sheet. Holds form state for the author-facing
+/// fields (id, name, version, description, …) and the selection of skills
+/// and cron jobs to include, then builds and writes the `.scarftemplate` on
+/// confirm.
+@Observable
+@MainActor
+final class TemplateExporterViewModel {
+    private static let logger = Logger(subsystem: "com.scarf", category: "TemplateExporterViewModel")
+
+    enum Stage: Sendable {
+        case idle
+        case exporting
+        case succeeded(path: String)
+        case failed(String)
+    }
+
+    let context: ServerContext
+    let project: ProjectEntry
+    private let exporter: ProjectTemplateExporter
+
+    init(context: ServerContext, project: ProjectEntry) {
+        self.context = context
+        self.project = project
+        self.exporter = ProjectTemplateExporter(context: context)
+
+        self.templateName = project.name
+        self.templateId = "you/\(ProjectTemplateExporter.slugify(project.name))"
+    }
+
+    // Form fields
+    var templateId: String
+    var templateName: String
+    var templateVersion: String = "1.0.0"
+    var templateDescription: String = ""
+    var authorName: String = ""
+    var authorURL: String = ""
+    var category: String = ""
+    var tags: String = ""
+    var includeSkillIds: Set<String> = []
+    var includeCronJobIds: Set<String> = []
+    var memoryAppendix: String = ""
+
+    // Derived: what the author can pick from
+    var availableSkills: [HermesSkill] = []
+    var availableCronJobs: [HermesCronJob] = []
+
+    var stage: Stage = .idle
+
+    func load() {
+        let ctx = context
+        Task.detached { [weak self] in
+            let service = HermesFileService(context: ctx)
+            let skills = service.loadSkills().flatMap(\.skills)
+            let jobs = service.loadCronJobs()
+            await MainActor.run { [weak self] in
+                self?.availableSkills = skills
+                self?.availableCronJobs = jobs
+            }
+        }
+    }
+
+    func previewPlan() -> ProjectTemplateExporter.ExportPlan {
+        exporter.previewPlan(for: currentInputs)
+    }
+
+    /// Kick off the export, writing to `outputPath`. The caller is
+    /// responsible for bouncing the user through an `NSSavePanel` to get
+    /// that path.
+    func export(to outputPath: String) {
+        stage = .exporting
+        let exporter = exporter
+        let inputs = currentInputs
+        Task.detached { [weak self] in
+            do {
+                try exporter.export(inputs: inputs, outputZipPath: outputPath)
+                await MainActor.run { [weak self] in
+                    self?.stage = .succeeded(path: outputPath)
+                }
+            } catch {
+                await MainActor.run { [weak self] in
+                    self?.stage = .failed(error.localizedDescription)
+                }
+            }
+        }
+    }
+
+    // MARK: - Private
+
+    private var currentInputs: ProjectTemplateExporter.ExportInputs {
+        let parsedTags = tags
+            .split(separator: ",")
+            .map { $0.trimmingCharacters(in: .whitespaces) }
+            .filter { !$0.isEmpty }
+        let trimmedAppendix = memoryAppendix.trimmingCharacters(in: .whitespacesAndNewlines)
+        return ProjectTemplateExporter.ExportInputs(
+            project: project,
+            templateId: templateId.trimmingCharacters(in: .whitespaces),
+            templateName: templateName.trimmingCharacters(in: .whitespaces),
+            templateVersion: templateVersion.trimmingCharacters(in: .whitespaces),
+            description: templateDescription.trimmingCharacters(in: .whitespaces),
+            authorName: authorName.isEmpty ? nil : authorName,
+            authorUrl: authorURL.isEmpty ? nil : authorURL,
+            category: category.isEmpty ? nil : category,
+            tags: parsedTags,
+            includeSkillIds: Array(includeSkillIds),
+            includeCronJobIds: Array(includeCronJobIds),
+            memoryAppendix: trimmedAppendix.isEmpty ? nil : trimmedAppendix
+        )
+    }
+}
+
+extension ProjectTemplateExporter {
+    /// Lowercase-and-hyphenate a human name into something safe for a
+    /// template id suffix. Only used to seed the default id in the export
+    /// form — the author can overwrite it.
+    nonisolated static func slugify(_ raw: String) -> String {
+        let lower = raw.lowercased()
+        let mapped = lower.unicodeScalars.map { scalar -> Character in
+            let c = Character(scalar)
+            if c.isLetter || c.isNumber { return c }
+            return "-"
+        }
+        let collapsed = String(mapped)
+            .split(separator: "-", omittingEmptySubsequences: true)
+            .joined(separator: "-")
+        return collapsed.isEmpty ? "template" : collapsed
+    }
+}

scarf/scarf/Features/Templates/ViewModels/TemplateInstallerViewModel.swift

@@ -0,0 +1,230 @@
+import Foundation
+import os
+
+/// Drives the template install sheet. Handles three entry points:
+/// 1. `openLocalFile(_:)` — user picked a `.scarftemplate` from disk.
+/// 2. `openRemoteURL(_:)` — user pasted/deeplinked a https URL.
+/// 3. `confirmInstall()` — user clicked "Install" in the preview sheet.
+///
+/// The view model owns one ephemeral temp dir at a time (the unpacked
+/// bundle). `cancel()` or `confirmInstall()` removes it.
+@Observable
+@MainActor
+final class TemplateInstallerViewModel {
+    private static let logger = Logger(subsystem: "com.scarf", category: "TemplateInstallerViewModel")
+
+    enum Stage: Sendable {
+        case idle
+        case fetching(sourceDescription: String)
+        case inspecting
+        case awaitingParentDirectory
+        /// Template declared a non-empty config schema; the sheet
+        /// presents `TemplateConfigSheet` before continuing to the
+        /// preview. Schema-less templates skip this stage entirely.
+        case awaitingConfig
+        case planned
+        case installing
+        case succeeded(installed: ProjectEntry)
+        case failed(String)
+    }
+
+    let context: ServerContext
+    private let templateService: ProjectTemplateService
+    private let installer: ProjectTemplateInstaller
+
+    init(context: ServerContext) {
+        self.context = context
+        self.templateService = ProjectTemplateService(context: context)
+        self.installer = ProjectTemplateInstaller(context: context)
+    }
+
+    var stage: Stage = .idle
+    var inspection: TemplateInspection?
+    var plan: TemplateInstallPlan?
+    var chosenParentDirectory: String?
+    /// README body preloaded off MainActor when inspection completes, so the
+    /// preview sheet can render it without hitting `String(contentsOf:)` from
+    /// inside a View body.
+    var readmeBody: String?
+
+    // MARK: - Entry points
+
+    /// Inspect a local `.scarftemplate` file. Moves stage to `.inspecting`
+    /// then either `.awaitingParentDirectory` or `.failed`. The unpacked
+    /// README body is read off MainActor here and stored on the VM so the
+    /// preview sheet doesn't do sync I/O during View body evaluation.
+    func openLocalFile(_ zipPath: String) {
+        resetTempState()
+        stage = .inspecting
+        let service = templateService
+        Task.detached { [weak self] in
+            do {
+                let inspection = try service.inspect(zipPath: zipPath)
+                let readme = Self.readReadme(unpackedDir: inspection.unpackedDir)
+                await MainActor.run { [weak self] in
+                    guard let self else { return }
+                    self.inspection = inspection
+                    self.readmeBody = readme
+                    self.stage = .awaitingParentDirectory
+                }
+            } catch {
+                await MainActor.run { [weak self] in
+                    self?.stage = .failed(error.localizedDescription)
+                }
+            }
+        }
+    }
+
+    /// Read README.md from an unpacked template dir. Nonisolated so the
+    /// inspect task can call it off MainActor. Returns `nil` on any I/O
+    /// failure — the preview sheet treats a nil README as "no section."
+    nonisolated private static func readReadme(unpackedDir: String) -> String? {
+        let path = unpackedDir + "/README.md"
+        do {
+            return try String(contentsOf: URL(fileURLWithPath: path), encoding: .utf8)
+        } catch {
+            Logger(subsystem: "com.scarf", category: "TemplateInstallerViewModel")
+                .warning("couldn't read README at \(path, privacy: .public): \(error.localizedDescription, privacy: .public)")
+            return nil
+        }
+    }
+
+    /// Download a https `.scarftemplate` to a temp file, then hand off to
+    /// `openLocalFile`. The 50 MB cap matches the plan — templates shouldn't
+    /// be anywhere near that, and rejecting huge downloads is cheap defense.
+    ///
+    /// Content-Length is checked first as an early-out, but chunked
+    /// transfer responses omit that header. The authoritative check is the
+    /// actual on-disk file size after the download completes — it runs
+    /// unconditionally and covers the chunked-transfer case.
+    func openRemoteURL(_ url: URL) {
+        resetTempState()
+        stage = .fetching(sourceDescription: url.host ?? url.absoluteString)
+        Task.detached { [weak self] in
+            let maxBytes: Int64 = 50 * 1024 * 1024
+            do {
+                let tempZip = NSTemporaryDirectory() + "scarf-template-download-" + UUID().uuidString + ".scarftemplate"
+                let (tempURL, response) = try await URLSession.shared.download(from: url)
+                defer { try? FileManager.default.removeItem(at: tempURL) }
+                if let httpResponse = response as? HTTPURLResponse {
+                    guard (200...299).contains(httpResponse.statusCode) else {
+                        throw ProjectTemplateError.unzipFailed("HTTP \(httpResponse.statusCode)")
+                    }
+                    if let length = httpResponse.value(forHTTPHeaderField: "Content-Length"),
+                       let bytes = Int64(length), bytes > maxBytes {
+                        throw ProjectTemplateError.unzipFailed("template exceeds 50 MB size cap (\(bytes) bytes)")
+                    }
+                }
+                // Unconditional post-download size check — catches chunked
+                // responses that ship no Content-Length. The download already
+                // hit disk, but refusing to *process* it bounds the blast
+                // radius to one temp file that gets removed in the defer.
+                let attrs = try FileManager.default.attributesOfItem(atPath: tempURL.path)
+                let actualSize = (attrs[.size] as? NSNumber)?.int64Value ?? 0
+                guard actualSize <= maxBytes else {
+                    throw ProjectTemplateError.unzipFailed("template exceeds 50 MB size cap (\(actualSize) bytes)")
+                }
+                try FileManager.default.moveItem(atPath: tempURL.path, toPath: tempZip)
+                await MainActor.run { [weak self] in
+                    self?.openLocalFile(tempZip)
+                }
+            } catch {
+                await MainActor.run { [weak self] in
+                    self?.stage = .failed("Couldn't fetch template: \(error.localizedDescription)")
+                }
+            }
+        }
+    }
+
+    // MARK: - Planning + confirmation
+
+    /// Finalize the plan now that the user has picked a parent directory.
+    func pickParentDirectory(_ parentDir: String) {
+        guard let inspection else { return }
+        chosenParentDirectory = parentDir
+        let service = templateService
+        Task.detached { [weak self] in
+            do {
+                let plan = try service.buildPlan(inspection: inspection, parentDir: parentDir)
+                await MainActor.run { [weak self] in
+                    guard let self else { return }
+                    self.plan = plan
+                    // If the template declares a non-empty config
+                    // schema, insert the configure step before the
+                    // preview sheet. Otherwise go straight to .planned.
+                    if let schema = plan.configSchema, !schema.isEmpty {
+                        self.stage = .awaitingConfig
+                    } else {
+                        self.stage = .planned
+                    }
+                }
+            } catch {
+                await MainActor.run { [weak self] in
+                    self?.stage = .failed(error.localizedDescription)
+                }
+            }
+        }
+    }
+
+    /// Called by `TemplateInstallSheet` once the user has filled in
+    /// the configure form and `TemplateConfigViewModel.commit()`
+    /// succeeded. Stashes the values in the plan and advances to the
+    /// preview stage (`.planned`). Secrets in `values` are already
+    /// `.keychainRef(...)` — the VM's commit step wrote them to the
+    /// Keychain.
+    func submitConfig(values: [String: TemplateConfigValue]) {
+        guard var plan else { return }
+        plan.configValues = values
+        self.plan = plan
+        stage = .planned
+    }
+
+    /// Called when the user cancels out of the configure step without
+    /// committing. Returns to `.awaitingParentDirectory` so they can
+    /// try again (or dismiss the whole sheet).
+    func cancelConfig() {
+        stage = .awaitingParentDirectory
+    }
+
+    func confirmInstall() {
+        guard let plan else { return }
+        stage = .installing
+        let installer = installer
+        let service = templateService
+        Task.detached { [weak self] in
+            do {
+                let entry = try installer.install(plan: plan)
+                service.cleanupTempDir(plan.unpackedDir)
+                await MainActor.run { [weak self] in
+                    guard let self else { return }
+                    self.stage = .succeeded(installed: entry)
+                    self.inspection = nil
+                    self.plan = nil
+                    self.chosenParentDirectory = nil
+                    self.readmeBody = nil
+                }
+            } catch {
+                await MainActor.run { [weak self] in
+                    self?.stage = .failed(error.localizedDescription)
+                }
+            }
+        }
+    }
+
+    // MARK: - Cleanup
+
+    func cancel() {
+        resetTempState()
+        stage = .idle
+    }
+
+    private func resetTempState() {
+        if let inspection {
+            templateService.cleanupTempDir(inspection.unpackedDir)
+        }
+        inspection = nil
+        plan = nil
+        chosenParentDirectory = nil
+        readmeBody = nil
+    }
+}

scarf/scarf/Features/Templates/ViewModels/TemplateUninstallerViewModel.swift

@@ -0,0 +1,110 @@
+import Foundation
+import os
+
+/// Drives the template-uninstall sheet. Mirrors the installer VM in
+/// stage shape: open a plan (`begin`), preview it, confirm or cancel.
+@Observable
+@MainActor
+final class TemplateUninstallerViewModel {
+    private static let logger = Logger(subsystem: "com.scarf", category: "TemplateUninstallerViewModel")
+
+    enum Stage: Sendable {
+        case idle
+        case loading
+        case planned
+        case uninstalling
+        case succeeded(removed: ProjectEntry)
+        case failed(String)
+    }
+
+    /// Snapshot of "what survived the uninstall" — surfaced in the
+    /// success screen so the user understands why the project directory
+    /// is or isn't gone from disk. Computed from the plan right before
+    /// executing it (`plan` itself is nil'd on success, so we can't
+    /// reach back for this info after the fact).
+    struct PreservedOutcome: Sendable {
+        /// True when the uninstaller removed the project dir (nothing
+        /// user-owned was left inside). In this case `preservedPaths`
+        /// is empty and the success view skips the banner entirely.
+        let projectDirRemoved: Bool
+        /// Absolute paths of files the uninstaller refused to touch
+        /// because they weren't installed by the template (typically
+        /// `status-log.md` after the cron ran, or anything the user
+        /// dropped into the project dir manually).
+        let preservedPaths: [String]
+        /// Project dir — echoed back so the success view can show the
+        /// user where the orphan files now live.
+        let projectDir: String
+    }
+
+    let context: ServerContext
+    private let uninstaller: ProjectTemplateUninstaller
+
+    init(context: ServerContext) {
+        self.context = context
+        self.uninstaller = ProjectTemplateUninstaller(context: context)
+    }
+
+    var stage: Stage = .idle
+    var plan: TemplateUninstallPlan?
+    /// Populated on transition to `.succeeded`. Nil whenever the user
+    /// re-enters the flow (cancel/begin both clear it).
+    var preservedOutcome: PreservedOutcome?
+
+    /// Load the `template.lock.json` for the given project and build a
+    /// removal plan. Moves stage to `.planned` on success.
+    func begin(project: ProjectEntry) {
+        stage = .loading
+        preservedOutcome = nil
+        let uninstaller = uninstaller
+        Task.detached { [weak self] in
+            do {
+                let plan = try uninstaller.loadUninstallPlan(for: project)
+                await MainActor.run { [weak self] in
+                    guard let self else { return }
+                    self.plan = plan
+                    self.stage = .planned
+                }
+            } catch {
+                await MainActor.run { [weak self] in
+                    self?.stage = .failed(error.localizedDescription)
+                }
+            }
+        }
+    }
+
+    func confirmUninstall() {
+        guard let plan else { return }
+        stage = .uninstalling
+        let uninstaller = uninstaller
+        // Capture the preservation shape before executing — the plan
+        // itself gets nil'd on success and we want the banner to show
+        // whatever was true at the moment of removal.
+        let outcome = PreservedOutcome(
+            projectDirRemoved: plan.projectDirBecomesEmpty,
+            preservedPaths: plan.extraProjectEntries,
+            projectDir: plan.project.path
+        )
+        Task.detached { [weak self] in
+            do {
+                try uninstaller.uninstall(plan: plan)
+                await MainActor.run { [weak self] in
+                    guard let self else { return }
+                    self.preservedOutcome = outcome
+                    self.stage = .succeeded(removed: plan.project)
+                    self.plan = nil
+                }
+            } catch {
+                await MainActor.run { [weak self] in
+                    self?.stage = .failed(error.localizedDescription)
+                }
+            }
+        }
+    }
+
+    func cancel() {
+        plan = nil
+        preservedOutcome = nil
+        stage = .idle
+    }
+}

scarf/scarf/Features/Templates/Views/ConfigEditorSheet.swift

@@ -0,0 +1,133 @@
+import SwiftUI
+
+/// Post-install configuration editor. Thin wrapper around the same
+/// `TemplateConfigSheet` the install flow uses — owns a
+/// `TemplateConfigEditorViewModel` that loads the cached manifest +
+/// current values from `<project>/.scarf/`, feeds them to the form,
+/// and writes the edited values back to `config.json` on commit.
+///
+/// Entry points: right-click on the project list (when the project has
+/// a cached manifest) and a button on the dashboard header (shown
+/// only when `isConfigurable` is true).
+struct ConfigEditorSheet: View {
+    @Environment(\.dismiss) private var dismiss
+    @State private var viewModel: TemplateConfigEditorViewModel
+
+    init(context: ServerContext, project: ProjectEntry) {
+        _viewModel = State(
+            initialValue: TemplateConfigEditorViewModel(
+                context: context,
+                project: project
+            )
+        )
+    }
+
+    var body: some View {
+        Group {
+            switch viewModel.stage {
+            case .idle, .loading:
+                VStack(spacing: 12) {
+                    ProgressView()
+                    Text("Loading configuration…")
+                        .font(.subheadline)
+                        .foregroundStyle(.secondary)
+                }
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+                .frame(minWidth: 560, minHeight: 320)
+                .padding()
+            case .editing:
+                if let form = viewModel.formViewModel,
+                   let manifest = viewModel.manifest {
+                    TemplateConfigSheet(
+                        viewModel: form,
+                        title: "Configure \(manifest.name)",
+                        commitLabel: "Save",
+                        project: nil,  // edit mode; VM carries the project
+                        onCommit: { values in
+                            viewModel.save(values: values)
+                        },
+                        onCancel: {
+                            viewModel.cancel()
+                            dismiss()
+                        }
+                    )
+                } else {
+                    unexpectedState
+                }
+            case .saving:
+                VStack(spacing: 12) {
+                    ProgressView()
+                    Text("Saving…")
+                        .font(.subheadline)
+                        .foregroundStyle(.secondary)
+                }
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+                .frame(minWidth: 560, minHeight: 320)
+                .padding()
+            case .succeeded:
+                VStack(spacing: 16) {
+                    Image(systemName: "checkmark.circle.fill")
+                        .font(.system(size: 48))
+                        .foregroundStyle(.green)
+                    Text("Configuration saved").font(.title2.bold())
+                    Button("Done") { dismiss() }
+                        .keyboardShortcut(.defaultAction)
+                        .buttonStyle(.borderedProminent)
+                }
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+                .frame(minWidth: 560, minHeight: 280)
+                .padding()
+            case .failed(let message):
+                VStack(spacing: 16) {
+                    Image(systemName: "exclamationmark.triangle.fill")
+                        .font(.system(size: 48))
+                        .foregroundStyle(.orange)
+                    Text("Couldn't save").font(.title2.bold())
+                    Text(message)
+                        .font(.subheadline)
+                        .foregroundStyle(.secondary)
+                        .multilineTextAlignment(.center)
+                    Button("Close") { dismiss() }
+                        .keyboardShortcut(.defaultAction)
+                }
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+                .frame(minWidth: 560, minHeight: 280)
+                .padding()
+            case .notConfigurable:
+                VStack(spacing: 16) {
+                    Image(systemName: "slider.horizontal.3")
+                        .font(.system(size: 40))
+                        .foregroundStyle(.secondary)
+                    Text("No configuration")
+                        .font(.title3.bold())
+                    Text("This project wasn't installed from a schemaful template.")
+                        .font(.subheadline)
+                        .foregroundStyle(.secondary)
+                        .multilineTextAlignment(.center)
+                    Button("Close") { dismiss() }
+                        .keyboardShortcut(.defaultAction)
+                }
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+                .frame(minWidth: 560, minHeight: 280)
+                .padding()
+            }
+        }
+        .task { viewModel.begin() }
+    }
+
+    private var unexpectedState: some View {
+        VStack(spacing: 12) {
+            Image(systemName: "questionmark.circle")
+                .font(.system(size: 40))
+                .foregroundStyle(.secondary)
+            Text("Internal state inconsistency — please close and re-open.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+            Button("Close") { dismiss() }
+                .keyboardShortcut(.defaultAction)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .frame(minWidth: 560, minHeight: 280)
+        .padding()
+    }
+}

scarf/scarf/Features/Templates/Views/TemplateConfigSheet.swift

@@ -0,0 +1,422 @@
+import SwiftUI
+
+/// The configure form rendered for template install + post-install
+/// editing. One row per schema field; controls dispatch by field type.
+/// Commit button returns the finalized values via `onCommit` — in
+/// install mode the caller stashes them in the install plan; in edit
+/// mode the caller writes them straight to `<project>/.scarf/config.json`.
+struct TemplateConfigSheet: View {
+    @Environment(\.dismiss) private var dismiss
+
+    @State var viewModel: TemplateConfigViewModel
+    let title: LocalizedStringKey
+    let commitLabel: LocalizedStringKey
+    /// In install mode the caller passes the planned `ProjectEntry`
+    /// (project dir path is the unique key for the Keychain secret).
+    /// In edit mode the VM already holds the project; pass `nil` here.
+    let project: ProjectEntry?
+    let onCommit: ([String: TemplateConfigValue]) -> Void
+    let onCancel: () -> Void
+
+    var body: some View {
+        VStack(spacing: 0) {
+            header
+            Divider()
+            ScrollView {
+                // `.frame(maxWidth: .infinity, alignment: .leading)` is
+                // load-bearing: without it, SwiftUI resolves width
+                // bottom-up and an unbreakable token in a child (e.g. a
+                // raw URL inside a field description rendered via
+                // AttributedString markdown) sets the whole VStack's
+                // ideal width to that token's length. ScrollView's
+                // content then exceeds the sheet's viewport, the outer
+                // `.frame(minWidth: 560)` grows to content width, and
+                // the window clips the result with labels cut off on
+                // the left + URL spilling off the right. With the
+                // explicit maxWidth, the ScrollView's offered width
+                // propagates down and the description Text's
+                // `.fixedSize(horizontal: false, vertical: true)`
+                // wraps at whitespace boundaries as intended.
+                VStack(alignment: .leading, spacing: 18) {
+                    if viewModel.schema.fields.isEmpty {
+                        ContentUnavailableView(
+                            "No fields",
+                            systemImage: "slider.horizontal.3",
+                            description: Text("This template has no configuration fields.")
+                        )
+                        .frame(maxWidth: .infinity, minHeight: 120)
+                    } else {
+                        ForEach(viewModel.schema.fields) { field in
+                            fieldRow(field)
+                        }
+                    }
+                    if let rec = viewModel.schema.modelRecommendation {
+                        modelRecommendation(rec)
+                    }
+                }
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .padding(20)
+            }
+            Divider()
+            footer
+        }
+        .frame(minWidth: 560, minHeight: 480)
+    }
+
+    // MARK: - Header / footer
+
+    @ViewBuilder
+    private var header: some View {
+        HStack {
+            VStack(alignment: .leading, spacing: 2) {
+                Text(title).font(.title2.bold())
+                Text(viewModel.templateId)
+                    .font(.caption.monospaced())
+                    .foregroundStyle(.secondary)
+            }
+            Spacer()
+        }
+        .padding(16)
+    }
+
+    @ViewBuilder
+    private var footer: some View {
+        HStack {
+            Button("Cancel") {
+                // Caller owns dismissal — this view is used both as a
+                // standalone sheet (ConfigEditorSheet, where the caller
+                // wants dismissal) AND inlined inside the install sheet
+                // (TemplateInstallSheet.configureView, where calling
+                // .dismiss here would tear down the OUTER install sheet
+                // and abort the flow before .planned is reached).
+                onCancel()
+            }
+            .keyboardShortcut(.cancelAction)
+            Spacer()
+            Button(commitLabel) {
+                if let finalized = viewModel.commit(project: project) {
+                    onCommit(finalized)
+                }
+                // Same dismissal-is-caller's-responsibility rule as
+                // Cancel — inside the install sheet, onCommit transitions
+                // stage to .planned and the outer view re-renders to
+                // show the preview. In the edit sheet, onCommit
+                // transitions the editor VM and its state machine
+                // handles dismissal via the success view's Done button.
+            }
+            .keyboardShortcut(.defaultAction)
+            .buttonStyle(.borderedProminent)
+        }
+        .padding(16)
+    }
+
+    // MARK: - Field rows
+
+    @ViewBuilder
+    private func fieldRow(_ field: TemplateConfigField) -> some View {
+        VStack(alignment: .leading, spacing: 6) {
+            HStack(alignment: .firstTextBaseline, spacing: 4) {
+                Text(field.label).font(.headline)
+                if field.required {
+                    Text("*")
+                        .font(.headline)
+                        .foregroundStyle(.red)
+                }
+                Spacer()
+                Text(field.type.rawValue)
+                    .font(.caption2.monospaced())
+                    .foregroundStyle(.secondary)
+            }
+            if let description = field.description, !description.isEmpty {
+                // Inline markdown so descriptions can include
+                // `[Create one](https://…)`-style links to token
+                // generation pages, **bold** emphasis on important
+                // prerequisites, etc. Raw URLs (not wrapped in
+                // markdown link syntax) will still render but can't
+                // word-break mid-token — keep the parent maxWidth
+                // constraint below so a rogue raw URL wraps cleanly
+                // instead of expanding the entire sheet.
+                TemplateMarkdown.inlineText(description)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+            control(for: field)
+            if let err = viewModel.errors[field.key] {
+                Label(err, systemImage: "exclamationmark.triangle.fill")
+                    .font(.caption)
+                    .foregroundStyle(.red)
+            }
+        }
+        // maxWidth: .infinity forces this row to span the column's
+        // full width so its internal description Text wraps instead
+        // of expanding the outer VStack when a description contains
+        // a long unbreakable token (raw URL, path, etc.). See the
+        // comment on the parent ScrollView's inner VStack.
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(12)
+        .background(
+            RoundedRectangle(cornerRadius: 8)
+                .fill(.background.secondary)
+        )
+    }
+
+    @ViewBuilder
+    private func control(for field: TemplateConfigField) -> some View {
+        switch field.type {
+        case .string:
+            StringControl(
+                value: stringBinding(for: field),
+                placeholder: field.placeholder
+            )
+        case .text:
+            TextControl(value: stringBinding(for: field))
+        case .number:
+            NumberControl(value: numberBinding(for: field))
+        case .bool:
+            BoolControl(label: field.label, value: boolBinding(for: field))
+        case .enum:
+            EnumControl(
+                options: field.options ?? [],
+                value: stringBinding(for: field)
+            )
+        case .list:
+            ListControl(items: listBinding(for: field))
+        case .secret:
+            SecretControl(
+                fieldKey: field.key,
+                placeholder: field.placeholder,
+                viewModel: viewModel
+            )
+        }
+    }
+
+    // MARK: - Model recommendation panel
+
+    private func modelRecommendation(_ rec: TemplateModelRecommendation) -> some View {
+        VStack(alignment: .leading, spacing: 6) {
+            Label("Recommended model", systemImage: "lightbulb")
+                .font(.caption.bold())
+                .foregroundStyle(.secondary)
+            Text(rec.preferred).font(.body.monospaced())
+            if let rationale = rec.rationale, !rationale.isEmpty {
+                Text(rationale)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+            if let alts = rec.alternatives, !alts.isEmpty {
+                Text("Also works: \(alts.joined(separator: ", "))")
+                    .font(.caption2)
+                    .foregroundStyle(.secondary)
+            }
+            Text("Scarf doesn't auto-switch your active model. Change it in Settings if you'd like.")
+                .font(.caption2)
+                .foregroundStyle(.tertiary)
+        }
+        .padding(12)
+        .background(
+            RoundedRectangle(cornerRadius: 8)
+                .fill(Color.accentColor.opacity(0.08))
+        )
+    }
+
+    // MARK: - Binding helpers (threading the VM through typed lenses)
+
+    private func stringBinding(for field: TemplateConfigField) -> Binding<String> {
+        Binding(
+            get: {
+                if case .string(let s) = viewModel.values[field.key] { return s }
+                return ""
+            },
+            set: { viewModel.setString(field.key, $0) }
+        )
+    }
+
+    private func numberBinding(for field: TemplateConfigField) -> Binding<Double> {
+        Binding(
+            get: {
+                if case .number(let n) = viewModel.values[field.key] { return n }
+                return 0
+            },
+            set: { viewModel.setNumber(field.key, $0) }
+        )
+    }
+
+    private func boolBinding(for field: TemplateConfigField) -> Binding<Bool> {
+        Binding(
+            get: {
+                if case .bool(let b) = viewModel.values[field.key] { return b }
+                return false
+            },
+            set: { viewModel.setBool(field.key, $0) }
+        )
+    }
+
+    private func listBinding(for field: TemplateConfigField) -> Binding<[String]> {
+        Binding(
+            get: {
+                if case .list(let items) = viewModel.values[field.key] { return items }
+                return []
+            },
+            set: { viewModel.setList(field.key, $0) }
+        )
+    }
+}
+
+// MARK: - Field controls
+
+private struct StringControl: View {
+    @Binding var value: String
+    let placeholder: String?
+    var body: some View {
+        TextField(placeholder ?? "", text: $value)
+            .textFieldStyle(.roundedBorder)
+    }
+}
+
+private struct TextControl: View {
+    @Binding var value: String
+    var body: some View {
+        TextEditor(text: $value)
+            .font(.body.monospaced())
+            .frame(minHeight: 80, maxHeight: 160)
+            .overlay(
+                RoundedRectangle(cornerRadius: 6)
+                    .stroke(.secondary.opacity(0.3))
+            )
+    }
+}
+
+private struct NumberControl: View {
+    @Binding var value: Double
+    var body: some View {
+        TextField("", value: $value, format: .number)
+            .textFieldStyle(.roundedBorder)
+    }
+}
+
+private struct BoolControl: View {
+    let label: String
+    @Binding var value: Bool
+    var body: some View {
+        Toggle(isOn: $value) {
+            Text(value ? "Enabled" : "Disabled")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+    }
+}
+
+private struct EnumControl: View {
+    let options: [TemplateConfigField.EnumOption]
+    @Binding var value: String
+    var body: some View {
+        // Always use the default Menu picker (dropdown). An earlier
+        // version switched to `.pickerStyle(.segmented)` when
+        // `options.count ≤ 4` for a more compact look, but on macOS
+        // segmented pickers size to the intrinsic width of all their
+        // labels concatenated — they refuse offered width constraints
+        // and refuse to wrap. A schema with three long labels like
+        // "Claude Opus 4 (Recommended - Most Capable)" produced a
+        // ~650pt picker that overflowed the 560pt sheet viewport,
+        // clipping the entire form. Menu pickers respect the fieldRow's
+        // offered width and show long labels in the popup list, so the
+        // sheet can't overflow regardless of label length.
+        Picker("", selection: $value) {
+            ForEach(options) { opt in
+                Text(opt.label).tag(opt.value)
+            }
+        }
+        .labelsHidden()
+    }
+}
+
+/// Variable-length list of string values. Each row is a text field
+/// with an inline remove button; a + button adds a trailing row.
+private struct ListControl: View {
+    @Binding var items: [String]
+    var body: some View {
+        VStack(alignment: .leading, spacing: 4) {
+            ForEach(items.indices, id: \.self) { i in
+                HStack(spacing: 6) {
+                    TextField("", text: Binding(
+                        get: { i < items.count ? items[i] : "" },
+                        set: { newValue in
+                            guard i < items.count else { return }
+                            items[i] = newValue
+                        }
+                    ))
+                    .textFieldStyle(.roundedBorder)
+                    Button {
+                        guard i < items.count else { return }
+                        items.remove(at: i)
+                    } label: {
+                        Image(systemName: "minus.circle")
+                    }
+                    .buttonStyle(.borderless)
+                    .disabled(items.count <= 1)
+                }
+            }
+            Button {
+                items.append("")
+            } label: {
+                Label("Add", systemImage: "plus.circle")
+                    .font(.caption)
+            }
+            .buttonStyle(.borderless)
+        }
+    }
+}
+
+/// Secret fields never echo the previously-stored value back. Instead
+/// we render "(unchanged)" when a Keychain ref already exists and let
+/// the user type over it if they want to replace. Empty input in edit
+/// mode signals "remove this secret entirely."
+private struct SecretControl: View {
+    let fieldKey: String
+    let placeholder: String?
+    @Bindable var viewModel: TemplateConfigViewModel
+
+    @State private var typedValue: String = ""
+    @State private var isRevealed: Bool = false
+
+    private var hasStoredRef: Bool {
+        if case .keychainRef = viewModel.values[fieldKey] { return true }
+        return false
+    }
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 4) {
+            HStack(spacing: 6) {
+                Group {
+                    if isRevealed {
+                        TextField(placeholder ?? "", text: $typedValue)
+                    } else {
+                        SecureField(placeholder ?? "", text: $typedValue)
+                    }
+                }
+                .textFieldStyle(.roundedBorder)
+                .onChange(of: typedValue) { _, new in
+                    viewModel.setSecret(fieldKey, new)
+                }
+                Button {
+                    isRevealed.toggle()
+                } label: {
+                    Image(systemName: isRevealed ? "eye.slash" : "eye")
+                }
+                .buttonStyle(.borderless)
+                .help(isRevealed ? "Hide" : "Show while typing")
+            }
+            if hasStoredRef && typedValue.isEmpty {
+                Text("Saved in Keychain — leave empty to keep the stored value.")
+                    .font(.caption2)
+                    .foregroundStyle(.secondary)
+            } else if !typedValue.isEmpty {
+                Text("Will be saved to the Keychain on commit.")
+                    .font(.caption2)
+                    .foregroundStyle(.secondary)
+            }
+        }
+    }
+}

scarf/scarf/Features/Templates/Views/TemplateExportSheet.swift

@@ -0,0 +1,259 @@
+import SwiftUI
+import AppKit
+import UniformTypeIdentifiers
+
+/// Author-facing sheet for exporting an existing project as a
+/// `.scarftemplate`. Mirrors the profile-export flow: fill in a few fields,
+/// pick which skills/cron jobs to include, save via NSSavePanel.
+struct TemplateExportSheet: View {
+    @Environment(\.dismiss) private var dismiss
+    @State var viewModel: TemplateExporterViewModel
+
+    var body: some View {
+        VStack(spacing: 0) {
+            switch viewModel.stage {
+            case .idle:
+                form
+            case .exporting:
+                VStack(spacing: 12) {
+                    ProgressView()
+                    Text("Building template…")
+                        .font(.subheadline)
+                        .foregroundStyle(.secondary)
+                }
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+            case .succeeded(let path):
+                VStack(spacing: 16) {
+                    Image(systemName: "checkmark.circle.fill")
+                        .font(.system(size: 48))
+                        .foregroundStyle(.green)
+                    Text("Exported").font(.title2.bold())
+                    Text(path)
+                        .font(.caption.monospaced())
+                        .foregroundStyle(.secondary)
+                    HStack {
+                        Button("Show in Finder") {
+                            NSWorkspace.shared.activateFileViewerSelecting([URL(fileURLWithPath: path)])
+                        }
+                        Button("Done") { dismiss() }
+                            .keyboardShortcut(.defaultAction)
+                    }
+                }
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+            case .failed(let message):
+                VStack(spacing: 16) {
+                    Image(systemName: "exclamationmark.triangle.fill")
+                        .font(.system(size: 48))
+                        .foregroundStyle(.orange)
+                    Text("Export Failed").font(.title2.bold())
+                    Text(message)
+                        .font(.subheadline)
+                        .foregroundStyle(.secondary)
+                        .multilineTextAlignment(.center)
+                    Button("Close") { dismiss() }
+                        .keyboardShortcut(.defaultAction)
+                }
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+                .padding()
+            }
+        }
+        .frame(minWidth: 620, minHeight: 560)
+        .padding()
+        .task { viewModel.load() }
+    }
+
+    @ViewBuilder
+    private var form: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 16) {
+                Text("Export \"\(viewModel.project.name)\" as Template")
+                    .font(.title2.bold())
+                metadataGroup
+                Divider()
+                requiredFilesGroup
+                Divider()
+                instructionsGroup
+                Divider()
+                skillsGroup
+                Divider()
+                cronGroup
+                Divider()
+                memoryGroup
+            }
+            .padding(.bottom)
+        }
+        HStack {
+            Button("Cancel") { dismiss() }
+                .keyboardShortcut(.cancelAction)
+            Spacer()
+            Button("Export…") { runExport() }
+                .keyboardShortcut(.defaultAction)
+                .buttonStyle(.borderedProminent)
+                .disabled(!canExport)
+        }
+        .padding(.top, 8)
+    }
+
+    private var metadataGroup: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Text("Metadata").font(.headline)
+            LabeledContent("Template ID") {
+                TextField("owner/name", text: $viewModel.templateId)
+                    .textFieldStyle(.roundedBorder)
+            }
+            LabeledContent("Display Name") {
+                TextField("", text: $viewModel.templateName)
+                    .textFieldStyle(.roundedBorder)
+            }
+            LabeledContent("Version") {
+                TextField("1.0.0", text: $viewModel.templateVersion)
+                    .textFieldStyle(.roundedBorder)
+            }
+            LabeledContent("Description") {
+                TextField("One-line pitch", text: $viewModel.templateDescription, axis: .vertical)
+                    .lineLimit(2...4)
+                    .textFieldStyle(.roundedBorder)
+            }
+            LabeledContent("Author") {
+                TextField("Your name", text: $viewModel.authorName)
+                    .textFieldStyle(.roundedBorder)
+            }
+            LabeledContent("Author URL") {
+                TextField("https://…", text: $viewModel.authorURL)
+                    .textFieldStyle(.roundedBorder)
+            }
+            LabeledContent("Category") {
+                TextField("e.g. productivity", text: $viewModel.category)
+                    .textFieldStyle(.roundedBorder)
+            }
+            LabeledContent("Tags (comma-separated)") {
+                TextField("focus, timer", text: $viewModel.tags)
+                    .textFieldStyle(.roundedBorder)
+            }
+        }
+    }
+
+    private var requiredFilesGroup: some View {
+        let plan = viewModel.previewPlan()
+        return VStack(alignment: .leading, spacing: 6) {
+            Text("Required Files").font(.headline)
+            check(label: "dashboard.json (\(plan.projectDir)/.scarf/dashboard.json)", ok: plan.dashboardPresent)
+            check(label: "README.md (\(plan.projectDir)/README.md)", ok: plan.readmePresent)
+            check(label: "AGENTS.md (\(plan.projectDir)/AGENTS.md)", ok: plan.agentsMdPresent)
+        }
+    }
+
+    private var instructionsGroup: some View {
+        let plan = viewModel.previewPlan()
+        return VStack(alignment: .leading, spacing: 4) {
+            Text("Agent-specific instructions (optional)").font(.headline)
+            if plan.instructionFiles.isEmpty {
+                Text("No per-agent instruction files found in the project root.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            } else {
+                ForEach(plan.instructionFiles, id: \.self) { file in
+                    Label(file, systemImage: "doc.plaintext")
+                        .font(.callout)
+                }
+            }
+        }
+    }
+
+    private var skillsGroup: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            Text("Include Skills").font(.headline)
+            if viewModel.availableSkills.isEmpty {
+                Text("No skills found.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            } else {
+                ForEach(viewModel.availableSkills) { skill in
+                    Toggle(isOn: Binding(
+                        get: { viewModel.includeSkillIds.contains(skill.id) },
+                        set: { on in
+                            if on { viewModel.includeSkillIds.insert(skill.id) }
+                            else { viewModel.includeSkillIds.remove(skill.id) }
+                        }
+                    )) {
+                        Text(skill.id).font(.callout.monospaced())
+                    }
+                }
+            }
+        }
+    }
+
+    private var cronGroup: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            Text("Include Cron Jobs").font(.headline)
+            if viewModel.availableCronJobs.isEmpty {
+                Text("No cron jobs found.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            } else {
+                ForEach(viewModel.availableCronJobs) { job in
+                    Toggle(isOn: Binding(
+                        get: { viewModel.includeCronJobIds.contains(job.id) },
+                        set: { on in
+                            if on { viewModel.includeCronJobIds.insert(job.id) }
+                            else { viewModel.includeCronJobIds.remove(job.id) }
+                        }
+                    )) {
+                        VStack(alignment: .leading, spacing: 0) {
+                            Text(job.name).font(.callout)
+                            Text(job.schedule.display ?? job.schedule.expression ?? job.schedule.kind)
+                                .font(.caption)
+                                .foregroundStyle(.secondary)
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    private var memoryGroup: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            Text("Memory Appendix (optional)").font(.headline)
+            Text("Markdown that will be appended to the installer's MEMORY.md, wrapped in template-specific markers so it can be removed cleanly later.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+            TextEditor(text: $viewModel.memoryAppendix)
+                .font(.callout.monospaced())
+                .frame(minHeight: 80, maxHeight: 160)
+                .overlay(
+                    RoundedRectangle(cornerRadius: 4)
+                        .stroke(.secondary.opacity(0.4))
+                )
+        }
+    }
+
+    private func check(label: String, ok: Bool) -> some View {
+        HStack(spacing: 6) {
+            Image(systemName: ok ? "checkmark.circle.fill" : "xmark.circle.fill")
+                .foregroundStyle(ok ? .green : .red)
+            Text(label)
+                .font(.caption)
+                .foregroundStyle(ok ? .primary : .secondary)
+        }
+    }
+
+    private var canExport: Bool {
+        let plan = viewModel.previewPlan()
+        return plan.dashboardPresent
+            && plan.readmePresent
+            && plan.agentsMdPresent
+            && !viewModel.templateId.trimmingCharacters(in: .whitespaces).isEmpty
+            && !viewModel.templateName.trimmingCharacters(in: .whitespaces).isEmpty
+            && !viewModel.templateVersion.trimmingCharacters(in: .whitespaces).isEmpty
+            && !viewModel.templateDescription.trimmingCharacters(in: .whitespaces).isEmpty
+    }
+
+    private func runExport() {
+        let panel = NSSavePanel()
+        panel.allowedContentTypes = [.zip]
+        panel.nameFieldStringValue = ProjectTemplateExporter.slugify(viewModel.templateName) + ".scarftemplate"
+        if panel.runModal() == .OK, let url = panel.url {
+            viewModel.export(to: url.path)
+        }
+    }
+}

scarf/scarf/Features/Templates/Views/TemplateInstallSheet.swift

@@ -0,0 +1,431 @@
+import SwiftUI
+import AppKit
+
+/// Preview-and-confirm sheet for installing a `.scarftemplate`. Honest
+/// accounting: shows every file that will be written, every cron job that
+/// will be registered, and the memory diff — nothing gets written until the
+/// user clicks Install.
+struct TemplateInstallSheet: View {
+    @Environment(\.dismiss) private var dismiss
+    @State var viewModel: TemplateInstallerViewModel
+    let onCompleted: (ProjectEntry) -> Void
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 0) {
+            switch viewModel.stage {
+            case .idle:
+                idleView
+            case .fetching(let src):
+                progress("Downloading from \(src)…")
+            case .inspecting:
+                progress("Inspecting template…")
+            case .awaitingParentDirectory:
+                pickParentView
+            case .awaitingConfig:
+                configureView
+            case .planned:
+                if let plan = viewModel.plan {
+                    plannedView(plan: plan)
+                } else {
+                    progress("Preparing…")
+                }
+            case .installing:
+                progress("Installing…")
+            case .succeeded(let entry):
+                successView(entry: entry)
+            case .failed(let message):
+                failureView(message: message)
+            }
+        }
+        .frame(minWidth: 640, minHeight: 520)
+        .padding()
+    }
+
+    // MARK: - Stages
+
+    private var idleView: some View {
+        VStack(spacing: 16) {
+            Text("No template loaded.")
+                .font(.headline)
+            Button("Close") { dismiss() }
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+
+    private func progress(_ label: LocalizedStringKey) -> some View {
+        VStack(spacing: 16) {
+            ProgressView()
+            Text(label)
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+
+    private var pickParentView: some View {
+        VStack(alignment: .leading, spacing: 12) {
+            if let manifest = viewModel.inspection?.manifest {
+                manifestHeader(manifest)
+                Divider()
+            }
+            Text("Where should this project live?")
+                .font(.headline)
+            Text("Scarf will create a new folder inside the directory you pick, named after the template id.")
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+            Spacer()
+            HStack {
+                Button("Cancel") {
+                    viewModel.cancel()
+                    dismiss()
+                }
+                .keyboardShortcut(.cancelAction)
+                Spacer()
+                Button("Choose Folder…") { chooseParentDirectory() }
+                    .keyboardShortcut(.defaultAction)
+            }
+        }
+    }
+
+    /// Configure step for schemaful templates. Inlines
+    /// `TemplateConfigSheet` into the install flow rather than pushing
+    /// a second sheet on top — keeps the user in one window. The
+    /// nested VM is created freshly each time `.awaitingConfig` is
+    /// entered so a Cancel + retry doesn't carry stale form state.
+    @ViewBuilder
+    private var configureView: some View {
+        if let plan = viewModel.plan,
+           let schema = plan.configSchema,
+           let manifest = viewModel.inspection?.manifest {
+            TemplateConfigSheet(
+                viewModel: TemplateConfigViewModel(
+                    schema: schema,
+                    templateId: manifest.id,
+                    templateSlug: manifest.slug,
+                    initialValues: plan.configValues,
+                    mode: .install
+                ),
+                title: "Configure \(manifest.name)",
+                commitLabel: "Continue",
+                project: ProjectEntry(name: plan.projectRegistryName, path: plan.projectDir),
+                onCommit: { values in
+                    viewModel.submitConfig(values: values)
+                },
+                onCancel: {
+                    viewModel.cancelConfig()
+                }
+            )
+        } else {
+            progress("Preparing…")
+        }
+    }
+
+    private func plannedView(plan: TemplateInstallPlan) -> some View {
+        VStack(alignment: .leading, spacing: 0) {
+            manifestHeader(plan.manifest)
+                .padding(.bottom, 8)
+            Divider()
+            ScrollView {
+                // `.frame(maxWidth: .infinity, alignment: .leading)` —
+                // without it, a subsection containing an unbreakable
+                // token (raw URL in a cron prompt or README block, a
+                // long file path in the project-files list, a schema
+                // description with a bare URL, etc.) sets the VStack's
+                // ideal width to that token's length; the sheet grows
+                // past its `.frame(minWidth: 620)` and gets clipped by
+                // the window. Same fix as `TemplateConfigSheet`'s
+                // inner VStack — propagate the ScrollView's width down
+                // so inner Text wraps instead of expanding outward.
+                VStack(alignment: .leading, spacing: 16) {
+                    projectFilesSection(plan: plan)
+                    if plan.skillsNamespaceDir != nil {
+                        skillsSection(plan: plan)
+                    }
+                    if !plan.cronJobs.isEmpty {
+                        cronSection(plan: plan)
+                    }
+                    if plan.memoryAppendix != nil {
+                        memorySection(plan: plan)
+                    }
+                    if let schema = plan.configSchema, !schema.isEmpty {
+                        configurationSection(plan: plan, schema: schema)
+                    }
+                    readmeSection
+                }
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .padding(.vertical)
+            }
+            Divider()
+            HStack {
+                Button("Cancel") {
+                    viewModel.cancel()
+                    dismiss()
+                }
+                .keyboardShortcut(.cancelAction)
+                Spacer()
+                Text("\(plan.totalWriteCount) changes")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                Button("Install") { viewModel.confirmInstall() }
+                    .keyboardShortcut(.defaultAction)
+                    .buttonStyle(.borderedProminent)
+            }
+            .padding(.top, 8)
+        }
+    }
+
+    private func manifestHeader(_ manifest: ProjectTemplateManifest) -> some View {
+        VStack(alignment: .leading, spacing: 4) {
+            HStack(alignment: .firstTextBaseline) {
+                Text(manifest.name).font(.title2.bold())
+                Text("v\(manifest.version)")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                Spacer()
+                Text(manifest.id)
+                    .font(.caption.monospaced())
+                    .foregroundStyle(.secondary)
+            }
+            // Inline-only markdown — descriptions are a sentence or two;
+            // bold/italic/code/links are all that reasonable template
+            // authors use there.
+            TemplateMarkdown.inlineText(manifest.description)
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+            if let author = manifest.author {
+                HStack(spacing: 4) {
+                    Image(systemName: "person.crop.circle")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                    Text(author.name)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                    if let url = author.url, let parsed = URL(string: url) {
+                        Link(parsed.host ?? url, destination: parsed)
+                            .font(.caption)
+                    }
+                }
+            }
+        }
+    }
+
+    private func projectFilesSection(plan: TemplateInstallPlan) -> some View {
+        section(title: "New project directory", subtitle: plan.projectDir) {
+            VStack(alignment: .leading, spacing: 2) {
+                ForEach(plan.projectFiles, id: \.destinationPath) { copy in
+                    fileRow(label: copy.destinationPath, systemImage: "doc.text")
+                }
+            }
+        }
+    }
+
+    private func skillsSection(plan: TemplateInstallPlan) -> some View {
+        section(
+            title: "Skills (namespaced, safe to remove later)",
+            subtitle: plan.skillsNamespaceDir
+        ) {
+            VStack(alignment: .leading, spacing: 2) {
+                ForEach(plan.skillsFiles, id: \.destinationPath) { copy in
+                    fileRow(label: copy.destinationPath, systemImage: "puzzlepiece")
+                }
+            }
+        }
+    }
+
+    private func cronSection(plan: TemplateInstallPlan) -> some View {
+        section(title: "Cron jobs (created disabled — you can enable each one manually)", subtitle: nil) {
+            VStack(alignment: .leading, spacing: 10) {
+                ForEach(plan.cronJobs, id: \.name) { job in
+                    VStack(alignment: .leading, spacing: 4) {
+                        HStack(alignment: .firstTextBaseline, spacing: 8) {
+                            Image(systemName: "clock.arrow.circlepath")
+                                .foregroundStyle(.secondary)
+                            VStack(alignment: .leading, spacing: 1) {
+                                Text(job.name).font(.callout.monospaced())
+                                Text("schedule: \(job.schedule)")
+                                    .font(.caption)
+                                    .foregroundStyle(.secondary)
+                            }
+                        }
+                        // Prompt preview — disclosed in an expandable
+                        // group so the preview stays compact when the
+                        // user doesn't care to read it. Markdown-rendered
+                        // so prompts that include `code`, **bold**, or
+                        // enumerated steps look right. Tokens like
+                        // {{PROJECT_DIR}} are still visible here — they
+                        // get substituted when the installer calls
+                        // `hermes cron create`.
+                        if let prompt = job.prompt, !prompt.isEmpty {
+                            DisclosureGroup("Prompt") {
+                                ScrollView {
+                                    TemplateMarkdown.render(prompt)
+                                        .frame(maxWidth: .infinity, alignment: .leading)
+                                }
+                                .frame(maxHeight: 140)
+                                .padding(8)
+                                .background(.quaternary.opacity(0.4))
+                                .clipShape(RoundedRectangle(cornerRadius: 6))
+                            }
+                            .font(.caption)
+                            .padding(.leading, 26)
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    private func memorySection(plan: TemplateInstallPlan) -> some View {
+        section(title: "Memory appendix", subtitle: plan.memoryPath) {
+            ScrollView {
+                Text(plan.memoryAppendix ?? "")
+                    .font(.caption.monospaced())
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .padding(8)
+                    .background(.quaternary.opacity(0.5))
+                    .clipShape(RoundedRectangle(cornerRadius: 6))
+            }
+            .frame(maxHeight: 160)
+        }
+    }
+
+    /// Configuration values the user entered in the configure step.
+    /// Secrets display masked so the preview never echoes a freshly
+    /// typed API key back on screen.
+    private func configurationSection(plan: TemplateInstallPlan, schema: TemplateConfigSchema) -> some View {
+        section(title: "Configuration", subtitle: "written to \(plan.projectDir)/.scarf/config.json") {
+            VStack(alignment: .leading, spacing: 4) {
+                ForEach(schema.fields) { field in
+                    HStack(alignment: .firstTextBaseline, spacing: 8) {
+                        Text(field.key)
+                            .font(.caption.monospaced())
+                            .foregroundStyle(.secondary)
+                            .frame(minWidth: 120, alignment: .leading)
+                        Text(displayValue(for: field, in: plan.configValues))
+                            .font(.caption)
+                            .lineLimit(1)
+                            .truncationMode(.tail)
+                    }
+                }
+            }
+        }
+    }
+
+    /// One-line display form for a value in the preview. Secrets are
+    /// always masked; lists show a count + first entry; strings are
+    /// truncated by `.lineLimit(1)` at the view level.
+    private func displayValue(
+        for field: TemplateConfigField,
+        in values: [String: TemplateConfigValue]
+    ) -> String {
+        switch field.type {
+        case .secret:
+            return values[field.key] == nil ? "(not set)" : "••••••• (Keychain)"
+        case .list:
+            if case .list(let items) = values[field.key] {
+                if items.isEmpty { return "(none)" }
+                if items.count == 1 { return items[0] }
+                return "\(items[0]) + \(items.count - 1) more"
+            }
+            return "(none)"
+        default:
+            return values[field.key]?.displayString ?? "(not set)"
+        }
+    }
+
+    private var readmeSection: some View {
+        Group {
+            // The body is preloaded in the VM off MainActor when inspection
+            // completes — no sync file I/O during View body evaluation.
+            if let readme = viewModel.readmeBody {
+                section(title: "README", subtitle: nil) {
+                    ScrollView {
+                        TemplateMarkdown.render(readme)
+                            .frame(maxWidth: .infinity, alignment: .leading)
+                    }
+                    .frame(maxHeight: 260)
+                }
+            }
+        }
+    }
+
+    @ViewBuilder
+    private func section<Content: View>(title: String, subtitle: String?, @ViewBuilder content: () -> Content) -> some View {
+        VStack(alignment: .leading, spacing: 4) {
+            Text(title).font(.headline)
+            if let subtitle {
+                Text(subtitle)
+                    .font(.caption.monospaced())
+                    .foregroundStyle(.secondary)
+            }
+            content()
+                .padding(.top, 2)
+        }
+    }
+
+    private func fileRow(label: String, systemImage: String) -> some View {
+        HStack(spacing: 6) {
+            Image(systemName: systemImage)
+                .foregroundStyle(.secondary)
+                .font(.caption)
+            Text(label)
+                .font(.caption.monospaced())
+                .lineLimit(1)
+                .truncationMode(.head)
+        }
+    }
+
+    private func successView(entry: ProjectEntry) -> some View {
+        VStack(spacing: 16) {
+            Image(systemName: "checkmark.circle.fill")
+                .font(.system(size: 48))
+                .foregroundStyle(.green)
+            Text("Installed \(entry.name)")
+                .font(.title2.bold())
+            Text(entry.path)
+                .font(.caption.monospaced())
+                .foregroundStyle(.secondary)
+            Button("Open Project") {
+                onCompleted(entry)
+                dismiss()
+            }
+            .keyboardShortcut(.defaultAction)
+            .buttonStyle(.borderedProminent)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+
+    private func failureView(message: String) -> some View {
+        VStack(spacing: 16) {
+            Image(systemName: "exclamationmark.triangle.fill")
+                .font(.system(size: 48))
+                .foregroundStyle(.orange)
+            Text("Install Failed").font(.title2.bold())
+            Text(message)
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+                .multilineTextAlignment(.center)
+            Button("Close") {
+                viewModel.cancel()
+                dismiss()
+            }
+            .keyboardShortcut(.defaultAction)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .padding()
+    }
+
+    // MARK: - Actions
+
+    private func chooseParentDirectory() {
+        let panel = NSOpenPanel()
+        panel.canChooseDirectories = true
+        panel.canChooseFiles = false
+        panel.allowsMultipleSelection = false
+        panel.prompt = String(localized: "Choose Parent Folder")
+        if panel.runModal() == .OK, let url = panel.url {
+            viewModel.pickParentDirectory(url.path)
+        }
+    }
+
+}

scarf/scarf/Features/Templates/Views/TemplateMarkdown.swift

@@ -0,0 +1,192 @@
+import SwiftUI
+import Foundation
+
+/// Minimal markdown renderer used by the template install/config UIs.
+///
+/// SwiftUI `Text` has built-in inline-markdown support via
+/// `AttributedString(markdown:)` — bold, italic, inline code, links.
+/// That's enough for field descriptions + template taglines. For
+/// longer content (README preview, full doc blocks), this helper adds
+/// block-level handling: lines starting with `#`/`##`/`###` render
+/// as bigger bold text; lines starting with `-`/`*`/`1.` render as
+/// list items with a hanging indent; fenced ``` ``` blocks render as
+/// monospaced; blank lines become paragraph breaks.
+///
+/// Scope is intentionally small. This isn't a full CommonMark
+/// renderer — it's "enough markdown to make template READMEs look
+/// right in the install sheet without pulling in a dependency." If
+/// the set of templates needs more over time, evolve this file or
+/// graduate to a proper library.
+enum TemplateMarkdown {
+
+    /// Render a markdown source string as a SwiftUI view. Preserves
+    /// reading order and approximate visual hierarchy. Safe with
+    /// untrusted input — we never execute HTML or scripts.
+    @ViewBuilder
+    static func render(_ source: String) -> some View {
+        VStack(alignment: .leading, spacing: 6) {
+            let blocks = parse(source)
+            ForEach(blocks.indices, id: \.self) { i in
+                block(blocks[i])
+            }
+        }
+    }
+
+    /// Inline-only markdown (bold/italic/code/links) as a single
+    /// `Text`. Use for short strings where block structure doesn't
+    /// apply — field labels, one-line descriptions.
+    static func inlineText(_ source: String) -> Text {
+        if let attr = try? AttributedString(
+            markdown: source,
+            options: .init(interpretedSyntax: .inlineOnlyPreservingWhitespace)
+        ) {
+            return Text(attr)
+        }
+        return Text(source)
+    }
+
+    // MARK: - Block model
+
+    fileprivate enum Block {
+        case paragraph(AttributedString)
+        case heading(level: Int, text: AttributedString)
+        case bullet(AttributedString)
+        case numbered(index: Int, text: AttributedString)
+        case code(String)
+    }
+
+    // MARK: - Parser
+
+    fileprivate static func parse(_ source: String) -> [Block] {
+        var blocks: [Block] = []
+        var lines = source.components(separatedBy: "\n")
+        var i = 0
+        while i < lines.count {
+            let line = lines[i]
+            let trimmed = line.trimmingCharacters(in: .whitespaces)
+
+            // Fenced code block.
+            if trimmed.hasPrefix("```") {
+                var body: [String] = []
+                i += 1
+                while i < lines.count {
+                    let inner = lines[i]
+                    if inner.trimmingCharacters(in: .whitespaces).hasPrefix("```") {
+                        i += 1
+                        break
+                    }
+                    body.append(inner)
+                    i += 1
+                }
+                blocks.append(.code(body.joined(separator: "\n")))
+                continue
+            }
+
+            // Heading.
+            if let headingMatch = trimmed.firstMatch(of: /^(#{1,6})\s+(.*)$/) {
+                let level = (headingMatch.1).count
+                let text = String(headingMatch.2)
+                blocks.append(.heading(level: level, text: renderInline(text)))
+                i += 1
+                continue
+            }
+
+            // Bullet list.
+            if let bulletMatch = line.firstMatch(of: /^\s*[-*]\s+(.*)$/) {
+                let text = String(bulletMatch.1)
+                blocks.append(.bullet(renderInline(text)))
+                i += 1
+                continue
+            }
+
+            // Numbered list.
+            if let numMatch = line.firstMatch(of: /^\s*(\d+)\.\s+(.*)$/) {
+                let index = Int(String(numMatch.1)) ?? 1
+                let text = String(numMatch.2)
+                blocks.append(.numbered(index: index, text: renderInline(text)))
+                i += 1
+                continue
+            }
+
+            // Blank line — skip.
+            if trimmed.isEmpty {
+                i += 1
+                continue
+            }
+
+            // Paragraph — collect contiguous non-blank lines that
+            // aren't headings/lists/fences into one paragraph block.
+            var paragraphLines: [String] = [line]
+            i += 1
+            while i < lines.count {
+                let next = lines[i]
+                let nextTrim = next.trimmingCharacters(in: .whitespaces)
+                if nextTrim.isEmpty { break }
+                if nextTrim.hasPrefix("```") { break }
+                if nextTrim.firstMatch(of: /^#{1,6}\s/) != nil { break }
+                if next.firstMatch(of: /^\s*[-*]\s+/) != nil { break }
+                if next.firstMatch(of: /^\s*\d+\.\s+/) != nil { break }
+                paragraphLines.append(next)
+                i += 1
+            }
+            let joined = paragraphLines.joined(separator: " ")
+            blocks.append(.paragraph(renderInline(joined)))
+        }
+        return blocks
+    }
+
+    /// Parse inline markdown (bold, italic, inline code, links) into
+    /// an AttributedString. Falls back to plain text on parse failure.
+    fileprivate static func renderInline(_ source: String) -> AttributedString {
+        if let attr = try? AttributedString(
+            markdown: source,
+            options: .init(interpretedSyntax: .inlineOnlyPreservingWhitespace)
+        ) {
+            return attr
+        }
+        return AttributedString(source)
+    }
+
+    // MARK: - Rendering
+
+    @ViewBuilder
+    fileprivate static func block(_ b: Block) -> some View {
+        switch b {
+        case .paragraph(let text):
+            Text(text)
+                .font(.callout)
+                .fixedSize(horizontal: false, vertical: true)
+        case .heading(let level, let text):
+            headingText(text: text, level: level)
+        case .bullet(let text):
+            HStack(alignment: .firstTextBaseline, spacing: 6) {
+                Text("•").font(.callout)
+                Text(text).font(.callout)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+        case .numbered(let index, let text):
+            HStack(alignment: .firstTextBaseline, spacing: 6) {
+                Text("\(index).").font(.callout.monospacedDigit())
+                Text(text).font(.callout)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+        case .code(let src):
+            Text(src)
+                .font(.caption.monospaced())
+                .padding(8)
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .background(.quaternary.opacity(0.5))
+                .clipShape(RoundedRectangle(cornerRadius: 6))
+        }
+    }
+
+    @ViewBuilder
+    fileprivate static func headingText(text: AttributedString, level: Int) -> some View {
+        switch level {
+        case 1: Text(text).font(.title2.bold()).padding(.top, 8)
+        case 2: Text(text).font(.title3.bold()).padding(.top, 6)
+        case 3: Text(text).font(.headline).padding(.top, 4)
+        default: Text(text).font(.subheadline.bold()).padding(.top, 2)
+        }
+    }
+}

scarf/scarf/Features/Templates/Views/TemplateUninstallSheet.swift

@@ -0,0 +1,369 @@
+import SwiftUI
+
+/// Preview-and-confirm sheet for uninstalling a template-installed
+/// project. Symmetric with the install sheet: lists every file, cron
+/// job, and memory block that will be removed BEFORE anything happens.
+struct TemplateUninstallSheet: View {
+    @Environment(\.dismiss) private var dismiss
+    @State var viewModel: TemplateUninstallerViewModel
+    /// Called on success with the project that was removed. Parent uses
+    /// this to refresh its projects list and clear any selection.
+    let onCompleted: (ProjectEntry) -> Void
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 0) {
+            switch viewModel.stage {
+            case .idle:
+                idleView
+            case .loading:
+                progress("Reading template.lock.json…")
+            case .planned:
+                if let plan = viewModel.plan {
+                    plannedView(plan: plan)
+                } else {
+                    progress("Preparing…")
+                }
+            case .uninstalling:
+                progress("Removing…")
+            case .succeeded(let removed):
+                successView(removed: removed)
+            case .failed(let message):
+                failureView(message: message)
+            }
+        }
+        .frame(minWidth: 620, minHeight: 480)
+        .padding()
+    }
+
+    // MARK: - Stages
+
+    private var idleView: some View {
+        VStack(spacing: 16) {
+            Text("No template loaded.")
+                .font(.headline)
+            Button("Close") { dismiss() }
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+
+    private func progress(_ label: LocalizedStringKey) -> some View {
+        VStack(spacing: 16) {
+            ProgressView()
+            Text(label)
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+
+    private func plannedView(plan: TemplateUninstallPlan) -> some View {
+        VStack(alignment: .leading, spacing: 0) {
+            header(plan: plan)
+                .padding(.bottom, 8)
+            Divider()
+            ScrollView {
+                VStack(alignment: .leading, spacing: 16) {
+                    projectFilesSection(plan: plan)
+                    if plan.skillsNamespaceDir != nil {
+                        skillsSection(plan: plan)
+                    }
+                    cronSection(plan: plan)
+                    memorySection(plan: plan)
+                    registrySection(plan: plan)
+                }
+                .padding(.vertical)
+            }
+            Divider()
+            HStack {
+                Button("Cancel") {
+                    viewModel.cancel()
+                    dismiss()
+                }
+                .keyboardShortcut(.cancelAction)
+                Spacer()
+                Text("\(plan.totalRemoveCount) changes")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                Button("Remove") { viewModel.confirmUninstall() }
+                    .keyboardShortcut(.defaultAction)
+                    .buttonStyle(.borderedProminent)
+                    .tint(.red)
+            }
+            .padding(.top, 8)
+        }
+    }
+
+    private func header(plan: TemplateUninstallPlan) -> some View {
+        VStack(alignment: .leading, spacing: 4) {
+            HStack(alignment: .firstTextBaseline) {
+                Text("Remove “\(plan.lock.templateName)”").font(.title2.bold())
+                Text("v\(plan.lock.templateVersion)")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                Spacer()
+                Text(plan.lock.templateId)
+                    .font(.caption.monospaced())
+                    .foregroundStyle(.secondary)
+            }
+            Text("Installed \(plan.lock.installedAt)")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    private func projectFilesSection(plan: TemplateUninstallPlan) -> some View {
+        section(title: "Project directory", subtitle: plan.project.path) {
+            VStack(alignment: .leading, spacing: 4) {
+                ForEach(plan.projectFilesToRemove, id: \.self) { path in
+                    fileRow(
+                        label: path,
+                        systemImage: "minus.circle",
+                        color: .red,
+                        tag: "remove"
+                    )
+                }
+                ForEach(plan.projectFilesAlreadyGone, id: \.self) { path in
+                    fileRow(
+                        label: path,
+                        systemImage: "questionmark.circle",
+                        color: .secondary,
+                        tag: "already gone"
+                    )
+                }
+                ForEach(plan.extraProjectEntries, id: \.self) { path in
+                    fileRow(
+                        label: path,
+                        systemImage: "lock.shield",
+                        color: .green,
+                        tag: "keep (not installed by template)"
+                    )
+                }
+                if plan.projectDirBecomesEmpty {
+                    Text("Project directory will also be removed (nothing user-owned left inside).")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .padding(.top, 4)
+                } else if !plan.extraProjectEntries.isEmpty {
+                    Text("Project directory stays — it still holds files you created after install.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .padding(.top, 4)
+                }
+            }
+        }
+    }
+
+    private func skillsSection(plan: TemplateUninstallPlan) -> some View {
+        section(
+            title: "Skills",
+            subtitle: plan.skillsNamespaceDir
+        ) {
+            HStack(spacing: 6) {
+                Image(systemName: "minus.circle")
+                    .foregroundStyle(.red)
+                    .font(.caption)
+                Text("Remove the entire namespace dir recursively")
+                    .font(.caption)
+            }
+        }
+    }
+
+    private func cronSection(plan: TemplateUninstallPlan) -> some View {
+        section(
+            title: "Cron jobs",
+            subtitle: plan.cronJobsToRemove.isEmpty && plan.cronJobsAlreadyGone.isEmpty
+                ? "none"
+                : nil
+        ) {
+            VStack(alignment: .leading, spacing: 4) {
+                ForEach(plan.cronJobsToRemove, id: \.id) { job in
+                    HStack(spacing: 6) {
+                        Image(systemName: "minus.circle")
+                            .foregroundStyle(.red)
+                            .font(.caption)
+                        VStack(alignment: .leading, spacing: 1) {
+                            Text(job.name).font(.callout.monospaced())
+                            Text(job.id)
+                                .font(.caption)
+                                .foregroundStyle(.secondary)
+                        }
+                    }
+                }
+                ForEach(plan.cronJobsAlreadyGone, id: \.self) { name in
+                    HStack(spacing: 6) {
+                        Image(systemName: "questionmark.circle")
+                            .foregroundStyle(.secondary)
+                            .font(.caption)
+                        Text("\(name) — already gone")
+                            .font(.caption)
+                            .foregroundStyle(.secondary)
+                    }
+                }
+            }
+        }
+    }
+
+    @ViewBuilder
+    private func memorySection(plan: TemplateUninstallPlan) -> some View {
+        if plan.memoryBlockPresent {
+            section(title: "Memory block", subtitle: plan.memoryPath) {
+                HStack(spacing: 6) {
+                    Image(systemName: "minus.circle")
+                        .foregroundStyle(.red)
+                        .font(.caption)
+                    Text("Strip the template's begin/end block, preserve everything else in MEMORY.md")
+                        .font(.caption)
+                }
+            }
+        } else if plan.lock.memoryBlockId != nil {
+            section(title: "Memory block", subtitle: nil) {
+                Text("A memory block was recorded in the lock but is no longer present in MEMORY.md — skipping.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+        }
+    }
+
+    private func registrySection(plan: TemplateUninstallPlan) -> some View {
+        section(title: "Projects registry", subtitle: nil) {
+            HStack(spacing: 6) {
+                Image(systemName: "minus.circle")
+                    .foregroundStyle(.red)
+                    .font(.caption)
+                Text("Remove \"\(plan.project.name)\" from Scarf's project list")
+                    .font(.caption)
+            }
+        }
+    }
+
+    @ViewBuilder
+    private func section<Content: View>(
+        title: LocalizedStringKey,
+        subtitle: String?,
+        @ViewBuilder content: () -> Content
+    ) -> some View {
+        VStack(alignment: .leading, spacing: 4) {
+            Text(title).font(.headline)
+            if let subtitle {
+                Text(subtitle)
+                    .font(.caption.monospaced())
+                    .foregroundStyle(.secondary)
+            }
+            content()
+                .padding(.top, 2)
+        }
+    }
+
+    private func fileRow(label: String, systemImage: String, color: Color, tag: LocalizedStringKey) -> some View {
+        HStack(spacing: 6) {
+            Image(systemName: systemImage)
+                .foregroundStyle(color)
+                .font(.caption)
+            Text(label)
+                .font(.caption.monospaced())
+                .lineLimit(1)
+                .truncationMode(.head)
+            Spacer()
+            Text(tag)
+                .font(.caption2)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    private func successView(removed: ProjectEntry) -> some View {
+        VStack(spacing: 16) {
+            Image(systemName: "checkmark.circle.fill")
+                .font(.system(size: 48))
+                .foregroundStyle(.green)
+            Text("Removed \(removed.name)")
+                .font(.title2.bold())
+
+            // Preserved-files banner. Only renders when the project dir
+            // stayed and at least one file was left behind — that's the
+            // case the user keeps getting surprised by ("I uninstalled
+            // but my project folder is still there?"). Explicit
+            // explanation + file list makes it obvious the files the
+            // user (or the cron job) created are intentionally kept.
+            if let outcome = viewModel.preservedOutcome,
+               outcome.projectDirRemoved == false,
+               outcome.preservedPaths.isEmpty == false {
+                preservedFilesBanner(outcome: outcome)
+            }
+
+            Button("Done") {
+                onCompleted(removed)
+                dismiss()
+            }
+            .keyboardShortcut(.defaultAction)
+            .buttonStyle(.borderedProminent)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .padding()
+    }
+
+    /// Orange informational banner listing the files the uninstaller
+    /// left in the project directory. Caps the visible list at 8 rows
+    /// with a "+N more…" tail so a long log (many runs = many status
+    /// file entries) doesn't blow out the sheet height.
+    private func preservedFilesBanner(
+        outcome: TemplateUninstallerViewModel.PreservedOutcome
+    ) -> some View {
+        let visible = Array(outcome.preservedPaths.prefix(8))
+        let overflow = outcome.preservedPaths.count - visible.count
+        return VStack(alignment: .leading, spacing: 8) {
+            HStack(spacing: 6) {
+                Image(systemName: "folder.badge.questionmark")
+                    .foregroundStyle(.orange)
+                Text("Project folder kept")
+                    .font(.headline)
+            }
+            Text("These files weren't installed by the template (the agent or you created them after install), so Scarf left them in place along with the folder itself.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+                .fixedSize(horizontal: false, vertical: true)
+            VStack(alignment: .leading, spacing: 2) {
+                ForEach(visible, id: \.self) { path in
+                    Text(path)
+                        .font(.caption.monospaced())
+                        .lineLimit(1)
+                        .truncationMode(.head)
+                }
+                if overflow > 0 {
+                    Text("+ \(overflow) more…")
+                        .font(.caption2)
+                        .foregroundStyle(.secondary)
+                }
+            }
+            Text("Delete \(outcome.projectDir) from Finder if you don't need these files anymore.")
+                .font(.caption2)
+                .foregroundStyle(.secondary)
+                .fixedSize(horizontal: false, vertical: true)
+        }
+        .frame(maxWidth: 520, alignment: .leading)
+        .padding(12)
+        .background(
+            RoundedRectangle(cornerRadius: 8)
+                .fill(Color.orange.opacity(0.10))
+        )
+    }
+
+    private func failureView(message: String) -> some View {
+        VStack(spacing: 16) {
+            Image(systemName: "exclamationmark.triangle.fill")
+                .font(.system(size: 48))
+                .foregroundStyle(.orange)
+            Text("Uninstall Failed").font(.title2.bold())
+            Text(message)
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+                .multilineTextAlignment(.center)
+            Button("Close") {
+                viewModel.cancel()
+                dismiss()
+            }
+            .keyboardShortcut(.defaultAction)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .padding()
+    }
+}

scarf/scarf/Features/Tools/Views/ToolsView.swift

@@ -43,7 +43,7 @@ struct ToolsView: View {
             } label: {
                 HStack(spacing: 8) {
                     Image(systemName: KnownPlatforms.icon(for: viewModel.selectedPlatform.name))
-                    Text(viewModel.selectedPlatform.displayName)
+                    Text(verbatim: viewModel.selectedPlatform.displayName)
                         .fontWeight(.medium)
                     statusDot(for: viewModel.connectivity[viewModel.selectedPlatform.name] ?? .notConfigured)
                     Image(systemName: "chevron.down")

scarf/scarf/Info.plist

@@ -38,5 +38,56 @@
 	<integer>86400</integer>
 	<key>SUEnableInstallerLauncherService</key>
 	<false/>
+	<key>CFBundleURLTypes</key>
+	<array>
+		<dict>
+			<key>CFBundleURLName</key>
+			<string>com.scarf.url</string>
+			<key>CFBundleURLSchemes</key>
+			<array>
+				<string>scarf</string>
+			</array>
+		</dict>
+	</array>
+	<key>UTExportedTypeDeclarations</key>
+	<array>
+		<dict>
+			<key>UTTypeIdentifier</key>
+			<string>com.scarf.template</string>
+			<key>UTTypeDescription</key>
+			<string>Scarf Project Template</string>
+			<key>UTTypeConformsTo</key>
+			<array>
+				<string>public.zip-archive</string>
+				<string>public.data</string>
+			</array>
+			<key>UTTypeTagSpecification</key>
+			<dict>
+				<key>public.filename-extension</key>
+				<array>
+					<string>scarftemplate</string>
+				</array>
+				<key>public.mime-type</key>
+				<array>
+					<string>application/vnd.scarf.template+zip</string>
+				</array>
+			</dict>
+		</dict>
+	</array>
+	<key>CFBundleDocumentTypes</key>
+	<array>
+		<dict>
+			<key>CFBundleTypeName</key>
+			<string>Scarf Project Template</string>
+			<key>CFBundleTypeRole</key>
+			<string>Viewer</string>
+			<key>LSHandlerRank</key>
+			<string>Owner</string>
+			<key>LSItemContentTypes</key>
+			<array>
+				<string>com.scarf.template</string>
+			</array>
+		</dict>
+	</array>
 </dict>
 </plist>

scarf/scarf/InfoPlist.xcstrings

@@ -0,0 +1,93 @@
+{
+  "sourceLanguage" : "en",
+  "strings" : {
+    "CFBundleDisplayName" : {
+      "comment" : "Bundle display name",
+      "extractionState" : "extracted_with_value",
+      "localizations" : {
+        "en" : {
+          "stringUnit" : {
+            "state" : "new",
+            "value" : "Scarf"
+          }
+        }
+      }
+    },
+    "CFBundleName" : {
+      "comment" : "Bundle name",
+      "extractionState" : "extracted_with_value",
+      "localizations" : {
+        "en" : {
+          "stringUnit" : {
+            "state" : "new",
+            "value" : "scarf"
+          }
+        }
+      }
+    },
+    "NSHumanReadableCopyright" : {
+      "comment" : "Copyright (human-readable)",
+      "extractionState" : "extracted_with_value",
+      "localizations" : {
+        "en" : {
+          "stringUnit" : {
+            "state" : "new",
+            "value" : ""
+          }
+        }
+      }
+    },
+    "NSMicrophoneUsageDescription" : {
+      "comment" : "Shown by macOS when Scarf first requests microphone access for Hermes voice chat.",
+      "extractionState" : "manual",
+      "localizations" : {
+        "de" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Scarf verwendet das Mikrofon für den Hermes-Sprach-Chat."
+          }
+        },
+        "en" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Scarf uses the microphone for Hermes voice chat."
+          }
+        },
+        "es" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Scarf usa el micrófono para el chat de voz de Hermes."
+          }
+        },
+        "fr" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Scarf utilise le microphone pour le chat vocal de Hermes."
+          }
+        },
+        "ja" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Scarf は Hermes の音声チャットのためにマイクを使用します。"
+          }
+        },
+        "pt-BR" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "O Scarf usa o microfone para o chat de voz do Hermes."
+          }
+        },
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Scarf 使用麦克风进行 Hermes 语音聊天。"
+          }
+        }
+      }
+    },
+    "Scarf Project Template" : {
+
+    }
+  },
+  "version" : "1.0"
+}

scarf/scarf/Navigation/AppCoordinator.swift

@@ -31,6 +31,33 @@ enum SidebarSection: String, CaseIterable, Identifiable {
 
     var id: String { rawValue }
 
+    var displayName: LocalizedStringResource {
+        switch self {
+        case .dashboard: return "Dashboard"
+        case .insights: return "Insights"
+        case .sessions: return "Sessions"
+        case .activity: return "Activity"
+        case .projects: return "Projects"
+        case .chat: return "Chat"
+        case .memory: return "Memory"
+        case .skills: return "Skills"
+        case .platforms: return "Platforms"
+        case .personalities: return "Personalities"
+        case .quickCommands: return "Quick Commands"
+        case .credentialPools: return "Credential Pools"
+        case .plugins: return "Plugins"
+        case .webhooks: return "Webhooks"
+        case .profiles: return "Profiles"
+        case .tools: return "Tools"
+        case .mcpServers: return "MCP Servers"
+        case .gateway: return "Gateway"
+        case .cron: return "Cron"
+        case .health: return "Health"
+        case .logs: return "Logs"
+        case .settings: return "Settings"
+        }
+    }
+
     var icon: String {
         switch self {
         case .dashboard: return "gauge.with.dots.needle.33percent"

scarf/scarf/Navigation/SidebarView.swift

@@ -2,42 +2,64 @@ import SwiftUI
 
 struct SidebarView: View {
     @Environment(AppCoordinator.self) private var coordinator
+    @Environment(\.serverContext) private var serverContext
 
     var body: some View {
         @Bindable var coordinator = coordinator
         List(selection: $coordinator.selectedSection) {
             Section("Monitor") {
                 ForEach([SidebarSection.dashboard, .insights, .sessions, .activity]) { section in
-                    Label(section.rawValue, systemImage: section.icon)
+                    Label {
-                        .tag(section)
+                        Text(section.displayName)
+                    } icon: {
+                        Image(systemName: section.icon)
+                    }
+                    .tag(section)
                 }
             }
             Section("Projects") {
                 ForEach([SidebarSection.projects]) { section in
-                    Label(section.rawValue, systemImage: section.icon)
+                    Label {
-                        .tag(section)
+                        Text(section.displayName)
+                    } icon: {
+                        Image(systemName: section.icon)
+                    }
+                    .tag(section)
                 }
             }
             Section("Interact") {
                 ForEach([SidebarSection.chat, .memory, .skills]) { section in
-                    Label(section.rawValue, systemImage: section.icon)
+                    Label {
-                        .tag(section)
+                        Text(section.displayName)
+                    } icon: {
+                        Image(systemName: section.icon)
+                    }
+                    .tag(section)
                 }
             }
             Section("Configure") {
                 ForEach([SidebarSection.platforms, .personalities, .quickCommands, .credentialPools, .plugins, .webhooks, .profiles]) { section in
-                    Label(section.rawValue, systemImage: section.icon)
+                    Label {
-                        .tag(section)
+                        Text(section.displayName)
+                    } icon: {
+                        Image(systemName: section.icon)
+                    }
+                    .tag(section)
                 }
             }
             Section("Manage") {
                 ForEach([SidebarSection.tools, .mcpServers, .gateway, .cron, .health, .logs, .settings]) { section in
-                    Label(section.rawValue, systemImage: section.icon)
+                    Label {
-                        .tag(section)
+                        Text(section.displayName)
+                    } icon: {
+                        Image(systemName: section.icon)
+                    }
+                    .tag(section)
                 }
             }
         }
         .listStyle(.sidebar)
         .navigationTitle("Scarf")
+        .splitViewAutosaveName("ScarfMainSidebar.\(serverContext.id)")
     }
 }

scarf/scarf/Navigation/SplitViewAutosave.swift

@@ -0,0 +1,57 @@
+import AppKit
+import SwiftUI
+
+/// Makes the enclosing `NSSplitView` remember its divider positions across
+/// app launches. `NavigationSplitView` is backed by `NSSplitViewController`,
+/// whose split view honours `autosaveName` — AppKit writes the divider
+/// offsets to `UserDefaults` on drag and restores them on the next launch.
+///
+/// Usage: attach `.splitViewAutosaveName("…")` to a child of the split view
+/// (the sidebar is a good choice). The modifier installs an invisible helper
+/// that walks up the view hierarchy on first layout, finds the `NSSplitView`,
+/// and assigns its autosave name. Subsequent launches restore the divider
+/// positions before the window appears.
+///
+/// The name is also used to key the entry in `UserDefaults` (AppKit stores
+/// it as `NSSplitView Subview Frames <name>`), so changing the name resets
+/// the remembered width. Pick a stable string and leave it alone.
+struct SplitViewAutosaveFinder: NSViewRepresentable {
+    let autosaveName: String
+
+    func makeNSView(context: Context) -> NSView {
+        let view = NSView()
+        // Defer the hierarchy walk until after SwiftUI has attached this
+        // view to its host window — at makeNSView time the view has no
+        // superview yet, so we can't find the split view above us.
+        DispatchQueue.main.async { [weak view] in
+            guard let view else { return }
+            SplitViewAutosaveFinder.apply(autosaveName, startingFrom: view)
+        }
+        return view
+    }
+
+    func updateNSView(_ nsView: NSView, context: Context) {}
+
+    private static func apply(_ name: String, startingFrom view: NSView) {
+        var current: NSView? = view
+        while let node = current {
+            if let split = node as? NSSplitView {
+                // Only set once — reassigning clobbers AppKit's restore path.
+                if split.autosaveName != NSSplitView.AutosaveName(name) {
+                    split.autosaveName = NSSplitView.AutosaveName(name)
+                }
+                return
+            }
+            current = node.superview
+        }
+    }
+}
+
+extension View {
+    /// Persist the enclosing `NavigationSplitView` / `NSSplitView` divider
+    /// positions to `UserDefaults` under `autosaveName`. Attach to any child
+    /// of the split view (the sidebar works well).
+    func splitViewAutosaveName(_ autosaveName: String) -> some View {
+        background(SplitViewAutosaveFinder(autosaveName: autosaveName))
+    }
+}

scarf/scarf/scarfApp.swift

@@ -57,13 +57,33 @@ struct ScarfApp: App {
                     // covers the case where the user added a server in
                     // another window since this one last opened.
                     .onAppear { liveRegistry.rebuild() }
+                    // scarf://install?url=… deep-link handler. Stages the
+                    // URL on the process-wide router; ProjectsView picks it
+                    // up and presents the install sheet. Activating the
+                    // app here ensures a cold launch from a browser click
+                    // surfaces the sheet without the user having to click
+                    // into Scarf first.
+                    .onOpenURL { url in
+                        TemplateURLRouter.shared.handle(url)
+                        NSApplication.shared.activate()
+                    }
             } else {
+                // MissingServerView is a dead-end "server was removed" pane
+                // with no ProjectsView — so no observer of the router's
+                // pendingInstallURL exists in this window. Routing a
+                // scarf://install URL here would silently drop it. Leave
+                // onOpenURL off this branch; ContextBoundRoot windows in
+                // the same app instance will still handle it.
                 MissingServerView(removedServerID: serverID)
                     .environment(registry)
                     .environment(updater)
             }
         } defaultValue: {
-            ServerContext.local.id
+            // Honour the user's "open on launch" choice from the Manage
+            // Servers popover. Falls back to Local when no entry is flagged
+            // (the default behaviour for fresh installs) or when the
+            // flagged entry was removed while the app was closed.
+            registry.defaultServerID
         }
         .defaultSize(width: 1100, height: 700)
         .commands {

scarf/scarfTests/TemplateConfigTests.swift

@@ -0,0 +1,402 @@
+import Testing
+import Foundation
+@testable import scarf
+
+// MARK: - Schema validation
+
+@Suite struct TemplateConfigSchemaValidationTests {
+
+    @Test func acceptsMinimalValidSchema() throws {
+        let schema = TemplateConfigSchema(
+            fields: [
+                .init(key: "name", type: .string, label: "Name",
+                      description: nil, required: true, placeholder: nil,
+                      defaultValue: nil, options: nil, minLength: nil,
+                      maxLength: nil, pattern: nil, minNumber: nil,
+                      maxNumber: nil, step: nil, itemType: nil,
+                      minItems: nil, maxItems: nil)
+            ],
+            modelRecommendation: nil
+        )
+        try ProjectConfigService.validateSchema(schema)
+    }
+
+    @Test func rejectsDuplicateKeys() {
+        let schema = TemplateConfigSchema(
+            fields: [
+                .init(key: "same", type: .string, label: "A", description: nil,
+                      required: false, placeholder: nil, defaultValue: nil,
+                      options: nil, minLength: nil, maxLength: nil,
+                      pattern: nil, minNumber: nil, maxNumber: nil,
+                      step: nil, itemType: nil, minItems: nil, maxItems: nil),
+                .init(key: "same", type: .bool, label: "B", description: nil,
+                      required: false, placeholder: nil, defaultValue: nil,
+                      options: nil, minLength: nil, maxLength: nil,
+                      pattern: nil, minNumber: nil, maxNumber: nil,
+                      step: nil, itemType: nil, minItems: nil, maxItems: nil)
+            ],
+            modelRecommendation: nil
+        )
+        #expect(throws: TemplateConfigSchemaError.self) {
+            try ProjectConfigService.validateSchema(schema)
+        }
+    }
+
+    @Test func rejectsSecretWithDefault() {
+        let schema = TemplateConfigSchema(
+            fields: [
+                .init(key: "api_key", type: .secret, label: "API Key",
+                      description: nil, required: true, placeholder: nil,
+                      defaultValue: .string("leaked-by-accident"),
+                      options: nil, minLength: nil, maxLength: nil,
+                      pattern: nil, minNumber: nil, maxNumber: nil,
+                      step: nil, itemType: nil, minItems: nil, maxItems: nil)
+            ],
+            modelRecommendation: nil
+        )
+        #expect(throws: TemplateConfigSchemaError.self) {
+            try ProjectConfigService.validateSchema(schema)
+        }
+    }
+
+    @Test func rejectsEnumWithoutOptions() {
+        let schema = TemplateConfigSchema(
+            fields: [
+                .init(key: "choice", type: .enum, label: "Choice",
+                      description: nil, required: true, placeholder: nil,
+                      defaultValue: nil, options: [],
+                      minLength: nil, maxLength: nil, pattern: nil,
+                      minNumber: nil, maxNumber: nil, step: nil,
+                      itemType: nil, minItems: nil, maxItems: nil)
+            ],
+            modelRecommendation: nil
+        )
+        #expect(throws: TemplateConfigSchemaError.self) {
+            try ProjectConfigService.validateSchema(schema)
+        }
+    }
+
+    @Test func rejectsEnumWithDuplicateValues() {
+        let schema = TemplateConfigSchema(
+            fields: [
+                .init(key: "choice", type: .enum, label: "Choice",
+                      description: nil, required: true, placeholder: nil,
+                      defaultValue: nil,
+                      options: [.init(value: "a", label: "A"),
+                                .init(value: "a", label: "Another A")],
+                      minLength: nil, maxLength: nil, pattern: nil,
+                      minNumber: nil, maxNumber: nil, step: nil,
+                      itemType: nil, minItems: nil, maxItems: nil)
+            ],
+            modelRecommendation: nil
+        )
+        #expect(throws: TemplateConfigSchemaError.self) {
+            try ProjectConfigService.validateSchema(schema)
+        }
+    }
+
+    @Test func rejectsUnsupportedListItemType() {
+        let schema = TemplateConfigSchema(
+            fields: [
+                .init(key: "items", type: .list, label: "Items",
+                      description: nil, required: true, placeholder: nil,
+                      defaultValue: nil, options: nil,
+                      minLength: nil, maxLength: nil, pattern: nil,
+                      minNumber: nil, maxNumber: nil, step: nil,
+                      itemType: "number", minItems: 1, maxItems: 10)
+            ],
+            modelRecommendation: nil
+        )
+        #expect(throws: TemplateConfigSchemaError.self) {
+            try ProjectConfigService.validateSchema(schema)
+        }
+    }
+
+    @Test func rejectsEmptyModelPreferred() {
+        let schema = TemplateConfigSchema(
+            fields: [],
+            modelRecommendation: .init(preferred: "  ", rationale: nil, alternatives: nil)
+        )
+        #expect(throws: TemplateConfigSchemaError.self) {
+            try ProjectConfigService.validateSchema(schema)
+        }
+    }
+}
+
+// MARK: - Value validation
+
+@Suite struct TemplateConfigValueValidationTests {
+
+    @Test func requiredFieldRejectsEmptyString() {
+        let schema = TemplateConfigSchema(
+            fields: [
+                .init(key: "name", type: .string, label: "Name",
+                      description: nil, required: true, placeholder: nil,
+                      defaultValue: nil, options: nil, minLength: nil,
+                      maxLength: nil, pattern: nil, minNumber: nil,
+                      maxNumber: nil, step: nil, itemType: nil,
+                      minItems: nil, maxItems: nil)
+            ],
+            modelRecommendation: nil
+        )
+        let errors = ProjectConfigService.validateValues(
+            ["name": .string("")], against: schema
+        )
+        #expect(errors.count == 1)
+        #expect(errors.first?.fieldKey == "name")
+    }
+
+    @Test func patternRejectsBadInput() {
+        let schema = TemplateConfigSchema(
+            fields: [
+                .init(key: "email", type: .string, label: "Email",
+                      description: nil, required: true, placeholder: nil,
+                      defaultValue: nil, options: nil, minLength: nil,
+                      maxLength: nil, pattern: "^[^@]+@[^@]+$",
+                      minNumber: nil, maxNumber: nil, step: nil,
+                      itemType: nil, minItems: nil, maxItems: nil)
+            ],
+            modelRecommendation: nil
+        )
+        let errors = ProjectConfigService.validateValues(
+            ["email": .string("not-an-email")], against: schema
+        )
+        #expect(errors.count == 1)
+    }
+
+    @Test func numberRangeEnforced() {
+        let schema = TemplateConfigSchema(
+            fields: [
+                .init(key: "port", type: .number, label: "Port",
+                      description: nil, required: true, placeholder: nil,
+                      defaultValue: nil, options: nil, minLength: nil,
+                      maxLength: nil, pattern: nil, minNumber: 1024,
+                      maxNumber: 65535, step: nil, itemType: nil,
+                      minItems: nil, maxItems: nil)
+            ],
+            modelRecommendation: nil
+        )
+        let errors = ProjectConfigService.validateValues(
+            ["port": .number(80)], against: schema
+        )
+        #expect(errors.count == 1)
+    }
+
+    @Test func enumRejectsUnknownValue() {
+        let schema = TemplateConfigSchema(
+            fields: [
+                .init(key: "mode", type: .enum, label: "Mode",
+                      description: nil, required: true, placeholder: nil,
+                      defaultValue: nil,
+                      options: [.init(value: "fast", label: "Fast"),
+                                .init(value: "slow", label: "Slow")],
+                      minLength: nil, maxLength: nil, pattern: nil,
+                      minNumber: nil, maxNumber: nil, step: nil,
+                      itemType: nil, minItems: nil, maxItems: nil)
+            ],
+            modelRecommendation: nil
+        )
+        let errors = ProjectConfigService.validateValues(
+            ["mode": .string("medium")], against: schema
+        )
+        #expect(errors.count == 1)
+    }
+
+    @Test func listItemBoundsEnforced() {
+        let schema = TemplateConfigSchema(
+            fields: [
+                .init(key: "urls", type: .list, label: "URLs",
+                      description: nil, required: true, placeholder: nil,
+                      defaultValue: nil, options: nil, minLength: nil,
+                      maxLength: nil, pattern: nil, minNumber: nil,
+                      maxNumber: nil, step: nil, itemType: "string",
+                      minItems: 1, maxItems: 3)
+            ],
+            modelRecommendation: nil
+        )
+        let tooFew = ProjectConfigService.validateValues(
+            ["urls": .list([])], against: schema
+        )
+        let tooMany = ProjectConfigService.validateValues(
+            ["urls": .list(["a", "b", "c", "d"])], against: schema
+        )
+        let justRight = ProjectConfigService.validateValues(
+            ["urls": .list(["a", "b"])], against: schema
+        )
+        #expect(tooFew.count == 1)
+        #expect(tooMany.count == 1)
+        #expect(justRight.isEmpty)
+    }
+
+    @Test func secretFieldAcceptsKeychainRef() {
+        let schema = TemplateConfigSchema(
+            fields: [
+                .init(key: "tok", type: .secret, label: "Token",
+                      description: nil, required: true, placeholder: nil,
+                      defaultValue: nil, options: nil, minLength: nil,
+                      maxLength: nil, pattern: nil, minNumber: nil,
+                      maxNumber: nil, step: nil, itemType: nil,
+                      minItems: nil, maxItems: nil)
+            ],
+            modelRecommendation: nil
+        )
+        let errors = ProjectConfigService.validateValues(
+            ["tok": .keychainRef("keychain://test/tok:abc")],
+            against: schema
+        )
+        #expect(errors.isEmpty)
+    }
+}
+
+// MARK: - Keychain ref helpers
+
+@Suite struct TemplateKeychainRefTests {
+
+    @Test func uriRoundTrips() {
+        let ref = TemplateKeychainRef(
+            service: "com.scarf.template.alice-foo",
+            account: "api_key:deadbeef"
+        )
+        #expect(ref.uri == "keychain://com.scarf.template.alice-foo/api_key:deadbeef")
+        let parsed = TemplateKeychainRef.parse(ref.uri)
+        #expect(parsed == ref)
+    }
+
+    @Test func parseRejectsMalformedUris() {
+        #expect(TemplateKeychainRef.parse("") == nil)
+        #expect(TemplateKeychainRef.parse("keychain://") == nil)
+        #expect(TemplateKeychainRef.parse("keychain:///account-only") == nil)
+        #expect(TemplateKeychainRef.parse("keychain://service-only") == nil)
+        #expect(TemplateKeychainRef.parse("https://example.com/foo") == nil)
+    }
+
+    @Test func hashDiffersByProjectPath() {
+        let a = TemplateKeychainRef.make(templateSlug: "s", fieldKey: "k", projectPath: "/Users/a/p1")
+        let b = TemplateKeychainRef.make(templateSlug: "s", fieldKey: "k", projectPath: "/Users/a/p2")
+        #expect(a.service == b.service) // same template
+        #expect(a.account != b.account) // different project → different hash suffix
+    }
+
+    @Test func hashStableForSamePath() {
+        let a = TemplateKeychainRef.make(templateSlug: "s", fieldKey: "k", projectPath: "/Users/a/p1")
+        let b = TemplateKeychainRef.make(templateSlug: "s", fieldKey: "k", projectPath: "/Users/a/p1")
+        #expect(a == b)
+    }
+}
+
+// MARK: - On-disk config round-trip
+
+@Suite struct ProjectConfigFileTests {
+
+    @Test func roundTripsNonSecretValues() throws {
+        let file = ProjectConfigFile(
+            schemaVersion: 2,
+            templateId: "alice/example",
+            values: [
+                "name": .string("Alice"),
+                "enabled": .bool(true),
+                "count": .number(42),
+                "tags": .list(["a", "b", "c"]),
+            ],
+            updatedAt: "2026-04-25T00:00:00Z"
+        )
+        let encoded = try JSONEncoder().encode(file)
+        let decoded = try JSONDecoder().decode(ProjectConfigFile.self, from: encoded)
+        #expect(decoded.schemaVersion == 2)
+        #expect(decoded.templateId == "alice/example")
+        #expect(decoded.values["name"] == .string("Alice"))
+        #expect(decoded.values["enabled"] == .bool(true))
+        #expect(decoded.values["count"] == .number(42))
+        #expect(decoded.values["tags"] == .list(["a", "b", "c"]))
+    }
+
+    @Test func preservesKeychainRefsOnRoundTrip() throws {
+        let file = ProjectConfigFile(
+            schemaVersion: 2,
+            templateId: "alice/example",
+            values: ["tok": .keychainRef("keychain://com.scarf.template.alice-example/tok:deadbeef")],
+            updatedAt: "2026-04-25T00:00:00Z"
+        )
+        let encoded = try JSONEncoder().encode(file)
+        let decoded = try JSONDecoder().decode(ProjectConfigFile.self, from: encoded)
+        // Keychain refs must NOT demote to plain strings on round-trip
+        // — otherwise a post-install editor would lose the secret
+        // binding when saving unchanged values.
+        #expect(decoded.values["tok"] == .keychainRef("keychain://com.scarf.template.alice-example/tok:deadbeef"))
+    }
+}
+
+// MARK: - ProjectConfigService + Keychain integration
+
+/// Exercises the full secret-storage path through a real macOS Keychain
+/// with a test-only service suffix so nothing leaks into the user's
+/// login Keychain. Every test sets + reads + deletes within a unique
+/// service name so parallel runs don't collide.
+@Suite struct ProjectConfigSecretsTests {
+
+    @Test func storeAndResolveSecret() throws {
+        let suffix = "tests-" + UUID().uuidString
+        let keychain = ProjectConfigKeychain(testServiceSuffix: suffix)
+        let service = ProjectConfigService(keychain: keychain)
+        let project = ProjectEntry(name: "Scratch", path: NSTemporaryDirectory() + UUID().uuidString)
+
+        let stored = try service.storeSecret(
+            templateSlug: "alice-example",
+            fieldKey: "api_key",
+            project: project,
+            secret: Data("hunter2".utf8)
+        )
+
+        // What goes into config.json is a keychainRef, not the bytes.
+        guard case .keychainRef(let uri) = stored else {
+            Issue.record("expected keychainRef, got \(stored)")
+            return
+        }
+        #expect(uri.hasPrefix("keychain://"))
+
+        // Resolve brings the bytes back.
+        let resolved = try service.resolveSecret(ref: stored)
+        #expect(resolved == Data("hunter2".utf8))
+
+        // Clean up so we don't leave a test item in the Keychain.
+        if let ref = TemplateKeychainRef.parse(uri) {
+            try keychain.delete(ref: ref)
+            #expect((try keychain.get(ref: ref)) == nil)
+        }
+    }
+
+    @Test func setOverwritesExistingSecret() throws {
+        let suffix = "tests-" + UUID().uuidString
+        let keychain = ProjectConfigKeychain(testServiceSuffix: suffix)
+        let ref = TemplateKeychainRef(service: "com.scarf.template.overwrite", account: "k:1")
+        try keychain.set(ref: ref, secret: Data("first".utf8))
+        try keychain.set(ref: ref, secret: Data("second".utf8))
+        #expect((try keychain.get(ref: ref)) == Data("second".utf8))
+        try keychain.delete(ref: ref)
+    }
+
+    @Test func deleteOfMissingItemSucceeds() throws {
+        let suffix = "tests-" + UUID().uuidString
+        let keychain = ProjectConfigKeychain(testServiceSuffix: suffix)
+        let ref = TemplateKeychainRef(service: "com.scarf.template.absent", account: "never:set")
+        // Deleting a non-existent item is a no-op — must not throw.
+        try keychain.delete(ref: ref)
+    }
+
+    @Test func deleteMultipleSecretsClearsAll() throws {
+        let suffix = "tests-" + UUID().uuidString
+        let keychain = ProjectConfigKeychain(testServiceSuffix: suffix)
+        let service = ProjectConfigService(keychain: keychain)
+
+        let refs = (0..<3).map { i in
+            TemplateKeychainRef(service: "com.scarf.template.bulk", account: "k:\(i)")
+        }
+        for ref in refs {
+            try keychain.set(ref: ref, secret: Data("v".utf8))
+        }
+        try service.deleteSecrets(refs: refs)
+        for ref in refs {
+            #expect((try keychain.get(ref: ref)) == nil)
+        }
+    }
+}

scripts/catalog.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+#
+# Scarf templates catalog helper — runs the Python validator, renders the
+# static site into .gh-pages-worktree/templates/, and (on `publish`)
+# commits + pushes that subdir on the gh-pages branch.
+#
+# Usage:
+#   ./scripts/catalog.sh check                # validate every template; no output
+#   ./scripts/catalog.sh build                # validate + write templates/catalog.json + .gh-pages-worktree/templates/
+#   ./scripts/catalog.sh preview [DIR]        # render self-contained preview; DIR defaults to /tmp/scarf-catalog-preview
+#   ./scripts/catalog.sh publish              # secret-scan + commit + push gh-pages (templates subdir only)
+#   ./scripts/catalog.sh serve  [PORT]        # serve .gh-pages-worktree/ on localhost:PORT (default 8000)
+#   ./scripts/catalog.sh --help               # this help
+#
+# The secret-scan runs BEFORE publish and inspects the generated
+# .gh-pages-worktree/templates/ tree — same hard-pattern regex as
+# scripts/wiki.sh so template README/AGENTS content that accidentally
+# leaks credentials gets blocked before it reaches the public site.
+#
+# Bootstrap (one-time): requires a .gh-pages-worktree/ clone of the
+# gh-pages branch. The release script (scripts/release.sh) creates it on
+# first use. If it's missing:
+#     git worktree add .gh-pages-worktree gh-pages
+#
+# Recovery: if .gh-pages-worktree/ is deleted, re-run the command above.
+
+set -euo pipefail
+
+# ---------- config ----------
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+GHPAGES_DIR="$REPO_ROOT/.gh-pages-worktree"
+CATALOG_SUBDIR="templates"
+PY="${PYTHON:-python3}"
+BUILDER="$REPO_ROOT/tools/build-catalog.py"
+
+# ---------- helpers (same shape as scripts/wiki.sh so a reader doesn't
+# have to learn two conventions) ----------
+log()  { printf '\033[1;34m==> %s\033[0m\n' "$*"; }
+warn() { printf '\033[1;33m[WARN] %s\033[0m\n' "$*" >&2; }
+die()  { printf '\033[1;31m[ERR] %s\033[0m\n' "$*" >&2; exit 1; }
+
+need_builder() {
+  [[ -f "$BUILDER" ]] || die "missing $BUILDER"
+  command -v "$PY" >/dev/null 2>&1 || die "python3 not found (set \$PYTHON if needed)"
+}
+
+need_ghpages() {
+  # `.git` is a directory in a regular clone but a pointer FILE in a
+  # `git worktree add` worktree — `-e` covers both. The earlier `-d`
+  # check falsely rejected worktrees, so the script's own error
+  # message told users to re-run `git worktree add` on a worktree
+  # that was already there and valid.
+  [[ -e "$GHPAGES_DIR/.git" ]] || die "no gh-pages worktree at $GHPAGES_DIR
+  Run: git worktree add .gh-pages-worktree gh-pages"
+}
+
+# ---------- secret-scan (mirrors scripts/wiki.sh hard-pattern set) ----------
+hard_regex='(sk-[A-Za-z0-9_-]{20,}|ghp_[A-Za-z0-9]{30,}|ghs_[A-Za-z0-9]{30,}|ghu_[A-Za-z0-9]{30,}|gho_[A-Za-z0-9]{30,}|ghr_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{35}|-----BEGIN [A-Z ]*PRIVATE KEY-----|BEGIN OPENSSH PRIVATE KEY)'
+
+scan_hard_ghpages() {
+  # Scan the generated output, NOT the repo source — the validator
+  # already scans bundle contents. This pass catches anything that leaked
+  # through template.json fields or README prose.
+  local hits
+  hits="$(grep -rInE --exclude-dir=.git "$hard_regex" "$GHPAGES_DIR/$CATALOG_SUBDIR" 2>/dev/null || true)"
+  if [[ -n "$hits" ]]; then
+    printf '%s\n' "$hits" >&2
+    die "hard-pattern secret match in rendered site — refusing to publish."
+  fi
+}
+
+# ---------- commands ----------
+cmd_check() {
+  need_builder
+  "$PY" "$BUILDER" --check --repo "$REPO_ROOT"
+}
+
+cmd_build() {
+  need_builder
+  "$PY" "$BUILDER" --build --repo "$REPO_ROOT"
+}
+
+cmd_preview() {
+  need_builder
+  local dir="${1:-/tmp/scarf-catalog-preview}"
+  rm -rf "$dir"
+  mkdir -p "$dir"
+  "$PY" "$BUILDER" --preview "$dir" --repo "$REPO_ROOT"
+  log "Preview rendered to $dir"
+  log "Serve with:  (cd $dir && python3 -m http.server 8000)  then open http://localhost:8000/"
+}
+
+cmd_serve() {
+  need_ghpages
+  local port="${1:-8000}"
+  log "Serving $GHPAGES_DIR on http://localhost:$port/"
+  (cd "$GHPAGES_DIR" && "$PY" -m http.server "$port")
+}
+
+cmd_publish() {
+  need_builder
+  need_ghpages
+  log "Validating"
+  "$PY" "$BUILDER" --check --repo "$REPO_ROOT"
+  log "Building"
+  "$PY" "$BUILDER" --build --repo "$REPO_ROOT"
+
+  log "Secret-scanning rendered site"
+  scan_hard_ghpages
+
+  log "Staging + committing gh-pages"
+  (cd "$GHPAGES_DIR" && git add "$CATALOG_SUBDIR")
+  if (cd "$GHPAGES_DIR" && git diff --cached --quiet); then
+    log "No changes to publish."
+    return 0
+  fi
+  local msg
+  msg="catalog: rebuild at $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  (cd "$GHPAGES_DIR" && git commit -m "$msg")
+  log "Pushing gh-pages"
+  (cd "$GHPAGES_DIR" && git push origin gh-pages)
+  log "Published."
+}
+
+cmd_help() {
+  sed -n '1,30p' "$0" | sed -n '/^# Usage/,/^#$/p'
+}
+
+# ---------- dispatch ----------
+sub="${1:-help}"
+shift || true
+case "$sub" in
+  check)    cmd_check   "$@" ;;
+  build)    cmd_build   "$@" ;;
+  preview)  cmd_preview "$@" ;;
+  serve)    cmd_serve   "$@" ;;
+  publish)  cmd_publish "$@" ;;
+  help|--help|-h) cmd_help ;;
+  *) die "unknown command: $sub  (try --help)" ;;
+esac

site/index.html.tmpl

@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Scarf Templates</title>
+  <meta name="description" content="Community catalog of Scarf project templates — pre-configured AI-agent projects with dashboards, cron jobs, and agent instructions.">
+  <link rel="stylesheet" href="styles.css">
+  <link rel="icon" type="image/png" href="assets/icon.png">
+</head>
+<body>
+  <header class="site-header">
+    <a class="brand" href=".">
+      <img src="assets/icon.png" alt="" width="40" height="40">
+      <span class="brand-name">Scarf Templates</span>
+    </a>
+    <nav class="site-nav">
+      <a href="https://github.com/awizemann/scarf">GitHub</a>
+      <a href="https://github.com/awizemann/scarf/blob/main/templates/CONTRIBUTING.md">Contribute</a>
+    </nav>
+  </header>
+
+  <section class="hero">
+    <h1>Pre-packaged projects for Scarf</h1>
+    <p>
+      Browse {{COUNT}} community template{{COUNT_PLURAL}} — each ships with a
+      ready-to-install Scarf dashboard, a cross-agent <code>AGENTS.md</code>, optional
+      cron jobs and skills. Click a template to see what it does; one click installs
+      it into Scarf.
+    </p>
+  </section>
+
+  <main class="catalog">
+    <div class="grid">
+      {{CARDS}}
+    </div>
+  </main>
+
+  <footer class="site-footer">
+    <p>
+      Scarf is open source:
+      <a href="https://github.com/awizemann/scarf">github.com/awizemann/scarf</a>.
+      Want to add your own template? See the
+      <a href="https://github.com/awizemann/scarf/blob/main/templates/CONTRIBUTING.md">contribution guide</a>.
+    </p>
+  </footer>
+</body>
+</html>

site/styles.css

@@ -0,0 +1,441 @@
+/* Scarf Templates — catalog site.
+ * Vanilla CSS, no framework. Matches Scarf's green accent and keeps
+ * decoration minimal — the live dashboard preview is the point. */
+
+:root {
+  --fg: #1a1a1a;
+  --fg-muted: #666;
+  --bg: #fafafa;
+  --bg-card: #ffffff;
+  --border: #e5e5e5;
+  --accent: #2aa876;        /* scarf green */
+  --accent-dark: #1f7f5a;
+  --red: #d9534f;
+  --blue: #3498db;
+  --orange: #f0ad4e;
+  --radius: 8px;
+  --shadow: 0 1px 2px rgba(0,0,0,0.04), 0 4px 12px rgba(0,0,0,0.04);
+  --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --fg: #e5e5e5;
+    --fg-muted: #9a9a9a;
+    --bg: #141414;
+    --bg-card: #1e1e1e;
+    --border: #2a2a2a;
+    --accent: #3abf8a;
+    --accent-dark: #2aa876;
+    --shadow: 0 1px 2px rgba(0,0,0,0.3), 0 4px 12px rgba(0,0,0,0.3);
+  }
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  font-family: var(--sans);
+  color: var(--fg);
+  background: var(--bg);
+  line-height: 1.5;
+}
+
+code, pre {
+  font-family: var(--mono);
+  font-size: 0.92em;
+}
+
+pre {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 12px 16px;
+  overflow-x: auto;
+}
+code {
+  background: rgba(0,0,0,0.05);
+  padding: 2px 5px;
+  border-radius: 4px;
+}
+pre code { background: transparent; padding: 0; }
+
+a { color: var(--accent-dark); text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+h1, h2, h3 { line-height: 1.25; }
+
+/* ---------- header / footer ---------- */
+
+.site-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 32px;
+  border-bottom: 1px solid var(--border);
+  background: var(--bg-card);
+}
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  color: var(--fg);
+}
+.brand:hover { text-decoration: none; }
+.brand-name { font-weight: 600; font-size: 18px; }
+.site-nav a {
+  margin-left: 20px;
+  color: var(--fg-muted);
+  font-size: 14px;
+}
+
+.site-footer {
+  padding: 32px;
+  text-align: center;
+  color: var(--fg-muted);
+  font-size: 14px;
+  border-top: 1px solid var(--border);
+  margin-top: 40px;
+}
+
+/* ---------- landing ---------- */
+
+.hero {
+  padding: 48px 32px 24px;
+  max-width: 720px;
+  margin: 0 auto;
+  text-align: center;
+}
+.hero h1 { font-size: 32px; margin: 0 0 12px; }
+.hero p { color: var(--fg-muted); }
+
+.catalog {
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 16px 32px 48px;
+}
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 16px;
+}
+.card {
+  display: block;
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 20px;
+  box-shadow: var(--shadow);
+  color: inherit;
+  transition: transform 0.12s ease, box-shadow 0.12s ease;
+}
+.card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 2px 4px rgba(0,0,0,0.06), 0 8px 24px rgba(0,0,0,0.06);
+  text-decoration: none;
+}
+.card h3 { margin: 0 0 6px; font-size: 18px; }
+.card .desc { color: var(--fg-muted); margin: 0 0 14px; font-size: 14px; }
+.card .meta {
+  display: flex;
+  justify-content: space-between;
+  font-size: 12px;
+  color: var(--fg-muted);
+  margin-bottom: 8px;
+}
+.card .author { font-weight: 500; }
+.card .version { font-family: var(--mono); }
+.tags { display: flex; flex-wrap: wrap; gap: 4px; }
+.tag {
+  display: inline-block;
+  padding: 2px 8px;
+  background: rgba(42,168,118,0.15);
+  color: var(--accent-dark);
+  border-radius: 10px;
+  font-size: 11px;
+}
+
+/* ---------- template detail page ---------- */
+
+.detail {
+  max-width: 900px;
+  margin: 0 auto;
+  padding: 32px;
+}
+.detail-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: 32px;
+  margin-bottom: 40px;
+  padding-bottom: 24px;
+  border-bottom: 1px solid var(--border);
+}
+.detail-header h1 { margin: 0 0 4px; }
+.detail-header h1 .version {
+  font-family: var(--mono);
+  font-size: 16px;
+  color: var(--fg-muted);
+  font-weight: 400;
+}
+.detail-header .desc { color: var(--fg-muted); margin: 0 0 12px; }
+.detail-header .meta {
+  display: flex;
+  gap: 16px;
+  font-size: 13px;
+  color: var(--fg-muted);
+  margin-bottom: 8px;
+}
+.detail-header .id { font-family: var(--mono); }
+
+.install-actions { display: flex; flex-direction: column; gap: 8px; min-width: 200px; }
+.btn {
+  display: inline-block;
+  padding: 10px 20px;
+  border-radius: var(--radius);
+  font-weight: 500;
+  text-align: center;
+  font-size: 14px;
+}
+.btn-primary {
+  background: var(--accent);
+  color: white;
+}
+.btn-primary:hover { background: var(--accent-dark); text-decoration: none; color: white; }
+.btn-secondary {
+  background: transparent;
+  color: var(--fg);
+  border: 1px solid var(--border);
+}
+.btn-secondary:hover { border-color: var(--accent); text-decoration: none; color: var(--accent-dark); }
+
+.detail-dashboard {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 24px;
+  margin-bottom: 32px;
+}
+.detail-dashboard h2 { margin-top: 0; }
+.detail-dashboard-note {
+  color: var(--fg-muted);
+  font-size: 13px;
+  margin-top: 4px;
+  margin-bottom: 20px;
+}
+
+.detail-readme h2 { margin-top: 0; }
+.detail-readme > div {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 24px;
+}
+
+/* ---------- config schema panel (v2.3) ---------- */
+
+.detail-config { margin-bottom: 32px; }
+.detail-config:empty, .detail-config > div:empty { display: none; }
+
+.config-schema {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 24px;
+}
+.config-schema-header { margin-top: 0; }
+.config-schema-desc {
+  color: var(--fg-muted);
+  font-size: 13px;
+  margin-top: 4px;
+  margin-bottom: 16px;
+}
+.config-schema-list {
+  margin: 0;
+  padding: 0;
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 12px;
+}
+.config-field-header {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  margin-top: 4px;
+  font-weight: 500;
+}
+.config-field-key { font-family: var(--mono); font-size: 13px; }
+.config-field-type {
+  font-family: var(--mono);
+  font-size: 11px;
+  padding: 1px 6px;
+  border-radius: 10px;
+  background: rgba(0,0,0,0.08);
+  color: var(--fg-muted);
+}
+.config-field-required {
+  font-size: 11px;
+  color: var(--red);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  padding: 1px 6px;
+  border-radius: 10px;
+  background: rgba(217,83,79,0.12);
+}
+.config-field-body {
+  margin: 0 0 4px 0;
+  padding-left: 0;
+  font-size: 14px;
+}
+.config-field-label {
+  font-size: 14px;
+  margin-bottom: 2px;
+}
+.config-field-description {
+  color: var(--fg-muted);
+  font-size: 13px;
+  margin-bottom: 4px;
+}
+.config-field-constraint {
+  font-size: 12px;
+  color: var(--fg-muted);
+  font-style: italic;
+}
+
+.config-model-rec {
+  margin-top: 20px;
+  padding: 14px 16px;
+  border-radius: var(--radius);
+  background: rgba(42,168,118,0.08);
+  border: 1px solid rgba(42,168,118,0.2);
+}
+.config-model-label {
+  font-size: 11px;
+  color: var(--accent-dark);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  font-weight: 600;
+  margin-bottom: 4px;
+}
+.config-model-preferred {
+  font-family: var(--mono);
+  font-size: 14px;
+  margin-bottom: 4px;
+}
+.config-model-rationale {
+  color: var(--fg-muted);
+  font-size: 13px;
+}
+.config-model-alternatives {
+  color: var(--fg-muted);
+  font-size: 12px;
+  margin-top: 4px;
+}
+
+/* ---------- dashboard preview ---------- */
+
+.dashboard-header h1.dashboard-title { margin: 0 0 4px; font-size: 22px; }
+.dashboard-desc { color: var(--fg-muted); margin: 0 0 24px; font-size: 14px; }
+.dashboard-section { margin-bottom: 24px; }
+.section-title { margin: 0 0 10px; font-size: 14px; font-weight: 600; color: var(--fg-muted); text-transform: uppercase; letter-spacing: 0.5px; }
+
+.widget-grid {
+  display: grid;
+  grid-template-columns: repeat(var(--cols, 3), 1fr);
+  gap: 12px;
+}
+
+.widget {
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 14px 16px;
+}
+
+.widget-title {
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--fg-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+/* stat */
+.widget-stat { display: flex; flex-direction: column; gap: 6px; }
+.widget-stat-top { display: flex; align-items: center; gap: 8px; }
+.widget-stat-icon { font-size: 14px; color: var(--fg-muted); }
+.widget-stat-value { font-size: 32px; font-weight: 600; line-height: 1.1; }
+.widget-stat-subtitle { font-size: 11px; color: var(--fg-muted); }
+.widget-stat[data-color="green"] .widget-stat-icon { color: var(--accent); }
+.widget-stat[data-color="red"] .widget-stat-icon { color: var(--red); }
+.widget-stat[data-color="blue"] .widget-stat-icon { color: var(--blue); }
+.widget-stat[data-color="orange"] .widget-stat-icon { color: var(--orange); }
+
+/* progress */
+.widget-progress-label { font-size: 13px; margin: 6px 0 8px; }
+.progress-bar { height: 8px; background: rgba(0,0,0,0.05); border-radius: 4px; overflow: hidden; }
+.progress-fill { height: 100%; background: var(--accent); border-radius: 4px; }
+
+/* text */
+.widget-text-body { font-size: 14px; margin-top: 6px; }
+.widget-text-body h1 { font-size: 20px; margin: 12px 0 8px; }
+.widget-text-body h2 { font-size: 17px; margin: 10px 0 6px; }
+.widget-text-body h3 { font-size: 14px; margin: 8px 0 4px; }
+.widget-text-body p { margin: 8px 0; }
+.widget-text-body ul, .widget-text-body ol { padding-left: 22px; }
+
+/* table */
+.data-table { width: 100%; border-collapse: collapse; font-size: 13px; margin-top: 8px; }
+.data-table th, .data-table td { padding: 6px 8px; border-bottom: 1px solid var(--border); text-align: left; }
+.data-table th { font-weight: 500; color: var(--fg-muted); }
+
+/* list */
+.widget-list-items { margin: 6px 0 0; padding-left: 18px; font-size: 13px; }
+.widget-list-item {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 3px 0;
+}
+.widget-list-text { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.widget-list-status {
+  font-size: 10px;
+  padding: 2px 6px;
+  border-radius: 10px;
+  background: rgba(0,0,0,0.08);
+  color: var(--fg-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  flex-shrink: 0;
+}
+.widget-list-status[data-status="up"] { background: rgba(42,168,118,0.18); color: var(--accent-dark); }
+.widget-list-status[data-status="down"] { background: rgba(217,83,79,0.18); color: var(--red); }
+
+/* chart */
+.widget-chart-svg { width: 100%; height: auto; margin-top: 8px; }
+.chart-axis { stroke: var(--border); stroke-width: 1; }
+.chart-line { fill: none; stroke-width: 2; }
+.chart-line[data-color="accent"], .chart-bar[data-color="accent"] { stroke: var(--accent); fill: var(--accent); }
+.chart-line[data-color="red"],    .chart-bar[data-color="red"]    { stroke: var(--red);    fill: var(--red); }
+.chart-line[data-color="blue"],   .chart-bar[data-color="blue"]   { stroke: var(--blue);   fill: var(--blue); }
+.chart-line[data-color="orange"], .chart-bar[data-color="orange"] { stroke: var(--orange); fill: var(--orange); }
+.widget-chart-empty { color: var(--fg-muted); font-size: 13px; padding: 20px 0; text-align: center; }
+
+/* webview */
+.widget-webview iframe { border: 1px solid var(--border); border-radius: 6px; margin-top: 8px; }
+
+/* unknown */
+.widget-unknown-body { color: var(--fg-muted); font-size: 13px; margin-top: 6px; }
+
+/* ---------- responsive ---------- */
+
+@media (max-width: 680px) {
+  .site-header { padding: 12px 16px; }
+  .site-nav a { margin-left: 12px; font-size: 13px; }
+  .hero { padding: 32px 16px 16px; }
+  .catalog, .detail { padding: 16px; }
+  .detail-header { flex-direction: column; gap: 16px; }
+  .install-actions { flex-direction: row; min-width: 0; }
+  .btn { flex: 1; }
+}

site/template.html.tmpl

@@ -0,0 +1,104 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{NAME}} — Scarf Templates</title>
+  <meta name="description" content="{{DESC}}">
+  <link rel="stylesheet" href="../styles.css">
+  <link rel="icon" type="image/png" href="../assets/icon.png">
+</head>
+<body>
+  <header class="site-header">
+    <a class="brand" href="..">
+      <img src="../assets/icon.png" alt="" width="40" height="40">
+      <span class="brand-name">Scarf Templates</span>
+    </a>
+    <nav class="site-nav">
+      <a href="..">Catalog</a>
+      <a href="https://github.com/awizemann/scarf">GitHub</a>
+      <a href="https://github.com/awizemann/scarf/blob/main/templates/CONTRIBUTING.md">Contribute</a>
+    </nav>
+  </header>
+
+  <main class="detail">
+    <section class="detail-header">
+      <div>
+        <h1>{{NAME}} <span class="version">v{{VERSION}}</span></h1>
+        <p class="desc">{{DESC}}</p>
+        <p class="meta">
+          <span class="author">by {{AUTHOR_HTML}}</span>
+          <span class="id">{{ID}}</span>
+          <span class="category">{{CATEGORY}}</span>
+        </p>
+        <p class="tags">{{TAGS_HTML}}</p>
+      </div>
+      <div class="install-actions">
+        <a class="btn btn-primary" href="{{SCARF_INSTALL_URL}}">Install with Scarf</a>
+        <a class="btn btn-secondary" href="{{INSTALL_URL_ENCODED}}">Download .scarftemplate</a>
+      </div>
+    </section>
+
+    <section class="detail-dashboard">
+      <h2>Live dashboard preview</h2>
+      <p class="detail-dashboard-note">
+        Exactly what you'll see inside Scarf after install. Values shown here are
+        placeholders; the agent updates them each time the cron job runs.
+      </p>
+      <div id="dashboard-preview"></div>
+    </section>
+
+    <section class="detail-config">
+      <div id="config-schema"></div>
+    </section>
+
+    <section class="detail-readme">
+      <h2>README</h2>
+      <div id="readme-body"></div>
+    </section>
+  </main>
+
+  <footer class="site-footer">
+    <p>
+      Scarf is open source:
+      <a href="https://github.com/awizemann/scarf">github.com/awizemann/scarf</a>.
+    </p>
+  </footer>
+
+  <script src="../widgets.js"></script>
+  <script>
+    // Fetch + render dashboard + README + config schema at page load.
+    // Dashboard + README live next to index.html in this template's
+    // detail dir; the config schema comes from the sibling manifest.json
+    // that the build-catalog renderer also copies in.
+    (async function () {
+      const dashboardEl = document.getElementById("dashboard-preview");
+      const readmeEl = document.getElementById("readme-body");
+      const configEl = document.getElementById("config-schema");
+      try {
+        const d = await fetch("dashboard.json").then(r => r.json());
+        ScarfWidgets.renderDashboard(dashboardEl, d);
+      } catch (e) {
+        dashboardEl.textContent = "Could not load dashboard preview.";
+      }
+      try {
+        const md = await fetch("README.md").then(r => r.text());
+        readmeEl.innerHTML = ScarfWidgets.renderMarkdown(md);
+      } catch (e) {
+        readmeEl.textContent = "Could not load README.";
+      }
+      try {
+        // manifest.json may not exist for schema-less templates — that's
+        // fine, we just leave the config section empty.
+        const res = await fetch("manifest.json");
+        if (res.ok) {
+          const manifest = await res.json();
+          ScarfWidgets.renderConfigSchema(configEl, manifest.config);
+        }
+      } catch (e) {
+        // Silent — config-schema display is optional.
+      }
+    })();
+  </script>
+</body>
+</html>

site/widgets.js

@@ -0,0 +1,523 @@
+// Scarf dashboard widget renderer — the dogfood piece.
+//
+// Takes the SAME `dashboard.json` shape the Scarf macOS app renders
+// (see scarf/scarf/Core/Models/ProjectDashboard.swift) and produces an
+// HTML approximation for the catalog site. A template's detail page
+// shows a live preview of exactly what the user's project dashboard
+// will look like after install.
+//
+// Widget types mirrored from the Swift dispatcher:
+//   stat      — big number + label + icon + color
+//   progress  — label + 0..1 bar
+//   text      — markdown (tiny subset renderer)
+//   table     — plain HTML table
+//   list      — bulleted list with optional status badge
+//   chart     — SVG line/bar by series
+//   webview   — sandboxed <iframe>
+//
+// Vanilla JS, no build step, no external deps. ~300 lines.
+
+(function (global) {
+  "use strict";
+
+  const SF_SYMBOL_FALLBACK = "●"; // SF Symbols aren't available on the web — use a dot.
+
+  // ---------------------------------------------------------------------
+  // Entry point
+  // ---------------------------------------------------------------------
+
+  /**
+   * Render a ProjectDashboard JSON into `container`.
+   * @param {HTMLElement} container
+   * @param {object} dashboard
+   */
+  function renderDashboard(container, dashboard) {
+    container.innerHTML = "";
+    if (!dashboard || !Array.isArray(dashboard.sections)) {
+      container.appendChild(elt("div", "dashboard-error", "Could not render dashboard."));
+      return;
+    }
+    const root = elt("div", "dashboard");
+    if (dashboard.title) {
+      const header = elt("div", "dashboard-header");
+      header.appendChild(elt("h1", "dashboard-title", dashboard.title));
+      if (dashboard.description) {
+        header.appendChild(elt("p", "dashboard-desc", dashboard.description));
+      }
+      root.appendChild(header);
+    }
+    for (const section of dashboard.sections) {
+      root.appendChild(renderSection(section));
+    }
+    container.appendChild(root);
+  }
+
+  function renderSection(section) {
+    const wrap = elt("section", "dashboard-section");
+    if (section.title) {
+      wrap.appendChild(elt("h2", "section-title", section.title));
+    }
+    const cols = Math.max(1, Math.min(6, section.columns || 3));
+    const grid = elt("div", "widget-grid");
+    grid.style.setProperty("--cols", String(cols));
+    // Webview widgets render in a dedicated tab in the Scarf app but
+    // we inline them here so the catalog preview is single-scroll.
+    for (const widget of section.widgets || []) {
+      grid.appendChild(renderWidget(widget));
+    }
+    wrap.appendChild(grid);
+    return wrap;
+  }
+
+  function renderWidget(widget) {
+    try {
+      switch (widget.type) {
+        case "stat":     return renderStat(widget);
+        case "progress": return renderProgress(widget);
+        case "text":     return renderText(widget);
+        case "table":    return renderTable(widget);
+        case "list":     return renderList(widget);
+        case "chart":    return renderChart(widget);
+        case "webview":  return renderWebview(widget);
+        default:         return renderUnknown(widget);
+      }
+    } catch (e) {
+      console.error("widget render error", widget, e);
+      return renderUnknown({ ...widget, title: (widget.title || "") + " (render error)" });
+    }
+  }
+
+  // ---------------------------------------------------------------------
+  // Stat
+  // ---------------------------------------------------------------------
+
+  function renderStat(widget) {
+    const card = elt("div", "widget widget-stat");
+    card.dataset.color = widget.color || "blue";
+    const top = elt("div", "widget-stat-top");
+    top.appendChild(elt("span", "widget-stat-icon", SF_SYMBOL_FALLBACK));
+    top.appendChild(elt("span", "widget-title", widget.title || ""));
+    card.appendChild(top);
+    const value = elt("div", "widget-stat-value", displayValue(widget.value));
+    card.appendChild(value);
+    if (widget.subtitle) {
+      card.appendChild(elt("div", "widget-stat-subtitle", widget.subtitle));
+    }
+    return card;
+  }
+
+  function displayValue(v) {
+    if (v === null || v === undefined) return "—";
+    if (typeof v === "number") {
+      return Number.isInteger(v) ? v.toLocaleString() : v.toFixed(1);
+    }
+    return String(v);
+  }
+
+  // ---------------------------------------------------------------------
+  // Progress
+  // ---------------------------------------------------------------------
+
+  function renderProgress(widget) {
+    const card = elt("div", "widget widget-progress");
+    card.appendChild(elt("div", "widget-title", widget.title || ""));
+    if (widget.label) {
+      card.appendChild(elt("div", "widget-progress-label", widget.label));
+    }
+    const bar = elt("div", "progress-bar");
+    const fill = elt("div", "progress-fill");
+    const pct = Math.max(0, Math.min(1, Number(widget.value) || 0));
+    fill.style.width = (pct * 100).toFixed(1) + "%";
+    bar.appendChild(fill);
+    card.appendChild(bar);
+    return card;
+  }
+
+  // ---------------------------------------------------------------------
+  // Text (markdown)
+  // ---------------------------------------------------------------------
+
+  function renderText(widget) {
+    const card = elt("div", "widget widget-text");
+    card.appendChild(elt("div", "widget-title", widget.title || ""));
+    const body = elt("div", "widget-text-body");
+    if ((widget.format || "").toLowerCase() === "markdown") {
+      body.innerHTML = renderMarkdown(widget.content || "");
+    } else {
+      body.textContent = widget.content || "";
+    }
+    card.appendChild(body);
+    return card;
+  }
+
+  /** Minimal markdown subset: headings, bold, italic, inline code, code
+   * blocks, bullet/numbered lists, links, paragraphs. Deliberately tiny
+   * — the catalog showcases dashboards, not blog posts. */
+  function renderMarkdown(src) {
+    const lines = src.split(/\r?\n/);
+    let html = "";
+    let inCode = false;
+    let inList = null; // "ul" | "ol" | null
+    const flushList = () => {
+      if (inList) {
+        html += `</${inList}>`;
+        inList = null;
+      }
+    };
+    for (const rawLine of lines) {
+      const line = rawLine;
+      if (line.trim().startsWith("```")) {
+        flushList();
+        if (inCode) {
+          html += "</code></pre>";
+          inCode = false;
+        } else {
+          html += "<pre><code>";
+          inCode = true;
+        }
+        continue;
+      }
+      if (inCode) {
+        html += escapeHTML(line) + "\n";
+        continue;
+      }
+      if (/^#{1,6}\s/.test(line)) {
+        flushList();
+        const level = Math.min(6, (line.match(/^#+/) || ["#"])[0].length);
+        const text = line.replace(/^#+\s*/, "");
+        html += `<h${level}>${renderInline(text)}</h${level}>`;
+        continue;
+      }
+      const bulletMatch = line.match(/^\s*[-*]\s+(.*)$/);
+      const orderedMatch = line.match(/^\s*\d+\.\s+(.*)$/);
+      if (bulletMatch) {
+        if (inList !== "ul") { flushList(); html += "<ul>"; inList = "ul"; }
+        html += `<li>${renderInline(bulletMatch[1])}</li>`;
+        continue;
+      }
+      if (orderedMatch) {
+        if (inList !== "ol") { flushList(); html += "<ol>"; inList = "ol"; }
+        html += `<li>${renderInline(orderedMatch[1])}</li>`;
+        continue;
+      }
+      if (line.trim() === "") {
+        flushList();
+        continue;
+      }
+      flushList();
+      html += `<p>${renderInline(line)}</p>`;
+    }
+    flushList();
+    if (inCode) html += "</code></pre>";
+    return html;
+  }
+
+  function renderInline(text) {
+    // Escape first, then re-apply formatting on the escaped text.
+    let s = escapeHTML(text);
+    // Inline code before bold/italic so the markers inside `…` stay literal.
+    s = s.replace(/`([^`]+)`/g, "<code>$1</code>");
+    s = s.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+    s = s.replace(/(^|[^\w])\*([^*]+)\*/g, "$1<em>$2</em>");
+    s = s.replace(/(^|[^\w])_([^_]+)_/g, "$1<em>$2</em>");
+    // Links: [text](url)
+    s = s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_m, text, url) => {
+      return `<a href="${url}">${text}</a>`;
+    });
+    return s;
+  }
+
+  // ---------------------------------------------------------------------
+  // Table
+  // ---------------------------------------------------------------------
+
+  function renderTable(widget) {
+    const card = elt("div", "widget widget-table");
+    card.appendChild(elt("div", "widget-title", widget.title || ""));
+    const table = elt("table", "data-table");
+    if (Array.isArray(widget.columns)) {
+      const thead = elt("thead");
+      const tr = elt("tr");
+      for (const col of widget.columns) {
+        tr.appendChild(elt("th", null, col));
+      }
+      thead.appendChild(tr);
+      table.appendChild(thead);
+    }
+    if (Array.isArray(widget.rows)) {
+      const tbody = elt("tbody");
+      for (const row of widget.rows) {
+        const tr = elt("tr");
+        for (const cell of row) {
+          tr.appendChild(elt("td", null, cell));
+        }
+        tbody.appendChild(tr);
+      }
+      table.appendChild(tbody);
+    }
+    card.appendChild(table);
+    return card;
+  }
+
+  // ---------------------------------------------------------------------
+  // List
+  // ---------------------------------------------------------------------
+
+  function renderList(widget) {
+    const card = elt("div", "widget widget-list");
+    card.appendChild(elt("div", "widget-title", widget.title || ""));
+    const ul = elt("ul", "widget-list-items");
+    for (const item of widget.items || []) {
+      const li = elt("li", "widget-list-item");
+      li.appendChild(elt("span", "widget-list-text", item.text || ""));
+      if (item.status) {
+        const badge = elt("span", "widget-list-status", item.status);
+        badge.dataset.status = item.status;
+        li.appendChild(badge);
+      }
+      ul.appendChild(li);
+    }
+    card.appendChild(ul);
+    return card;
+  }
+
+  // ---------------------------------------------------------------------
+  // Chart (SVG — no Chart.js dep)
+  // ---------------------------------------------------------------------
+
+  function renderChart(widget) {
+    const card = elt("div", "widget widget-chart");
+    card.appendChild(elt("div", "widget-title", widget.title || ""));
+    const series = widget.series || [];
+    if (series.length === 0) {
+      card.appendChild(elt("div", "widget-chart-empty", "No chart data."));
+      return card;
+    }
+    // Collect x-labels (assume aligned across series).
+    const xs = series[0].data.map((p) => p.x);
+    const ys = series.flatMap((s) => s.data.map((p) => p.y));
+    const maxY = Math.max(0, ...ys);
+    const minY = Math.min(0, ...ys);
+    const W = 320;
+    const H = 120;
+    const padL = 24, padR = 8, padT = 8, padB = 22;
+    const plotW = W - padL - padR;
+    const plotH = H - padT - padB;
+
+    const svgNS = "http://www.w3.org/2000/svg";
+    const svg = document.createElementNS(svgNS, "svg");
+    svg.setAttribute("viewBox", `0 0 ${W} ${H}`);
+    svg.classList.add("widget-chart-svg");
+
+    const yToPixel = (y) => {
+      if (maxY === minY) return padT + plotH / 2;
+      return padT + plotH - ((y - minY) / (maxY - minY)) * plotH;
+    };
+    const xToPixel = (i) => padL + (plotW * (i / Math.max(1, xs.length - 1)));
+
+    // Axis baseline
+    const axis = document.createElementNS(svgNS, "line");
+    axis.setAttribute("x1", String(padL));
+    axis.setAttribute("y1", String(padT + plotH));
+    axis.setAttribute("x2", String(W - padR));
+    axis.setAttribute("y2", String(padT + plotH));
+    axis.setAttribute("class", "chart-axis");
+    svg.appendChild(axis);
+
+    const kind = (widget.chartType || "line").toLowerCase();
+    series.forEach((s, idx) => {
+      const color = s.color || ["accent", "red", "blue", "orange"][idx % 4];
+      if (kind === "bar") {
+        const barW = Math.max(2, plotW / (xs.length * series.length) - 2);
+        s.data.forEach((p, i) => {
+          const rect = document.createElementNS(svgNS, "rect");
+          const x = xToPixel(i) - barW / 2 + idx * barW;
+          const y = yToPixel(p.y);
+          rect.setAttribute("x", String(x));
+          rect.setAttribute("y", String(y));
+          rect.setAttribute("width", String(barW));
+          rect.setAttribute("height", String(padT + plotH - y));
+          rect.setAttribute("class", "chart-bar");
+          rect.dataset.color = color;
+          svg.appendChild(rect);
+        });
+      } else {
+        const d = s.data.map((p, i) => {
+          const x = xToPixel(i);
+          const y = yToPixel(p.y);
+          return `${i === 0 ? "M" : "L"} ${x.toFixed(1)} ${y.toFixed(1)}`;
+        }).join(" ");
+        const path = document.createElementNS(svgNS, "path");
+        path.setAttribute("d", d);
+        path.setAttribute("class", "chart-line");
+        path.dataset.color = color;
+        svg.appendChild(path);
+      }
+    });
+
+    card.appendChild(svg);
+    return card;
+  }
+
+  // ---------------------------------------------------------------------
+  // Webview
+  // ---------------------------------------------------------------------
+
+  function renderWebview(widget) {
+    const card = elt("div", "widget widget-webview");
+    card.appendChild(elt("div", "widget-title", widget.title || ""));
+    const frame = document.createElement("iframe");
+    frame.src = widget.url || "about:blank";
+    frame.setAttribute("sandbox", "allow-scripts allow-popups allow-forms");
+    frame.style.width = "100%";
+    frame.style.height = (widget.height ? Number(widget.height) : 300) + "px";
+    frame.loading = "lazy";
+    card.appendChild(frame);
+    return card;
+  }
+
+  // ---------------------------------------------------------------------
+  // Unknown / placeholder
+  // ---------------------------------------------------------------------
+
+  function renderUnknown(widget) {
+    const card = elt("div", "widget widget-unknown");
+    card.appendChild(elt("div", "widget-title", widget.title || ""));
+    card.appendChild(elt("div", "widget-unknown-body",
+      `Unknown widget type: ${widget.type}`));
+    return card;
+  }
+
+  // ---------------------------------------------------------------------
+  // Utilities
+  // ---------------------------------------------------------------------
+
+  function elt(tag, cls, text) {
+    const e = document.createElement(tag);
+    if (cls) e.className = cls;
+    if (text !== undefined && text !== null) e.textContent = String(text);
+    return e;
+  }
+
+  function escapeHTML(s) {
+    return String(s)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#39;");
+  }
+
+  // ---------------------------------------------------------------------
+  // Config-schema display (v2.3 — template configuration).
+  // ---------------------------------------------------------------------
+  //
+  // Renders the author-declared schema as a read-only listing on the
+  // catalog detail page. The site itself never collects values — the
+  // form UI lives inside the Scarf app. This is purely informational
+  // so visitors know what they'll need to fill in before installing.
+
+  /**
+   * Render a manifest.config block into `container` as a summary.
+   * Safe to call with a null schema (no-op).
+   * @param {HTMLElement} container
+   * @param {{schema: Array, modelRecommendation?: object} | null | undefined} config
+   */
+  function renderConfigSchema(container, config) {
+    container.innerHTML = "";
+    if (!config || !Array.isArray(config.schema) || config.schema.length === 0) {
+      return;
+    }
+    const wrap = elt("div", "config-schema");
+    const header = elt("h3", "config-schema-header", "Configuration");
+    wrap.appendChild(header);
+    const desc = elt("p", "config-schema-desc",
+      "Fields you'll fill in during install. Secrets are stored in the macOS Keychain; non-secret values live at <project>/.scarf/config.json.");
+    wrap.appendChild(desc);
+
+    const list = elt("dl", "config-schema-list");
+    for (const field of config.schema) {
+      const dt = elt("dt", "config-field-header");
+      dt.appendChild(elt("span", "config-field-key", field.key || ""));
+      dt.appendChild(elt("span", "config-field-type", field.type || ""));
+      if (field.required) {
+        const req = elt("span", "config-field-required", "required");
+        dt.appendChild(req);
+      }
+      list.appendChild(dt);
+
+      const dd = elt("dd", "config-field-body");
+      if (field.label) {
+        dd.appendChild(elt("div", "config-field-label", field.label));
+      }
+      if (field.description) {
+        const descEl = elt("div", "config-field-description");
+        descEl.innerHTML = renderInline(field.description);
+        dd.appendChild(descEl);
+      }
+      const constraint = summariseConstraint(field);
+      if (constraint) {
+        dd.appendChild(elt("div", "config-field-constraint", constraint));
+      }
+      list.appendChild(dd);
+    }
+    wrap.appendChild(list);
+
+    if (config.modelRecommendation) {
+      const rec = config.modelRecommendation;
+      const recBlock = elt("div", "config-model-rec");
+      recBlock.appendChild(elt("div", "config-model-label", "Recommended model"));
+      recBlock.appendChild(elt("div", "config-model-preferred", rec.preferred || ""));
+      if (rec.rationale) {
+        recBlock.appendChild(elt("div", "config-model-rationale", rec.rationale));
+      }
+      if (Array.isArray(rec.alternatives) && rec.alternatives.length > 0) {
+        recBlock.appendChild(elt("div", "config-model-alternatives",
+          "Also works: " + rec.alternatives.join(", ")));
+      }
+      wrap.appendChild(recBlock);
+    }
+
+    container.appendChild(wrap);
+  }
+
+  /** One-line human summary of a field's type-specific constraints.
+   * Empty string if nothing noteworthy to say. */
+  function summariseConstraint(field) {
+    const type = field.type;
+    if (type === "enum") {
+      const opts = Array.isArray(field.options) ? field.options : [];
+      const values = opts.map(o => o && o.label ? o.label : (o && o.value) || "").filter(Boolean);
+      if (values.length > 0) return "Choices: " + values.join(", ");
+    } else if (type === "list") {
+      const min = field.minItems, max = field.maxItems;
+      if (min && max) return `${min}–${max} items`;
+      if (min) return `At least ${min} item${min === 1 ? "" : "s"}`;
+      if (max) return `At most ${max} item${max === 1 ? "" : "s"}`;
+    } else if (type === "string" || type === "text") {
+      if (field.pattern) return `Pattern: ${field.pattern}`;
+      const min = field.minLength, max = field.maxLength;
+      if (min && max) return `${min}–${max} characters`;
+      if (min) return `At least ${min} characters`;
+      if (max) return `At most ${max} characters`;
+    } else if (type === "number") {
+      const min = field.min, max = field.max;
+      if (min !== undefined && max !== undefined) return `${min}–${max}`;
+      if (min !== undefined) return `≥ ${min}`;
+      if (max !== undefined) return `≤ ${max}`;
+    } else if (type === "secret") {
+      return "Stored in the macOS Keychain on install — never in git, never in config.json.";
+    }
+    return "";
+  }
+
+  // ---------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------
+
+  global.ScarfWidgets = {
+    renderDashboard,
+    renderMarkdown,      // used by the detail page's README block
+    renderConfigSchema,  // used by the detail page's Configuration block
+  };
+})(typeof window !== "undefined" ? window : this);

templates/CONTRIBUTING.md

@@ -0,0 +1,147 @@
+# Contributing a template to Scarf
+
+Thanks for packaging something up for other Scarf users. This guide walks you through the full submission flow end-to-end.
+
+## Before you start
+
+- You need Scarf 2.2 or later installed to build + test your template.
+- Your template must ship a cross-agent **`AGENTS.md`** — that's the Linux Foundation open standard ([agents.md](https://agents.md/)) every major coding agent reads. Templates without one are rejected; Scarf specifically supports agent-portable projects.
+- Templates are free and MIT-licensed implicitly by submission. Don't submit anything you don't have rights to.
+
+## What makes a good template
+
+- **Scoped.** One purpose per template. A "does-everything" template is harder to maintain than three focused ones.
+- **Agent-first.** The `AGENTS.md` tells any agent how to interact with your project. Spell out the project layout, what each file is for, and what the agent should do when the user asks common questions ("run the X job", "add a Y").
+- **Self-contained prompts.** Cron jobs + skills should not assume state the template doesn't ship. If you need a `sites.txt`, have `AGENTS.md` tell the agent to bootstrap it on first run (see `awizemann/site-status-checker` for the pattern).
+- **Paused by default.** Every cron job ships disabled — Scarf pauses new jobs on install. Write prompts that work whether fired by cron or invoked directly in chat.
+- **No secrets.** No API keys, no hostnames, no paths specific to your machine. The catalog's CI secret-scan will block obvious cases but this is on you.
+- **No config writes.** Templates must not modify `~/.hermes/config.yaml`, `auth.json`, or any credential path. The installer refuses v1 bundles that claim to. If you need integration with, say, a specific MCP server, document the prerequisite in your README instead of trying to install it.
+
+## Step-by-step submission
+
+### 1. Fork + clone
+
+```bash
+gh repo fork awizemann/scarf --clone && cd scarf
+```
+
+### 2. Create your template directory
+
+```bash
+mkdir -p templates/<your-github-handle>/<your-template-name>/staging
+cd templates/<your-github-handle>/<your-template-name>/staging
+```
+
+Directory names are lowercase, hyphenated, stable: people will type them.
+
+### 3. Author the bundle
+
+Minimum required files under `staging/`:
+
+- **`template.json`** — manifest. Schema:
+  ```json
+  {
+    "schemaVersion": 1,
+    "id": "<your-handle>/<your-template-name>",
+    "name": "Your Template Name",
+    "version": "1.0.0",
+    "minScarfVersion": "2.2.0",
+    "minHermesVersion": "0.9.0",
+    "author": { "name": "Your Name", "url": "https://…" },
+    "description": "One-line pitch shown in the catalog.",
+    "category": "monitoring",
+    "tags": ["short", "list"],
+    "contents": {
+      "dashboard": true,
+      "agentsMd": true,
+      "cron": 0,
+      "instructions": null,
+      "skills": null,
+      "memory": null
+    }
+  }
+  ```
+  The `contents` claim must exactly match what's in `staging/` — the validator cross-checks and rejects mismatches.
+
+- **`README.md`** — shown on the catalog detail page. Include: what the project does, what the user has to do after install, how to customize, how to uninstall.
+
+- **`AGENTS.md`** — the cross-agent spec. Include: project layout, first-run bootstrap (if any), what each cron job expects to happen, and answers to common user prompts (`"what's the status"`, `"add a X"`, etc.).
+
+- **`dashboard.json`** — the Scarf dashboard that renders on the catalog detail page and after install. See [awizemann/site-status-checker/staging/dashboard.json](awizemann/site-status-checker/staging/dashboard.json) for the schema in action.
+
+Optional:
+
+- `instructions/CLAUDE.md`, `instructions/GEMINI.md`, `instructions/.cursorrules`, `instructions/.github/copilot-instructions.md` — agent-specific shims beyond `AGENTS.md`.
+- `skills/<skill-name>/SKILL.md` — shipped skills, installed into `~/.hermes/skills/templates/<slug>/` on the user's side.
+- `cron/jobs.json` — an array of cron job specs. Each has `name`, `schedule` (e.g. `0 9 * * *` or `every 2h`), `prompt`, optional `deliver`, `skills[]`, `repeat`. The prompt may use these install-time placeholders — the installer substitutes them before registering the cron job with Hermes:
+  - `{{PROJECT_DIR}}` — absolute path of the newly-installed project dir. **Required for any cron prompt that reads or writes project files** — Hermes doesn't set a CWD when firing cron jobs, so relative paths (`.scarf/config.json`) won't resolve. Write `{{PROJECT_DIR}}/.scarf/config.json` instead.
+  - `{{TEMPLATE_ID}}` — the `owner/name` id from your manifest.
+  - `{{TEMPLATE_SLUG}}` — the sanitised slug used for the project dir name + skills namespace.
+- `memory/append.md` — markdown appended to the user's `MEMORY.md` between template-specific markers. Use sparingly — most templates don't need this.
+
+### 4. Build the bundle
+
+From the `staging/` directory:
+
+```bash
+cd ..
+zip -qq -r <your-template-name>.scarftemplate staging/
+mv <your-template-name>.scarftemplate .    # end up alongside staging/
+```
+
+Or equivalently:
+
+```bash
+cd staging && zip -qq -r ../<your-template-name>.scarftemplate . && cd ..
+```
+
+### 5. Test locally in Scarf
+
+1. Open Scarf → Projects → Templates → **Install from File…** → select your `.scarftemplate`.
+2. Walk through the preview sheet. Make sure every file, cron job, and memory block shown is something you meant to ship.
+3. Install into a scratch parent dir. Verify the dashboard renders. Enable the cron job(s) if any and trigger them manually to confirm your `AGENTS.md` drives the right behavior.
+4. Right-click the project → **Uninstall Template…** → verify nothing unexpected remains.
+
+### 6. Validate
+
+Before opening the PR, run the catalog validator locally:
+
+```bash
+python3 tools/build-catalog.py --check
+```
+
+This checks every template in the repo (including yours), verifies the manifest matches the bundle contents, refuses bundles >5 MB, and flags common secret patterns. If it fails, fix the reported issues before pushing.
+
+### 7. Open the PR
+
+```bash
+git checkout -b add-<your-template-name>
+git add templates/<your-handle>/<your-template-name>
+git commit -m "feat(templates): add <your-template-name>"
+git push origin add-<your-template-name>
+gh pr create
+```
+
+**Do not modify `templates/catalog.json`** — the maintainer regenerates it after merge to keep PR diffs small.
+
+The scarf repo ships a tailored submission checklist at [.github/PULL_REQUEST_TEMPLATE/template-submission.md](../.github/PULL_REQUEST_TEMPLATE/template-submission.md). To apply it to your PR, append `?template=template-submission.md` to the compare URL when opening the PR in the browser, or copy the checkbox list into the body manually.
+
+GitHub Actions runs the validator on your PR (see [.github/workflows/validate-template-pr.yml](../.github/workflows/validate-template-pr.yml)). A green check means the bundle structure is sound; it doesn't mean the content is approved. Expect a maintainer pass for content quality (is the `AGENTS.md` clear, does the prompt do what you describe, is the scope reasonable).
+
+### 8. Iterate + ship
+
+Respond to review feedback. Common requests:
+
+- Sharpen the `README.md` so install/uninstall steps are copy-pasteable.
+- Split ambitious cron prompts into smaller, clearly-scoped ones.
+- Remove things the template doesn't need (an empty `skills/` dir, an unused `deliver` target, etc.).
+
+Once merged, your template shows up at `https://awizemann.github.io/scarf/templates/<your-handle>-<your-name>/` within a few minutes (the maintainer pushes the site regeneration by hand).
+
+## Updating an existing template
+
+Bump `version` in `template.json`, rebuild the `.scarftemplate`, commit, PR. The Install button on the catalog always points at the latest `main` version — there's no per-version pinning in v1. Users who already installed get no automatic update; they'd have to uninstall + reinstall for v2.
+
+## Questions?
+
+Open a [GitHub Discussion](https://github.com/awizemann/scarf/discussions) — the tag `templates` is watched.

templates/README.md

@@ -0,0 +1,52 @@
+# Scarf Templates
+
+The community template catalog for [Scarf](https://github.com/awizemann/scarf) — a macOS GUI for the Hermes AI agent. Each subdirectory here is one installable project template. Browse the live catalog with live dashboard previews at **<https://awizemann.github.io/scarf/templates/>**.
+
+## What's a template?
+
+A `.scarftemplate` bundle ships:
+
+- A pre-configured project **dashboard** (widgets for stats, lists, text, charts).
+- A cross-agent **`AGENTS.md`** ([agents.md standard](https://agents.md/)) that tells Claude Code, Cursor, Codex, Aider, Jules, Copilot, Zed, etc. how to work with the project.
+- Optional **skills**, **cron jobs**, optional per-agent instruction shims (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`), and an optional **memory appendix**.
+
+Users install with one click from the catalog site or by opening a `.scarftemplate` file in Scarf.
+
+## Layout
+
+Each template lives at `templates/<github-handle>/<template-name>/` with:
+
+```
+templates/<github-handle>/<template-name>/
+├── staging/                               source tree
+│   ├── template.json                      manifest (id, name, version, contents claim)
+│   ├── README.md                          shown on catalog detail page
+│   ├── AGENTS.md                          required cross-agent instructions
+│   ├── dashboard.json                     rendered as a live preview on the catalog site
+│   ├── instructions/…                     optional per-agent shims
+│   ├── skills/…                           optional namespaced skills
+│   ├── cron/jobs.json                     optional cron job definitions
+│   └── memory/append.md                   optional memory appendix
+├── <template-name>.scarftemplate          built bundle (zipped staging/), committed as-is
+└── screenshots/                           optional PNGs for the detail page
+```
+
+The built `.scarftemplate` is served directly from `raw.githubusercontent.com` — the catalog's Install button links at:
+
+```
+scarf://install?url=https://raw.githubusercontent.com/awizemann/scarf/main/templates/<author>/<name>/<name>.scarftemplate
+```
+
+## Contributing a template
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full submission walkthrough. tl;dr: fork, drop a template under `templates/<your-handle>/<your-name>/`, open a PR. A CI check validates the bundle; a maintainer reviews the content.
+
+## Catalog metadata
+
+`catalog.json` at this directory is the aggregate index that the website reads. It's regenerated by the maintainer on merge — **do not modify it in your PR**, the build script will take care of it.
+
+## Current templates
+
+| Template | Author | Description |
+|---|---|---|
+| [site-status-checker](awizemann/site-status-checker/) | awizemann | Daily HTTP uptime check for a user-editable list of URLs. Dashboard + cron + AGENTS.md. |

templates/awizemann/site-status-checker/staging/AGENTS.md

@@ -0,0 +1,75 @@
+# Site Status Checker — Agent Instructions
+
+This project maintains a daily uptime check for a list of URLs the user configured during install. The same instructions apply whether you're Hermes, Claude Code, Cursor, Codex, Aider, or any other agent that reads `AGENTS.md`.
+
+## Project layout
+
+- `.scarf/config.json` — **the source of truth for what to check.** Written by Scarf's install/configure UI; holds a `values.sites` field (a JSON array of URL strings) and a `values.timeout_seconds` field (a number, default 10).
+- `.scarf/manifest.json` — cached copy of `template.json`, used by Scarf's Configuration editor to re-render the form. Don't modify.
+- `status-log.md` — append-only markdown log. Newest run at the top. Each run is a section with the ISO-8601 timestamp as the heading. Created on the first run if it doesn't exist.
+- `.scarf/dashboard.json` — Scarf dashboard. **Only the `value` fields of the three stat widgets and the `items` array of the "Watched Sites" list widget should be updated.** The section titles, widget types, and structure must stay intact.
+
+## How configuration works
+
+The user configures this project through Scarf's UI — not by editing files directly. On install, a form asked them for the list of sites and a request timeout; those values landed in `.scarf/config.json`. They can edit those values any time via the **Configuration** button on the project dashboard header.
+
+Read configuration like this (JSON, via whatever file-read tool you have):
+
+```
+cat .scarf/config.json
+# → { "values": { "sites": ["https://foo.com", "https://bar.com"],
+#                 "timeout_seconds": 10 }, ... }
+```
+
+**Never** edit `.scarf/config.json` yourself. If the user asks "add a site" in chat, tell them to open the Configuration button on the dashboard. (A future Scarf release may expose a tool for agents to write config programmatically; until then, configuration is a user action.)
+
+## First-run bootstrap
+
+If `status-log.md` doesn't exist, create it with a one-line header:
+
+```
+# Site Status Log
+
+Newest run at the top. Each section is a single check.
+```
+
+No `sites.txt` anymore — sites come from `.scarf/config.json`.
+
+## What to do when the cron job fires
+
+The cron prompt Scarf registers for this project carries **absolute paths** (the installer substitutes `{{PROJECT_DIR}}` at install time) — you don't need to figure out the project's location yourself. Use whatever absolute paths appear in the prompt you received; if you're working in the project's interactive chat instead, the paths below are relative to the project root.
+
+1. Read `.scarf/config.json`. Extract `values.sites` (array of URLs) and `values.timeout_seconds` (number). If `sites` is empty or missing, write a `status-log.md` entry noting "no sites configured — open Configuration to add some" and leave the dashboard untouched.
+2. For each URL in `sites`, make an HTTP GET request with the configured timeout. Follow up to 3 redirects. Treat any 2xx or 3xx response as **up**, anything else (including timeouts and DNS failures) as **down**.
+3. Build a results table: URL, status (up/down), HTTP code (or error reason), response time in milliseconds.
+4. Prepend a new section to `status-log.md`:
+   ```
+   ## <ISO-8601 timestamp>
+
+   | URL | Status | Code | Latency |
+   |-----|--------|------|---------|
+   | … | up | 200 | 142 ms |
+   | … | down | timeout | — |
+   ```
+5. Update `.scarf/dashboard.json`:
+   - `Sites Up` stat widget: `value` = count of up results.
+   - `Sites Down` stat widget: `value` = count of down results.
+   - `Last Checked` stat widget: `value` = the ISO-8601 timestamp you just wrote.
+   - `Watched Sites` list widget `items`: one entry per URL with `text` = URL and `status` = `"up"` or `"down"` (lowercase).
+   - `First Watched Site` **webview widget** (in the "Live Site Preview" section): set its `url` field to the **first** URL from `values.sites`. This is what the user sees rendered in the Scarf **Site** tab. If `values.sites` is empty, leave the webview's existing `url` alone.
+6. If the cron job has a `deliver` target set, emit a one-line summary (`3 up, 1 down — example.com timed out`) as the agent's final response so the delivery mechanism picks it up.
+
+## What not to do
+
+- Don't modify the structure of `dashboard.json` (section titles, widget types, widget titles, `columns`). Only the values listed above are writable.
+- Don't edit `.scarf/config.json` — that's the user's responsibility via the Configuration UI.
+- Don't truncate `status-log.md` — it's the historical record. If it grows past 1 MB, add a one-line note at the top of the file asking the user to archive it.
+- Don't invent URLs or pull them from anywhere other than `values.sites`.
+- Don't run browsers or headless Chrome. Plain HTTP GET is sufficient.
+
+## When the user asks you things
+
+- "What's the status of my sites?" — read the top section of `status-log.md` and summarize.
+- "Add a site" / "Remove a site" — tell them: *"Click the Configuration button on the dashboard header (the slider icon, next to the folder). Add or remove the URL there and save. The next cron run will pick it up."* Don't try to edit config.json yourself.
+- "Run the check now" — do everything in the cron flow above, then summarize the results in chat.
+- "Why is [site] down?" — read the last 3–5 entries for that URL in `status-log.md` and report any pattern you see (consistent timeouts, intermittent 5xx, DNS failures, etc.). Don't speculate beyond what the log shows.

templates/awizemann/site-status-checker/staging/README.md

@@ -0,0 +1,39 @@
+# Site Status Checker
+
+A minimal uptime watchdog that pings a list of URLs once a day, records pass/fail results, and keeps a simple Scarf dashboard up to date.
+
+**Requires Scarf 2.3+** — this template uses the configuration feature (a form during install, and a Configuration button on the dashboard for editing later).
+
+## What you get
+
+- **Configurable site list** — you tell Scarf which URLs to watch during install, via a form. No file editing required. Edit the list later via the **Configuration** button on the project dashboard (slider icon next to the folder).
+- **Configurable timeout** — how long to wait per URL before giving up, also set via the form.
+- **`.scarf/config.json`** — where your configured values land. The agent reads this at run time; you never need to open it by hand.
+- **`status-log.md`** — the agent's append-only log of check results. New runs append a section at the top. Created automatically on first run.
+- **`.scarf/dashboard.json`** — Scarf dashboard with live stat widgets (sites up, sites down, last checked), the full list of watched sites with their last-known status, and a usage guide.
+- **Cron job `Check site status`** — registered (paused) by the installer; tag `[tmpl:awizemann/site-status-checker]`. Runs daily at 9:00 AM when enabled. Reads your configured sites + timeout, hits each URL, writes results to `status-log.md`, and updates the dashboard.
+
+## First steps
+
+1. During install, fill in the Configuration form: add the URLs you want to watch and (optionally) adjust the timeout. Hit Continue, then Install.
+2. After install, open the **Cron** sidebar and enable the `[tmpl:awizemann/site-status-checker] Check site status` job. It's paused on install so nothing runs without your explicit say-so.
+3. From the project's dashboard, ask your agent to run the job now: *"Run the site status check and update the dashboard."*
+4. Future runs happen automatically at 9 AM daily.
+
+## Changing sites or timeout later
+
+Click the **Configuration** button (slider icon, dashboard toolbar) to re-open the form pre-filled with your current values. Add, remove, or edit URLs. Save. The next cron run picks up the changes.
+
+## Customizing
+
+- **Change the schedule.** Edit the cron job in the Cron sidebar — the schedule field accepts `30m`, `every 2h`, or standard cron expressions like `0 9 * * *`.
+- **Change what "down" means.** By default the agent treats any non-2xx/3xx HTTP response as down. If you want to check for specific strings in the body (e.g. "Maintenance"), tell the agent in `AGENTS.md` and it will adapt.
+- **Add alerting.** Set a `deliver` target on the cron job (Discord, Slack, Telegram) — the agent will post the run summary there instead of just writing to `status-log.md`.
+
+## Recommended model
+
+`claude-haiku-4` works well — this is a simple tool-use task (HTTP GETs + a short summary). Haiku keeps costs low when the cron runs daily. The recommendation appears in the Configuration form; Scarf doesn't auto-switch your active model, so adjust via Settings if you'd like.
+
+## Uninstalling
+
+Right-click the project in the sidebar → **Uninstall Template…** (or click the shippingbox icon on the dashboard header). Scarf walks you through exactly what's about to be removed: template-installed files in the project dir, the `[tmpl:…]` cron job, and the Configuration values you entered (`config.json` + Keychain items for any secrets — though this template has none). User-created files (like `status-log.md`) are preserved.