From 683e8d382bdec0438643d26733010da1adc9da5c Mon Sep 17 00:00:00 2001
From: jupiterx0910 <242764434+jupiterx0910@users.noreply.github.com>
Date: Sat, 12 Sep 2026 17:13:30 +0800
Subject: [PATCH] docs(agents): reconcile Footprint Ladder rung 3 with the
 session-surface rule

Ladder rung 3 says a service-gated tool 'only appears when a prerequisite
is configured', while the SESSION-surface section below says check_fn must
not gate per-session surface. Both are correct but read as a contradiction
at the ladder; add the disambiguation inline with a pointer to the section.
---
 AGENTS.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index aecd44860c..930a2afc19 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -138,7 +138,10 @@ Choose the highest (least-footprint) rung that correctly solves the problem:
    `hermes <subcommand>` guided by a skill. Default for subscriptions, scheduled tasks,
    service setup (`hermes webhook`, `hermes cron`, `hermes tools`).
 3. **Service-gated tool (`check_fn`)** — needs structured params/returns AND only appears when
-   a prerequisite is configured (Home Assistant tools, memory-provider tools).
+   a prerequisite is configured (Home Assistant tools, memory-provider tools). This rung gates
+   reachability/opt-in process-wide; a capability that varies per SESSION (who is watching) is
+   a named toolset folded in by the toolset resolver, not a `check_fn` — see "Surface capability
+   is a property of the SESSION" below.
 4. **Plugin** — third-party/niche/user-specific; lives in `~/.hermes/plugins/` or a pip
    package, discovered at runtime.
 5. **MCP server (in the catalog)** — genuinely a tool but not core-fundamental. Zero permanent