Give the semantic index its own Administration menu entry

The index rebuild control was buried at the bottom of the Company settings
page, where it was hard to find. Move it to a dedicated "Semantic index" page
with its own sidebar entry under Administration, next to "Assistant feedback".

- New SemanticIndexAdminView (GET, system.config.read) renders the status card
  (indexed/total, last updated, embedding model) and the rebuild button.
- Sidebar link shown when AI_ASSISTANT_ENABLED and the user has
  system.config.read; gated icon bi-stars.
- Rebuild POST redirects back to the new page; card removed from Company
  settings (and its context reverted).
- French translations, a page render + permission test, and docs/CHANGELOG
  updated to point at Administration -> Semantic index.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: claude

CHANGELOG.md

@@ -11,7 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Ask Cairn: OpenAI and OpenAI-compatible providers**: the assistant gains an `openai` backend (`AI_ASSISTANT_PROVIDER=openai`) that targets OpenAI (ChatGPT, e.g. `gpt-4o-mini`) out of the box and, via `AI_ASSISTANT_BASE_URL`, any other endpoint implementing the OpenAI `/chat/completions` and `/embeddings` API (vLLM, LiteLLM, LocalAI, Together, Groq...). The shared request/response handling was extracted into a generic `OpenAICompatibleClient`; the existing `MistralClient` is now a thin subclass of it (Mistral already exposes an OpenAI-compatible API), so behaviour is unchanged for Mistral users. `AI_ASSISTANT_BASE_URL` now defaults to empty and each provider falls back to its own endpoint (`mistral` -> `api.mistral.ai`, `openai` -> `api.openai.com`, `anthropic` -> `api.anthropic.com`); set it only to target a custom gateway.
 - **Ask Cairn: Claude (Anthropic) provider**: a native `anthropic` backend (`AI_ASSISTANT_PROVIDER=anthropic`) talks to Claude through the Messages API (`POST /v1/messages`, `x-api-key` header, top-level `system`, `content` block list) - Claude is not OpenAI-compatible, so it has its own client. Routing uses forced tool use (a `plan` tool whose `input_schema` is the routing schema) and no `temperature`/`thinking` is sent (both 400 on the current Opus family). Set `AI_ASSISTANT_MODEL` to a Claude model id (e.g. `claude-opus-4-8`). Semantic search is not available with this provider, since Anthropic has no embeddings API.
-- **Ask Cairn: automatic semantic index maintenance**: the requirement semantic index now stays fresh without a manual command. A `post_delete` signal prunes a deleted requirement's embedding immediately (no provider call); the index is refreshed in a guarded background thread when a server process starts (when `AI_ASSISTANT_SEMANTIC_ENABLED`); and the Company settings page gains an index-status panel (indexed / total requirements, last updated, embedding model) with an **"Update the index now"** button (gated by `system.config.update`) that triggers a background rebuild. Embedding stays off the request path - requirement saves never embed inline; the documented daily `rebuild_semantic_index` cron remains the self-healing backstop. The rebuild logic was extracted into `assistant.semantic.rebuild_index` / `rebuild_index_async` (cache-locked to dedupe overlapping triggers) and reused by the management command.
+- **Ask Cairn: automatic semantic index maintenance**: the requirement semantic index now stays fresh without a manual command. A `post_delete` signal prunes a deleted requirement's embedding immediately (no provider call); the index is refreshed in a guarded background thread when a server process starts (when `AI_ASSISTANT_SEMANTIC_ENABLED`); and a dedicated **Administration -> Semantic index** page shows an index-status panel (indexed / total requirements, last updated, embedding model) with an **"Update the index now"** button (gated by `system.config.update`) that triggers a background rebuild. Embedding stays off the request path - requirement saves never embed inline; the documented daily `rebuild_semantic_index` cron remains the self-healing backstop. The rebuild logic was extracted into `assistant.semantic.rebuild_index` / `rebuild_index_async` (cache-locked to dedupe overlapping triggers) and reused by the management command.
 
 ## [0.27.1] - 2026-06-14
 

accounts/templates/accounts/company_settings.html

@@ -85,49 +85,6 @@ <h2>{% trans "Company settings" %}</h2>
     </div>
   </div>
 </form>
