docs: how agents see Scarf projects (v2.3 AGENTS.md injection)

Project-Templates.md

@@ -221,6 +221,32 @@ The installer enforces these rules — a bundle that violates any of them is ref
 - **Bundle size capped:** 50 MB at the install layer, 5 MB at the catalog-submission layer.
 - **Install preview is load-bearing:** every file the installer will write appears in the sheet. There's no silent write path.
 
+## How the agent sees the project (v2.3+)
+
+When you click **New Chat** on a project's Sessions tab, Scarf does two things:
+
+1. Starts `hermes acp` with the project directory as the session's working directory.
+2. Writes a Scarf-managed block into `<project>/AGENTS.md` between `<!-- scarf-project:begin -->` and `<!-- scarf-project:end -->` markers, so Hermes's automatic context-file load picks up the project's identity.
+
+Hermes reads a context file from the session's cwd at startup, picking the first match in this priority order: `.hermes.md` → `HERMES.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`. Each is capped at 20 KB. Scarf's managed block contains:
+
+- Project name + directory
+- Dashboard and manifest paths
+- Template id + version (for template-installed projects)
+- Configuration field *names* (with type hints — `secret` fields marked as such, but **values never appear**)
+- Cron jobs attributed to the project via the `[tmpl:<id>] …` prefix
+- A reminder to preserve template-author content below the block
+
+**Safe around hand-edits.** Everything outside the markers is left byte-identical on every refresh. Template-author AGENTS.md content lives safely below the block.
+
+**Secret-safe.** Config values stored in the Keychain never appear — only field names. The block is safe to drop into any agent's context.
+
+**Bare projects.** If you add a plain directory to Scarf (via the `+` button) and start a chat in it, Scarf creates a minimal `AGENTS.md` containing only the managed block. The agent still has identity-level project awareness even without a template.
+
+**Known caveat.** If any parent directory of your project contains a `.hermes.md` or `HERMES.md` file, Hermes's priority order picks *those* up first and the project's AGENTS.md is shadowed. No fix in v2.3 — planned for v2.4 pending input on how to handle authored `.hermes.md` files.
+
+The service backing all of this is `ProjectAgentContextService` in the main Scarf repo. Template authors: leave the `<!-- scarf-project -->` region alone in your bundled `AGENTS.md`, put template-specific instructions below it.
+
 ## Troubleshooting
 
 **"The install sheet closes as soon as I click Continue on the Configure step."**