ui: clarify agent endpoint guidance

TASKS.md

@@ -51,8 +51,9 @@ Progress:
   - `API Keys` page now has a mobile card layout instead of relying only on desktop table presentation
   - `Secrets` page now has a mobile card layout instead of relying only on desktop table presentation
   - `Usage` page now has a mobile card layout instead of relying only on desktop table presentation
+  - `Agents` page and modal now explain separate agent endpoints, next-step machine access, and stable slug expectations
 - pending:
-  - remaining `Agents` and `Settings` commercial UX polish
+  - remaining `Settings` and workspace commercial UX polish
 
 ## Planned
 

apps/ui/html/agents.html

@@ -168,6 +168,7 @@
       </div>
       <div class="empty-state-title" data-i18n="agents.empty.initial.title">No agents yet</div>
       <div class="empty-state-sub" x-text="emptyStateText()">Create your first agent to get a dedicated MCP endpoint with a curated set of tools.</div>
+      <div class="empty-state-sub" style="margin-top:8px;" x-text="tKey('agents.empty.initial.next_step')">After creation, issue separate machine-access keys for this endpoint on the API Keys page.</div>
       <button class="btn-new" @click="openCreate()" style="margin-top: 16px;">
         <svg width="13" height="13" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><path d="M8 3v10M3 8h10"/></svg>
         <span data-i18n="agents.new">New agent</span>
@@ -227,6 +228,7 @@
               <svg width="11" height="11" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><rect x="5" y="5" width="9" height="9" rx="1"/><path d="M5 5V3a1 1 0 011-1h7a1 1 0 011 1v7a1 1 0 01-1 1h-2"/></svg>
             </button>
           </div>
+          <div class="agent-card-date" style="margin-top:8px;" x-text="endpointHelpText(agent)"></div>
 
           <!-- Footer -->
           <div class="agent-card-footer">
@@ -296,6 +298,7 @@
           <div class="form-hint" x-show="form.slug">
             <span data-i18n="agents.drawer.endpoint">MCP endpoint</span>: <code style="font-family:monospace;font-size:11px;color:var(--accent)" x-text="'/mcp/v1/' + (localStorage.getItem('crank_workspace_slug') || 'default') + '/' + form.slug"></code>
           </div>
+          <div class="form-hint" data-i18n="agents.drawer.slug_hint">Keep the slug stable after clients start using this endpoint. Changing it changes the MCP path.</div>
         </div>
 
         <div class="form-group" style="margin-bottom: 14px;">

apps/ui/js/agents.js

