docs: clarify Polygon auth and API contracts

site/templates/index.html

@@ -23,7 +23,7 @@
             {% endfor %}
             <span class="sep">·</span>
             {% endif %}
-            <a href="/swagger" class="swagger-link">📋 Swagger</a>
+            <a href="{{ swagger_url }}" class="swagger-link">📋 Swagger</a>
             <span class="sep">·</span>
             <span class="dot dot-green"></span>
             <span class="status-text">Работает</span>
@@ -112,8 +112,12 @@ curl -s -X POST {{ endpoint }}/{% if stands_list|length > 1 %}{{ current_stand }
                 <hr style="margin: 20px 0; border: none; border-top: 1px solid var(--border);">
 
                 <h3 class="h4">🛠 Управление полигоном (служебные эндпоинты)</h3>
-                <p>Если на сервере задан <code>MOCK_AUTH_TOKEN</code>, для запросов к <code>/_mock/*</code> добавьте
-                    заголовок <code>-H "X-Mock-Auth: &lt;token&gt;"</code>.</p>
+                <p><strong>Авторизация служебных запросов:</strong> администратор задаёт <code>MOCK_AUTH_TOKEN</code>
+                    в переменных окружения сервиса. Сам токен здесь не показывается. Если защита включена, в Swagger
+                    нажмите <strong>Authorize</strong>, вставьте токен в поле <code>X-Mock-Auth</code> и подтвердите
+                    кнопкой <strong>Authorize</strong>. Для curl добавьте к запросу
+                    <code>-H "X-Mock-Auth: &lt;token&gt;"</code>. Если переменная не задана, токен не нужен.
+                </p>
 
                 <div class="feature-grid">
                     <div class="feature-item">

site/templates/swagger.html

@@ -86,11 +86,30 @@
         .swagger-ui .info .title {
             font-family: system-ui, -apple-system, sans-serif;
         }
+
+        .auth-help {
+            max-width: 1460px;
+            margin: 16px auto;
+            padding: 12px 16px;
+            background: #fff;
+            border: 1px solid #d1d5db;
+            color: #374151;
+            font: 14px/1.5 system-ui, sans-serif;
+        }
     </style>
 </head>
 
 <body>
 
+    <aside class="auth-help">
+        <strong>Токен для служебных запросов</strong>
+        <p>Если администратор настроил <code>MOCK_AUTH_TOKEN</code> в переменных окружения сервиса, нажмите
+            <strong>Authorize</strong> в Swagger, вставьте выданное вам значение в поле <code>X-Mock-Auth</code>
+            (Value) и подтвердите кнопкой <strong>Authorize</strong>. Токен выдаёт администратор; Swagger его не
+            показывает. Если защита не включена, авторизация не требуется.
+        </p>
+    </aside>
+
     <div id="swagger-ui"></div>
 
     <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js" crossorigin></script>
@@ -123,12 +142,12 @@
                 if (link) {
                     link.innerHTML = '<img class="logo" src="{{ url_for("static", filename="logo.svg") }}" alt="Nubes">' +
                         '<span class="version-badge">polygon v{{ version }}</span>';
-                    link.href = "/";
+                    link.href = "{{ home_url }}";
                 }
                 // Добавляем ссылку «← На главную»
                 const navLink = document.createElement("a");
                 navLink.className = "nav-link";
-                navLink.href = "/";
+                navLink.href = "{{ home_url }}";
                 navLink.textContent = "← На главную";
                 topbar.appendChild(navLink);
             }