Skip to content

Self-hosted project management for devs and their clients: tickets, time tracking, docs and meetings, with an AI assistant that cites its sources. AGPL-3.0.

docs: map the glossary reader, the terms endpoint and get_glossary

Guido Boyke342bf6487429
diff --git a/CLAUDE.md b/CLAUDE.md
index b6cb7df..c8470bd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -831,6 +831,9 @@ feature by feature):
without decoding, so the action still applies its permissions and input validation.
Existing JSON fingerprints stay unchanged. Every write route must be `idempotent`
(`spec/architecture/api_v1_writes_idempotent_guard_spec.rb`).
+* ⚠️ **A `rescue_from` handler runs outside the token owner's language**: the action's
+ `around_action :with_token_owner_locale` has ended by then. A text built at the raise is right;
+ one built in the handler needs `with_token_owner_locale { ... }` (`TermsController#glossary_forbidden`).
* **`GET /api/v1/me`** names `api_version` and `capabilities` from `Api::V1::Capabilities`,
pinned against the routes both ways (`spec/requests/api/v1/capabilities_spec.rb`): a new
endpoint adds its line there. Additive changes bump the minor.
@@ -938,6 +941,26 @@ by 50, at most 100; a value outside is a 400, never cut. Guards:
`spec/requests/api/v1/people_spec.rb`, `spec/requests/api/mcp_people_spec.rb`,
`spec/requests/api/people_parity_spec.rb` (REST and MCP answer the same rows).
+`GET /api/v1/organisations/:organisation_id/terms` (K4c, 2026-11-06, API 1.11.0, capability
+`terms.list`) and the MCP tool `get_glossary` (MCP 0.18.0, `:mcp` only) read an organisation's
+glossary through `Glossary::Lookup`, for a device that hands the terms to its speech recognition
+and replaces learnt wrong forms before it sends. Only what works: confirmed terms, and at them the
+heard forms of `TermCorrection.effective` (a confirmed term without one has an empty `heard`),
+grouped by the compared form with the spelling last heard, `count` the sum of `replaced_count`,
+`speakers` as refs of the people directory. The glossary right of the token's owner
+(`GlossaryPolicy`, an active membership) or 403 with `reason: glossary_forbidden` (MCP `refused`,
+the same reason and text). Unlike the people directory, a token limited to some projects is
+answered: every term, the heard forms of its projects only, and a form without a project only for
+a token that reaches every project. An organisation outside the token, a foreign, a missing and a
+malformed one answer the same 404 (MCP `not_found`, also for a malformed id); `project_id` puts the
+forms of its project first, outside the organisation or the token the same 404. `people` and
+`speakers` only with the people right (`PersonPolicy`), named as the directory names them to the
+reader; whom it does not list counts in `count` alone. No meeting, place or corrector in the
+answer. Pages by 50, at most 100, a value outside is a 400. Guards:
+`spec/requests/api/v1/terms_spec.rb`, `spec/requests/api/mcp_glossary_spec.rb`,
+`spec/requests/api/glossary_parity_spec.rb` (REST and MCP answer the same),
+`spec/services/glossary/lookup_spec.rb`.
+
`POST /api/v1/tickets/:ticket_id/posts` (REST R3a) writes by the rule the MCP tool
`post_comment` writes by, `Posts::Comment`, through `Actors::SavePost` like the web form:
`post[format]` `html` (the default, the body stored as sent) or `plain` (literal text through
diff --git a/app/models/CLAUDE.md b/app/models/CLAUDE.md
index eca2aed..5258a05 100644
--- a/app/models/CLAUDE.md
+++ b/app/models/CLAUDE.md
@@ -1,4 +1,4 @@
-# Karte: app/models (Stand: 2026-11-05)
+# Karte: app/models (Stand: 2026-11-06)
~80 Modelle liegen flach in diesem Verzeichnis; Namespaces existieren nur für `admin/`,
`knowledge/`, `overview/`, `smart_folders/`, `time_sessions/`, `user/`. Die Domänen-Zugehörigkeit ist am
@@ -121,7 +121,8 @@ Verzeichnis-Layout nicht ablesbar — diese Karte gruppiert sie:
`proposed`/`confirmed`, Check `term_corrections_status_known`, Altbestand `confirmed`). Ohne
`manage_glossary` entsteht sie als Vorschlag, auch an einem bestätigten Begriff. Wirksam ist
nur `TermCorrection.effective` (bestätigte Form an bestätigtem Begriff): K4c und das Gerät lesen
- dort, nie `term_corrections` direkt. ⚠️ `Meeting#invalidate_stale_summary` hat GENAU EINE
+ dort, nie `term_corrections` direkt. K4c (06.11.2026): dieser Leser ist `Glossary::Lookup`
+ (REST `/terms` und MCP `get_glossary`, Karte `app/services/CLAUDE.md`). ⚠️ `Meeting#invalidate_stale_summary` hat GENAU EINE
Ausnahme: `keep_summary_for_next_save!` (eine Speicherung, eine Instanz), gesetzt nur von
`Actors::SaveMeeting` mit `keep_summary: true`, das nur `Actors::CorrectMeetingTerm` übergibt
(Wächter `spec/architecture/meeting_summary_exception_guard_spec.rb`). Nicht über
diff --git a/app/services/CLAUDE.md b/app/services/CLAUDE.md
index 63af4aa..0c6eb69 100644
--- a/app/services/CLAUDE.md
+++ b/app/services/CLAUDE.md
@@ -1,4 +1,4 @@
-# Karte: app/services (Stand: 2026-11-05)
+# Karte: app/services (Stand: 2026-11-06)
**Entry-Point-Konvention für NEUE Services: `Klass.call(**kwargs)`** (Klassenmethode; eine
Instanz-`#call`-Implementierung dahinter ist erlaubt). Pflicht: mindestens 1 Kommentarzeile
@@ -14,7 +14,7 @@ Ausgenommene Subtrees mit eigenem Vertrag: `actors/`, `lalabase/tools/`).
Einzel-`update!` ohne Side-Effects bleibt im Controller.
* An actor writes and checks no rights. Exceptions lock first and authorize again under the lock (`AcceptTicketSuggestion`, `StartTicketSuggestionRun`, `CorrectMeetingTerm`).
-* Finding belongs to one object per domain (`Tickets::ReadableForToken`, `Tickets::RelationAccess`, `People::Lookup`); they share the question, not code. Where `nil` would drop a limit, the keyword is required.
+* Finding belongs to one object per domain (`Tickets::ReadableForToken`, `Tickets::RelationAccess`, `People::Lookup`, `Glossary::Lookup`); they share the question, not code. Where `nil` would drop a limit, the keyword is required.
* The policy decides yes or no.
* The caller words the answer (status, text, 404 form).
* A guard holds where a mistake discloses data (`ticket_token_lookup_guard_spec.rb`, `ticket_relation_actor_callers_guard_spec.rb`).
@@ -208,6 +208,15 @@ Verzeichnis-Übersicht (Auswahl):
einer eigenen Marke für JEDEN Treffer unverändert bleibt (`#everywhere?`, Runde 2): ein Treffer
im Link-Ziel lässt nur „nur hier“. `term_correction_dialog.rb`
ist, was der Dialog zeigt (Stelle, Zahl, Sprecher, Digest), geteilt von `new`, `count`, `create`.
+* `glossary/` — `term_lock.rb` (die Sperr-Reihenfolge jedes Glossar-Writes, siehe `actors/`) und
+ `lookup.rb` (`Glossary::Lookup`, K4c, 06.11.2026), das EINE Lesen des Glossars einer Organisation
+ für `GET /api/v1/organisations/:id/terms` und das MCP-Werkzeug `get_glossary`: Recht
+ (`#allowed?`, von `#read` noch einmal gefragt: `Refused`), `.for_token` (eine Organisation in
+ Reichweite, ihre Projekte als Grenze der gehörten Formen; nil für außerhalb, fehlend, kaputt), nur
+ Wirksames (bestätigte Begriffe, `TermCorrection.effective`), `project_id` nach vorn (`NotFound`
+ außerhalb), Sprecher nur mit dem Personenrecht über `People::Directory#entry_for_participant`,
+ Seiten (`InvalidArgument`). Setzt den Mandanten selbst. Eine neue Regel dieser Antwort gehört
+ hierher, nicht in eine der beiden Türen.
* `people/` — `directory.rb`, das Lese-Objekt der Personenliste (seit 26.10.2026): Mitglieder
über `MembershipPolicy::Scope` (dieselbe Reichweite wie die Mitgliederseite), dazu die
Zeilen ohne aktives Mitglied als Kontakte; Suche in Ruby über `PersonName.normalize`.
diff --git a/app/services/lalabase/CLAUDE.md b/app/services/lalabase/CLAUDE.md
index f6ebd53..1d04cc6 100644
--- a/app/services/lalabase/CLAUDE.md
+++ b/app/services/lalabase/CLAUDE.md
@@ -1,4 +1,4 @@
-# Karte: app/services/lalabase (Stand: 2026-11-03)
+# Karte: app/services/lalabase (Stand: 2026-11-06)
AI/RAG-Domäne (Produktname „Lalabase"): alles rund um LLM-Aufrufe, Embeddings und
Codebase-Verständnis.
@@ -41,6 +41,14 @@ Codebase-Verständnis.
each part's first page is a third of a page, so the three stay within one; `part` and
`offset` read on, `next_offset` is null at the end. Offsets count code points, as Ruby's
String does; a page may end inside a grapheme cluster, which the next one continues.
+ `get_glossary` (K4c, MCP 0.18.0, `:mcp` only, the last tool, no assistant twin) reads an
+ organisation's glossary through `Glossary::Lookup`, the reader of
+ `GET /api/v1/organisations/:id/terms`. `scope_mode :token`; `Glossary::Lookup.for_token` is its
+ gate: an organisation outside the token, a foreign, a missing and a malformed id are all
+ `not_found`, as REST's one 404 (not `invalid_input` like the people twins: one reader, one
+ reading of the id). Then the tenant, the glossary right (`refused`, reason `glossary_forbidden`,
+ REST's text) and `authorize!`. `project_id` is its own argument (it reorders, it does not narrow),
+ so `project_filter?` stays false; an unknown argument is `invalid_input`.
On `:mcp` the same two names are twins (`McpFindPeople`, `McpGetPerson`, People S3b, MCP
0.13.0), own classes because their schema requires `organisation_id` (E3). `scope_mode
:token`; `PeopleTool.with_token_lookup` is their gate: only an organisation whose every
@@ -57,8 +65,8 @@ Codebase-Verständnis.
`project_id` als Pflicht, ToolCall gated das Projekt) oder `:token` (Inbox-Arbeitsfluss:
kein Projekt-Gate, `Context#reach` = `PersonalAccessToken::Reach`, läuft OHNE Tenant, nur
im `:mcp`-Set, record-mode; `list_notifications`, `mark_notification_read`,
- `list_organisations`, `list_projects`, die Personen-Zwillinge und `get_meeting`, die sich den
- Tenant ihrer Organisation selbst setzen). Die Inbox-
+ `list_organisations`, `list_projects`, die Personen-Zwillinge, `get_meeting` und `get_glossary`,
+ die sich den Tenant ihrer Organisation selbst setzen). Die Inbox-
Zeilen kommen aus `Notifications::InboxQuery` + `Serializer`, geteilt mit der HTTP-API.
Schreibende Werkzeuge gibt es nur im `:mcp`-Set: `create_ticket`, `post_comment`,
`create_time_session`, `mark_notification_read`, `update_ticket`, `create_meeting`