@@ -446,6 +446,13 @@ document.addEventListener('alpine:init', function() {
         return '/mcp/v1/' + workspaceSlug + '/' + agent.slug;
       },
 
+      endpointHelpText(agent) {
+        return this.tfKey(
+          this.isCommunityBuild ? 'agents.card.endpoint_help_community' : 'agents.card.endpoint_help',
+          { count: agent.key_count || 0 }
+        );
+      },
+
       copyEndpoint(agent) {
         var endpoint = this.mcpEndpoint(agent);
         navigator.clipboard.writeText(endpoint).catch(function() {});

apps/ui/js/i18n.js

@@ -967,6 +967,7 @@ var TRANSLATIONS = {
     'agents.empty.initial.title': 'No agents yet',
     'agents.empty.initial.sub': 'Create your first agent to get a dedicated MCP endpoint with a curated set of tools.',
     'agents.empty.initial.sub_community': 'Create your first agent to get one dedicated MCP endpoint and its static machine-access keys for a focused toolset.',
+    'agents.empty.initial.next_step': 'After creation, issue separate machine-access keys for this endpoint on the API Keys page.',
     'agents.empty.search.title': 'No agents match "{query}"',
     'agents.empty.search.sub': 'Try a different search term.',
     'agents.card.tools': 'tools',
@@ -974,6 +975,8 @@ var TRANSLATIONS = {
     'agents.card.calls_today': 'calls today',
     'agents.card.created': 'Created {date}',
     'agents.card.copy_endpoint': 'Copy endpoint',
+    'agents.card.endpoint_help': 'Use this MCP endpoint in your client and manage its machine-access keys on the API Keys page.',
+    'agents.card.endpoint_help_community': 'Use this MCP endpoint in your client. Community keeps machine access on static agent keys managed on the API Keys page.',
     'agents.action.edit': 'Edit',
     'agents.action.archive': 'Archive',
     'agents.action.delete': 'Delete',
@@ -996,6 +999,7 @@ var TRANSLATIONS = {
     'agents.drawer.required': 'required',
     'agents.drawer.status': 'Status',
     'agents.drawer.endpoint': 'MCP endpoint',
+    'agents.drawer.slug_hint': 'Keep the slug stable after clients start using this endpoint. Changing it changes the MCP path.',
     'agents.drawer.placeholder.name': 'Customer Support',
     'agents.drawer.placeholder.slug': 'customer-support',
     'agents.drawer.placeholder.description': 'What does this agent do? What LLM or use-case is it for?',
@@ -2042,6 +2046,7 @@ var TRANSLATIONS = {
     'agents.empty.initial.title': 'Агентов пока нет',
     'agents.empty.initial.sub': 'Создайте первого агента, чтобы получить отдельный MCP endpoint с нужным набором инструментов.',
     'agents.empty.initial.sub_community': 'Создайте первого агента, чтобы получить один отдельный MCP endpoint и его статические машинные ключи для конкретного набора инструментов.',
+    'agents.empty.initial.next_step': 'После создания выпустите отдельные машинные ключи для этого endpoint на странице API Keys.',
     'agents.empty.search.title': 'Нет агентов по запросу "{query}"',
     'agents.empty.search.sub': 'Попробуйте другой поисковый запрос.',
     'agents.card.tools': 'инструментов',
@@ -2049,6 +2054,8 @@ var TRANSLATIONS = {
     'agents.card.calls_today': 'вызовов сегодня',
     'agents.card.created': 'Создан {date}',
     'agents.card.copy_endpoint': 'Скопировать endpoint',
+    'agents.card.endpoint_help': 'Используйте этот MCP endpoint в клиенте и управляйте его машинными ключами на странице API Keys.',
+    'agents.card.endpoint_help_community': 'Используйте этот MCP endpoint в клиенте. В Community машинный доступ держится на статических ключах агента со страницы API Keys.',
     'agents.action.edit': 'Редактировать',
     'agents.action.archive': 'Архивировать',
     'agents.action.delete': 'Удалить',
@@ -2071,6 +2078,7 @@ var TRANSLATIONS = {
     'agents.drawer.required': 'обязательно',
     'agents.drawer.status': 'Статус',
     'agents.drawer.endpoint': 'MCP endpoint',
+    'agents.drawer.slug_hint': 'Сохраняйте slug стабильным после подключения клиентов. Его изменение меняет MCP path.',
     'agents.drawer.placeholder.name': 'Customer Support',
     'agents.drawer.placeholder.slug': 'customer-support',
     'agents.drawer.placeholder.description': 'Что делает этот агент? Для какой LLM или сценария он нужен?',

apps/ui/tests/e2e/agents.spec.js

@@ -6,8 +6,12 @@ test('agents page shows demo cards and edit drawer opens', async ({ page }) => {
   await page.goto('/agents');
   await expect(page.locator('.page-heading')).toHaveText(localized('Agents', 'Агенты'));
   await expect(page.locator('.agents-info-callout')).toContainText(localized('static agent keys', 'статические ключи агента'));
+  await expect(page.locator('.agent-card-date').first()).toContainText(
+    localized('API Keys page', 'API Keys')
+  );
   await page.getByRole('button', { name: localized('New agent', 'Новый агент') }).click();
   await expect(page.locator('.drawer-title')).toHaveText(localized('New agent', 'Новый агент'));
   await expect(page.locator('.drawer-subtitle')).toContainText(localized('static agent-key boundary', 'статических ключах агента'));
+  await expect(page.locator('.form-hint')).toContainText(localized('Keep the slug stable', 'Сохраняйте slug стабильным'));
   await expect(page.locator('.drawer')).toContainText(/mcp/i);
 });