-
-{# ── Ask Cairn: semantic search index ──────────────── #}
-<div class="row">
-  <div class="col-lg-8">
-    <div class="card mb-4">
-      <div class="card-header"><h6 class="mb-0"><i class="bi bi-stars me-2" style="color:var(--accent)"></i>{% trans "Semantic search index" %}</h6></div>
-      <div class="card-body">
-        {% if not semantic.enabled %}
-        <p class="text-muted mb-0">{% trans "Semantic search is disabled." %} {% trans "Enable it with the AI_ASSISTANT_SEMANTIC_ENABLED setting to let topic questions match requirements across languages." %}</p>
-        {% elif not semantic.embeddings_supported %}
-        <p class="text-muted mb-0"><i class="bi bi-exclamation-triangle me-1"></i>{% trans "The current AI provider has no embeddings, so the semantic index cannot be built. Use the Mistral, OpenAI or Ollama provider to index requirements." %}</p>
-        {% else %}
-        <div class="row g-3 mb-3">
-          <div class="col-sm-4">
-            <div class="form-label mb-0">{% trans "Indexed requirements" %}</div>
-            <div style="font-weight:600;font-size:1.0625rem">{{ semantic.indexed }} / {{ semantic.total }}</div>
-          </div>
-          <div class="col-sm-4">
-            <div class="form-label mb-0">{% trans "Last updated" %}</div>
-            <div style="font-weight:600;font-size:1.0625rem">{% if semantic.last_updated %}{{ semantic.last_updated|date:"SHORT_DATETIME_FORMAT" }}{% else %}{% trans "Never" %}{% endif %}</div>
-          </div>
-          <div class="col-sm-4">
-            <div class="form-label mb-0">{% trans "Embedding model" %}</div>
-            <div style="font-weight:600;font-size:1.0625rem">{{ semantic.embed_model }}</div>
-          </div>
-        </div>
-        {% if semantic.running %}
-        <p class="text-muted mb-3"><span class="spinner-border spinner-border-sm me-2"></span>{% trans "An update is currently running." %}</p>
-        {% endif %}
-        <p class="text-muted small mb-3">{% trans "New and edited requirements are picked up automatically (daily and at startup); use this button to refresh immediately, e.g. after a bulk import." %}</p>
-        {% if can_edit %}
-        <form method="post" action="{% url 'assistant:rebuild-semantic-index' %}">
-          {% csrf_token %}
-          <button type="submit" class="btn btn-outline-primary"{% if semantic.running %} disabled{% endif %}>
-            <i class="bi bi-arrow-repeat me-1"></i>{% trans "Update the index now" %}
-          </button>
-        </form>
-        {% endif %}
-        {% endif %}
-      </div>
-    </div>
-  </div>
-</div>
 {% endblock %}
 
 {% block extra_js %}

accounts/views.py

@@ -162,21 +162,11 @@ def post(self, request):
 class CompanySettingsView(LoginRequiredMixin, PermissionRequiredMixin, View):
     permission_required = "system.config.read"
 
-    def _context(self, form, instance, can_edit):
-        from assistant.semantic import index_status
-
-        return {
-            "form": form,
-            "company": instance,
-            "can_edit": can_edit,
-            "semantic": index_status(),
-        }
-
     def get(self, request):
         instance = CompanySettings.get()
         form = CompanySettingsForm(instance=instance)
         can_edit = request.user.is_superuser or request.user.has_perm("system.config.update")
-        return render(request, "accounts/company_settings.html", self._context(form, instance, can_edit))
+        return render(request, "accounts/company_settings.html", {"form": form, "company": instance, "can_edit": can_edit})
 
     def post(self, request):
         can_edit = request.user.is_superuser or request.user.has_perm("system.config.update")
@@ -189,7 +179,7 @@ def post(self, request):
             form.save()
             messages.success(request, _("Company settings updated."))
             return redirect("accounts:company-settings")
-        return render(request, "accounts/company_settings.html", self._context(form, instance, can_edit))
+        return render(request, "accounts/company_settings.html", {"form": form, "company": instance, "can_edit": can_edit})
 
 
 # ── Users ───────────────────────────────────────────────────

assistant/templates/assistant/semantic_index.html

@@ -0,0 +1,50 @@
+{% extends "base.html" %}
+{% load ui %}
+{% load i18n %}
+{% block title %}{% trans "Semantic index - Cairn" %}{% endblock %}
+
+{% block content %}
+{% page_header _("Semantic index") eyebrow=_("Administration") accent="accounts" %}{% endpage_header %}
+
+<div class="row">
+  <div class="col-lg-8">
+    <div class="card mb-4">
+      <div class="card-header"><h6 class="mb-0"><i class="bi bi-stars me-2" style="color:var(--accent)"></i>{% trans "Semantic search index" %}</h6></div>
+      <div class="card-body">
+        {% if not semantic.enabled %}
+        <p class="text-muted mb-0">{% trans "Semantic search is disabled." %} {% trans "Enable it with the AI_ASSISTANT_SEMANTIC_ENABLED setting to let topic questions match requirements across languages." %}</p>
+        {% elif not semantic.embeddings_supported %}
+        <p class="text-muted mb-0"><i class="bi bi-exclamation-triangle me-1"></i>{% trans "The current AI provider has no embeddings, so the semantic index cannot be built. Use the Mistral, OpenAI or Ollama provider to index requirements." %}</p>
+        {% else %}
+        <div class="row g-3 mb-3">
+          <div class="col-sm-4">
+            <div class="form-label mb-0">{% trans "Indexed requirements" %}</div>
+            <div style="font-weight:600;font-size:1.0625rem">{{ semantic.indexed }} / {{ semantic.total }}</div>
+          </div>
+          <div class="col-sm-4">
+            <div class="form-label mb-0">{% trans "Last updated" %}</div>
+            <div style="font-weight:600;font-size:1.0625rem">{% if semantic.last_updated %}{{ semantic.last_updated|date:"SHORT_DATETIME_FORMAT" }}{% else %}{% trans "Never" %}{% endif %}</div>
+          </div>
+          <div class="col-sm-4">
+            <div class="form-label mb-0">{% trans "Embedding model" %}</div>
+            <div style="font-weight:600;font-size:1.0625rem">{{ semantic.embed_model }}</div>
+          </div>
+        </div>
+        {% if semantic.running %}
+        <p class="text-muted mb-3"><span class="spinner-border spinner-border-sm me-2"></span>{% trans "An update is currently running." %}</p>
+        {% endif %}
+        <p class="text-muted small mb-3">{% trans "New and edited requirements are picked up automatically (daily and at startup); use this button to refresh immediately, e.g. after a bulk import." %}</p>
+        {% if can_edit %}
+        <form method="post" action="{% url 'assistant:rebuild-semantic-index' %}">
+          {% csrf_token %}
+          <button type="submit" class="btn btn-outline-primary"{% if semantic.running %} disabled{% endif %}>
+            <i class="bi bi-arrow-repeat me-1"></i>{% trans "Update the index now" %}
+          </button>
+        </form>
+        {% endif %}
+        {% endif %}
+      </div>
+    </div>
+  </div>
+</div>
+{% endblock %}

assistant/tests/test_semantic_maintenance.py

@@ -141,6 +141,26 @@ def test_rebuild_view_reports_disabled(client, monkeypatch):
     assert "called" not in started
 
 
+@pytest.mark.django_db
+@override_settings(AI_ASSISTANT_SEMANTIC_ENABLED=True)
+def test_semantic_index_admin_page_requires_permission(client):
+    user = UserFactory()  # no system.config.read
+    client.force_login(user)
+    resp = client.get(reverse("assistant:semantic-index"))
+    assert resp.status_code == 403
+
+
+@pytest.mark.django_db
+@override_settings(AI_ASSISTANT_SEMANTIC_ENABLED=True, AI_ASSISTANT_PROVIDER="mistral")
+def test_semantic_index_admin_page_renders_status(client):
+    user = UserFactory()
+    _grant(user, "system.config.read")
+    client.force_login(user)
+    resp = client.get(reverse("assistant:semantic-index"))
+    assert resp.status_code == 200
+    assert resp.context["semantic"]["enabled"] is True
+
+
 @pytest.mark.django_db
 @override_settings(AI_ASSISTANT_SEMANTIC_ENABLED=True)
 def test_rebuild_view_starts_rebuild_with_permission(client, monkeypatch):

assistant/urls.py

@@ -10,5 +10,6 @@
     path("feedback/list/", views.AssistantFeedbackListView.as_view(), name="feedback-list"),
     path("feedback/export/", views.AssistantFeedbackExportView.as_view(), name="feedback-export"),
     path("feedback/<uuid:pk>/resolve/", views.AssistantFeedbackResolveView.as_view(), name="feedback-resolve"),
+    path("semantic-index/", views.SemanticIndexAdminView.as_view(), name="semantic-index"),
     path("semantic-index/rebuild/", views.RebuildSemanticIndexView.as_view(), name="rebuild-semantic-index"),
 ]

