Complete agent directory references and skill version checks

documentation/src/content/docs/controls.mdx

@@ -9,7 +9,7 @@ import { controlPages } from '../../data/control-reference.mjs';
 
 Ask the agent for an outcome in ordinary language. It can use the controls below when its current permissions, platform, and connections allow them. These reference pages explain the exact tool names, inputs, results, and restrictions for people building integrations or checking how an action works.
 
-The gateway defines **108 controls**. The separate [skills-library service](/docs/controls/skills-library) defines **10 more**. A run receives an authorized subset; a tool appearing here does not mean it is enabled in every conversation. The library endpoint uses its own access tokens.
+The gateway defines **110 controls**. The separate [skills-library service](/docs/controls/skills-library) defines **10 more**. A run receives an authorized subset; a tool appearing here does not mean it is enabled in every conversation. The library endpoint uses its own access tokens.
 
 For practical workflows, browse the [feature directory](/docs/features). For deployment and conversation defaults, open [configuration](/docs/configuration). The [functionality map](/docs/functionality) connects the broader product areas to their guides.
 

documentation/src/content/docs/controls/conversation-settings.md

@@ -7,6 +7,28 @@ These controls are capability-bound to the current conversation, except the expl
 
 Persistent control changes require the current authorized human decision through the gateway approval path. Auto approval of engine tools does not approve these control-plane changes. The managed updater has an explicit Auto/Admin exception; restart has an Admin exception, described below. Read-only tools do not require that extra sign-off.
 
+## set_channel_agent_profile
+
+Describe or hide the current channel's specialist agent without changing its skills or access.
+
+| Argument | Required | Meaning and default |
+| --- | --- | --- |
+| `description` | No | Purpose, up to 600 characters. Empty clears the curated purpose. |
+| `examples` | No | Up to six example tasks, each up to 160 characters. Empty array clears them. |
+| `hidden` | No | Hide/unhide this agent in discovery. |
+
+**Authority:** Authenticated current-channel manager or admin with current gateway access.
+Channel-scoped and reversible; no second approval card. API/untrusted principals are refused.
+At least one field is required semantically; omitted fields remain unchanged.
+
+**Result:** Saved profile, immediately available to subsequent directory lookups. Without a
+curated purpose, platform purpose/topic supplies it. Announce the saved change in the reply.
+The audit records actor, channel and changed keys without descriptive content.
+
+**Restrictions:** Always this conversation; model arguments cannot target another channel.
+Publishing a purpose never widens private channel visibility. See
+[search_agents](/docs/controls/knowledge-and-instructions/#search_agents).
+
 ## set_channel_admin_mode
 
 **Required:** `enabled` (boolean). **Optional:** none. **Authority:** gateway admin, with control approval.

documentation/src/content/docs/controls/knowledge-and-instructions.md

@@ -3,7 +3,37 @@ title: Memory and instruction controls
 description: Search, read, and update channel knowledge and request standing rules.
 ---
 
-Memory stores declarative facts for later retrieval. Instructions govern behavior. These four controls use the current conversation only; the run capability does not expose another channel’s knowledge.
+Memory stores declarative facts for later retrieval. Instructions govern behavior. Memory and
+instruction controls use the current conversation only. Agent discovery returns a separately
+authorized directory projection; it never reads another conversation's memory or history.
+
+## search_agents
+
+Find an existing specialist channel agent by purpose, example tasks or active shared skills.
+
+| Argument | Required | Meaning and default |
+| --- | --- | --- |
+| `query` | No | Up to 500 characters; empty lists eligible agents. |
+| `limit` | No | Integer 1–50; default 20. |
+| `offset` | No | Integer 0–10000; default 0. Use the previous page's `nextOffset`. |
+
+**Authority and scope:** Authenticated conversation member with current gateway access. Live
+platform checks protect the requester and reply audience; API/untrusted principals are refused.
+Slack currently supplies the metadata/membership provider. Unsupported or offline providers fail
+closed. DMs/group DMs never appear as agents; personal skills never contribute. Private targets
+cannot appear in public/shared sources. Other results require the complete current source roster
+to belong to the target; a real one-to-one bot DM uses the requester's membership.
+
+**Result:** `agents`, `returned`, `hasMore` and `nextOffset`. Entries include the channel link,
+purpose, examples, current shared skill summaries and platform verification time. Summaries
+prioritize query matches; `skillsTotal` and `skillsTruncated` identify shortened skill lists.
+Pages are bounded to 64 KiB. Continue with the same query and returned offset.
+
+**Restrictions:** No messages, invitations, delegated runs or file transfers. Cached metadata
+narrows search but never authorizes a result. Channel metadata reconciles on startup and nightly
+at 03:00 host-local time without an engine turn; platform-purpose keyword updates may wait for
+that refresh. Curated profiles and shared skill changes participate immediately. See
+[set_channel_agent_profile](/docs/controls/conversation-settings/#set_channel_agent_profile).
 
 ## search_channel_memory
 

documentation/src/content/docs/features/skills.md

@@ -35,6 +35,18 @@ Catalog revisions preserve the exact package files and support history and rollb
 
 Lean removes optional skill grants. Related: [skill sources](/docs/configuration/skill-sources), [plugins](/docs/features/plugins), and the [complete skills reference](/docs/skills).
 
+## Find an existing specialist agent
+
+Ask “Which agent can help me create a presentation?” or “List the agents and their skills.” The
+gateway guide checks `search_agents` and recommends a relevant channel with its purpose, link and
+active shared skills. It continues helping here if preferred; discovery does not send your request
+elsewhere. Managers can describe or hide their own channel with `set_channel_agent_profile`.
+
+The directory protects everyone reading the reply as well as the requester. Private specialists
+are not advertised to public/shared channels, and personal skills stay private. Metadata refreshes
+nightly at 03:00 host-local time; skill grants resolve at lookup. See the
+[directory control reference](/docs/controls/knowledge-and-instructions/#search_agents).
+
 ## Explore the skills handbook
 
 - [Discovery and inspection](/docs/features/skill-discovery)

test/channelgate-skill.test.js

@@ -25,7 +25,7 @@ test("the ChannelGate skill is a valid, fully routed package", async () => {
   const { data, body } = parseFrontmatter(manifest);
 
   assert.equal(data.name, "channelgate");
-  assert.equal(data.metadata.version, "3.2.0");
+  assert.equal(data.metadata.version, "3.3.0");
   assert.match(data.description, /device-login links/);
   assert.match(data.description, /Do not\s+use for ordinary work/);
   assert.match(data.description, /server sizing and hosting-provider choice/);