assistant/views.py

@@ -262,12 +262,35 @@ def _safe_query(self, request):
         return f"?{encoded}" if encoded else ""
 
 
+class SemanticIndexAdminView(LoginRequiredMixin, PermissionRequiredMixin, View):
+    """In-app Administration page for the requirement semantic index.
+
+    Shows index status (indexed / total requirements, last updated, embedding
+    model) and the on-demand rebuild button.
+    """
+
+    permission_required = "system.config.read"
+    http_method_names = ["get"]
+
+    def get(self, request):
+        from assistant.semantic import index_status
+
+        can_edit = request.user.is_superuser or request.user.has_perm(
+            "system.config.update"
+        )
+        return render(
+            request,
+            "assistant/semantic_index.html",
+            {"semantic": index_status(), "can_edit": can_edit},
+        )
+
+
 class RebuildSemanticIndexView(LoginRequiredMixin, View):
     """Trigger an on-demand background refresh of the requirement index.
 
-    Lives on the Company settings page (in-app Administration), gated by the
-    same permission as other system configuration changes. The rebuild runs in
-    a guarded background thread so the request returns immediately.
+    Posted from the Semantic index admin page, gated by the same permission as
+    other system configuration changes. The rebuild runs in a guarded background
+    thread so the request returns immediately.
     """
 
     http_method_names = ["post"]
@@ -278,10 +301,10 @@ def post(self, request):
             or request.user.has_perm("system.config.update")
         ):
             messages.error(request, _("You do not have the required permissions."))
-            return redirect("accounts:company-settings")
+            return redirect("assistant:semantic-index")
         if not settings.AI_ASSISTANT_SEMANTIC_ENABLED:
             messages.error(request, _("Semantic search is disabled."))
-            return redirect("accounts:company-settings")
+            return redirect("assistant:semantic-index")
 
         from assistant.semantic import rebuild_index_async
 
@@ -292,4 +315,4 @@ def post(self, request):
             )
         else:
             messages.info(request, _("A semantic index update is already running."))
-        return redirect("accounts:company-settings")
+        return redirect("assistant:semantic-index")

docs/installation.md

@@ -140,7 +140,7 @@ Both accept `--dry-run` to preview changes. A typical host cron entry:
 20 2 * * * cd /opt/cairn && docker compose exec -T web python manage.py mark_overdue_treatment_plans
 ```
 
-If the **semantic search** of the Ask Cairn assistant is enabled (`AI_ASSISTANT_SEMANTIC_ENABLED`), schedule the index refresh the same way. The command is idempotent (it only re-embeds changed requirements and prunes deleted ones), so a daily run is cheap. The index is also refreshed automatically when the app starts, a deleted requirement is pruned immediately, and an administrator can force a refresh from the Company settings page; the daily cron is the reliable, self-healing backstop.
+If the **semantic search** of the Ask Cairn assistant is enabled (`AI_ASSISTANT_SEMANTIC_ENABLED`), schedule the index refresh the same way. The command is idempotent (it only re-embeds changed requirements and prunes deleted ones), so a daily run is cheap. The index is also refreshed automatically when the app starts, a deleted requirement is pruned immediately, and an administrator can force a refresh from the **Administration -> Semantic index** page; the daily cron is the reliable, self-healing backstop.
 
 ```cron
 25 2 * * * cd /opt/cairn && docker compose exec -T web python manage.py rebuild_semantic_index

docs/modules/assistant/README.md

@@ -206,7 +206,7 @@ The index drifts as requirements are created, edited or deleted, so it is refres
 
 - **On delete (immediate)**: a `post_delete` signal on `Requirement` (`assistant/signals.py`, wired from `AssistantConfig.ready()`) prunes the requirement's `SemanticIndex` row. This is a network-free DB delete, safe even when semantic search is disabled.
 - **On startup**: when a server process boots (uvicorn / `runserver`) with the feature on, `AssistantConfig.ready()` launches a guarded background thread that runs the rebuild once (skipped for management commands like `migrate`/`test`, so the work never blocks boot and a slow provider can't wedge startup).
-- **On demand (admin)**: the Company settings page (in-app Administration, gated by `system.config.update`) shows index status (indexed / total requirements, last updated, embedding model) and an **"Update the index now"** button that triggers a background rebuild (`assistant:rebuild-semantic-index`). The card warns when the active provider has no embeddings (e.g. `anthropic`).
+- **On demand (admin)**: a dedicated **Administration -> Semantic index** page (`assistant:semantic-index`, sidebar link shown when `AI_ASSISTANT_ENABLED` and the user has `system.config.read`) shows index status (indexed / total requirements, last updated, embedding model) and an **"Update the index now"** button (gated by `system.config.update`) that triggers a background rebuild. It warns when the active provider has no embeddings (e.g. `anthropic`).
 - **Scheduled (recommended backstop)**: run `manage.py rebuild_semantic_index` from cron (see [installation.md](../../installation.md)). It is the reliable, self-healing mechanism - it catches anything the others missed (e.g. an edit that no rebuild has run for yet, or an embed that failed transiently).
 
 A cache lock (`assistant.semantic.rebuild_index_async`) dedupes overlapping triggers (startup + button + a double click), and the startup/admin rebuilds run in daemon threads that close their own DB connections. New and edited requirements become searchable at the next rebuild (startup, daily cron, or the admin button) - lexical search covers them immediately in the meantime.

locale/fr/LC_MESSAGES/django.po

@@ -9905,3 +9905,9 @@ msgstr "La mise à jour de l'index sémantique a démarré ; elle s'exécute en
 
 msgid "A semantic index update is already running."
 msgstr "Une mise à jour de l'index sémantique est déjà en cours."
+
+msgid "Semantic index"
+msgstr "Index sémantique"
+
+msgid "Semantic index - Cairn"
+msgstr "Index sémantique - Cairn"