@cyanheads/ris-austria-mcp-server 0.4.3 → 0.5.0

package/changelog/0.5.x/0.5.0.md

@@ -0,0 +1,29 @@
+---
+summary: "ris_get_document returns over-budget html/xml as kind: link and accepts ogd.ris.bka.gv.at URLs; search tools reject blank text filters and page sizes above 20; issuer filters resolve the 2025 ministries and social-insurance carrier abbreviations."
+breaking: true
+security: false
+---
+
+# 0.5.0 — 2026-09-24
+
+## Changed
+
+- **`ris_get_document` html/xml over 40,000 bytes returns `kind: "link"`** — no text, `truncated: true`, the full `byte_size`, and `content_urls`; it previously returned the whole rendition as `kind: "full"`. Nearly every HTML rendition lands here, so read with `markdown` ([#36](https://github.com/cyanheads/ris-austria-mcp-server/issues/36)).
+- **Raw html/xml text is fenced in `content[]`**, with a fence longer than any backtick run in it, so markup reaches the client verbatim ([#36](https://github.com/cyanheads/ris-austria-mcp-server/issues/36)).
+- **`page_size` accepts only 10 or 20** on the six paginated tools; 50 and 100 are rejected at the schema — raise `page` to read further ([#40](https://github.com/cyanheads/ris-austria-mcp-server/issues/40)).
+- **Blank or whitespace-only text filters are rejected** on the five search tools (`filterText`, advertised as a JSON Schema `pattern`); omit the field to leave it unfiltered ([#39](https://github.com/cyanheads/ris-austria-mcp-server/issues/39)).
+- **`changed_since` is rejected with `collection: "social_insurance"` or `"veterinary"`** on `ris_search_announcements`, where RIS ignores it; the recovery names `published_from` and `ris_track_changes` ([#37](https://github.com/cyanheads/ris-austria-mcp-server/issues/37)).
+- **A ministry the target issuer parameter does not accept fails as `unresolved_ministry`**, naming the parameters that do accept it. `ris_search_drafts`, `ris_search_gazette`, and `ris_search_announcements` declare the reason, which also covers the unknown and ambiguous abbreviations previously reported as `invalid_query` ([#45](https://github.com/cyanheads/ris-austria-mcp-server/issues/45)).
+- **Social-insurance `issuer` expands carrier abbreviations** (`ÖGK`, `DVSV`, `SVS`, …) to the exact `Urheber` value, case-insensitively; any other value is sent as written ([#38](https://github.com/cyanheads/ris-austria-mcp-server/issues/38)).
+- **`ris_list_reference`**: `issuing_bodies` shows each carrier's accepted abbreviation, `ministries` lists the 2025 ministries, and `collections` lists `changed_since` only where RIS honors it.
+- **README and `docs/design.md`** document these rules — the README capability reference is condensed to a few bullets per tool, and the design notes record the decision behind each rule. Releases now go through a gated release PR with a review pass before publishing (`CLAUDE.md` / `AGENTS.md` `## Publishing`).
+
+## Fixed
+
+- **The ministries in office since 2025 resolve** — BMASGPK, BMEIF, BMFFJI, BMFI, BMFWF, BMIMI, BMLUK, BMWET, BMWKMS. A full designation missing from the table (any value containing a space) is now sent to RIS unchanged instead of rejected ([#44](https://github.com/cyanheads/ris-austria-mcp-server/issues/44)).
+- **`document_url` accepts `https://ogd.ris.bka.gv.at`**, the host search results now carry, alongside `https://www.ris.bka.gv.at`; the origin match stays exact ([#43](https://github.com/cyanheads/ris-austria-mcp-server/issues/43)).
+
+## Dependencies
+
+- `@socketsecurity/bun-security-scanner` ^1.1.2 → ^1.1.3
+- `@types/node` 26.6.1 → ^26.6.2

package/changelog/template.md

@@ -6,8 +6,8 @@
 
 # Required. One-line GitHub Release-style headline. 350 character cap — a
 # ceiling, not a target. Default short and scannable. Don't pad, don't stitch
-# unrelated changes with commas/semicolons into an inventory — pick the
-# headline, like a tag's theme line. Quotes required: unquoted YAML treats
+# unrelated changes with commas/semicolons into an inventory — pick the one
+# headline the release is about. Quotes required: unquoted YAML treats
 # `: ` inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
@@ -119,11 +119,11 @@ security: false
   TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
   via `gh release create --notes-from-tag`. It is a condensed digest of this
   entry, never a copy, and its format is owned by the `release-and-publish`
-  skill (step 4, "Create the annotated tag"): the entry's `summary:` as the
-  theme line without the version, flat headline bullets — no Keep-a-Changelog
-  section headers, no gates line — at most one deps line, issue backlinks,
-  and the changelog link last. In release-PR mode the `git-wrapup` skill
-  authors that digest as the PR body's `## Changes` and the tag copies it.
+  skill (step 4, "Create the annotated tag"): a short subject line without the
+  version, flat headline bullets — no Keep-a-Changelog section headers, no
+  gates line — at most one deps line, issue backlinks, and the changelog link
+  last. In release-PR mode the `git-wrapup` skill authors those bullets as the
+  PR body's `## Changes` and the tag copies them.
 -->
 
 ## Added

package/dist/config/server-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;iBAetB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D;;;GAGG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAO9C"}
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;iBAiBtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D;;;GAGG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAO9C"}

package/dist/config/server-config.js

@@ -13,7 +13,7 @@ const ServerConfigSchema = z.object({
     contentBaseUrl: z
         .url()
         .default('https://www.ris.bka.gv.at')
-        .describe('RIS document content host — also the allowlist host for document_url fetches.'),
+        .describe('RIS document content host that rendition URLs are constructed on. document_url accepts its origin alongside the two RIS content origins, https://www.ris.bka.gv.at and https://ogd.ris.bka.gv.at.'),
     contact: z
         .string()
         .optional()

package/dist/config/server-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,UAAU,EAAE,CAAC;SACV,GAAG,EAAE;SACL,OAAO,CAAC,qCAAqC,CAAC;SAC9C,QAAQ,CAAC,4BAA4B,CAAC;IACzC,cAAc,EAAE,CAAC;SACd,GAAG,EAAE;SACL,OAAO,CAAC,2BAA2B,CAAC;SACpC,QAAQ,CAAC,+EAA+E,CAAC;IAC5F,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,iGAAiG,CAClG;CACJ,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,UAAU,EAAE,kBAAkB;QAC9B,cAAc,EAAE,sBAAsB;QACtC,OAAO,EAAE,aAAa;KACvB,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,UAAU,EAAE,CAAC;SACV,GAAG,EAAE;SACL,OAAO,CAAC,qCAAqC,CAAC;SAC9C,QAAQ,CAAC,4BAA4B,CAAC;IACzC,cAAc,EAAE,CAAC;SACd,GAAG,EAAE;SACL,OAAO,CAAC,2BAA2B,CAAC;SACpC,QAAQ,CACP,mMAAmM,CACpM;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,iGAAiG,CAClG;CACJ,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,UAAU,EAAE,kBAAkB;QAC9B,cAAc,EAAE,sBAAsB;QACtC,OAAO,EAAE,aAAa;KACvB,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.js

@@ -18,6 +18,9 @@ import { initRisService } from './services/ris/ris-service.js';
 await createApp({
     name: 'ris-austria-mcp-server',
     title: 'ris-austria-mcp-server',
+    // Every tool answers from the request it was given — no handler gates on ctx.requestInput —
+    // so HTTP sessions buy nothing here. MCP_SESSION_MODE still overrides when set.
+    sessionMode: 'stateless',
     cacheHints: {
         'tools/list': { ttlMs: 3_600_000, cacheScope: 'public' },
         'resources/list': { ttlMs: 3_600_000, cacheScope: 'public' },

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,iEAAiE,CAAC;AACzG,OAAO,EAAE,gBAAgB,EAAE,MAAM,4DAA4D,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,wBAAwB;IAC9B,KAAK,EAAE,wBAAwB;IAC/B,UAAU,EAAE;QACV,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QACxD,gBAAgB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QAC5D,0BAA0B,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QACtE,iBAAiB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;KAC9D;IACD,KAAK,EAAE;QACL,oBAAoB;QACpB,gBAAgB;QAChB,gBAAgB;QAChB,eAAe;QACf,sBAAsB;QACtB,iBAAiB;QACjB,cAAc;QACd,eAAe;QACf,gBAAgB;KACjB;IACD,SAAS,EAAE,CAAC,mBAAmB,CAAC;IAChC,KAAK,CAAC,IAAI;QACR,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,iEAAiE,CAAC;AACzG,OAAO,EAAE,gBAAgB,EAAE,MAAM,4DAA4D,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,wBAAwB;IAC9B,KAAK,EAAE,wBAAwB;IAC/B,4FAA4F;IAC5F,gFAAgF;IAChF,WAAW,EAAE,WAAW;IACxB,UAAU,EAAE;QACV,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QACxD,gBAAgB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QAC5D,0BAA0B,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QACtE,iBAAiB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;KAC9D;IACD,KAAK,EAAE;QACL,oBAAoB;QACpB,gBAAgB;QAChB,gBAAgB;QAChB,eAAe;QACf,sBAAsB;QACtB,iBAAiB;QACjB,cAAc;QACd,eAAe;QACf,gBAAgB;KACjB;IACD,SAAS,EAAE,CAAC,mBAAmB,CAAC;IAChC,KAAK,CAAC,IAAI;QACR,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/_shared.d.ts

@@ -5,6 +5,7 @@
  */
 import type { TypedFail, TypedRecoveryFor } from '@cyanheads/mcp-ts-core';
 import { z } from '@cyanheads/mcp-ts-core';
+import { UNRESOLVED_MINISTRY_REASON } from '../../../services/ris/request-builder.js';
 /**
  * An ISO calendar date (YYYY-MM-DD), validated client-side before any upstream call — an
  * impossible date is an input error at every tool that takes one, never a silent upstream
@@ -16,6 +17,21 @@ import { z } from '@cyanheads/mcp-ts-core';
  * 29 February outside a leap year) and does not serialize.
  */
 export declare const isoDateString: z.ZodString;
+/**
+ * A free-text search filter, validated client-side: a supplied value must carry a
+ * non-whitespace character. RIS reads an empty filter as no filter and ignores some
+ * whitespace-only ones, so a blank would answer the unfiltered query the caller meant to
+ * narrow; omitting the field is the one way to leave a filter unset. The pattern reaches the
+ * advertised JSON Schema, so a schema-validating client rejects a blank before the call.
+ */
+export declare const filterText: z.ZodString;
+/**
+ * Documents per page on every paginated tool. RIS pages by page number over a fixed page
+ * size, so `page` / `pageSize` / `totalCount` / `truncated` stay exact at either size here;
+ * the service still speaks all four RIS sizes, but pages of 50 or 100 records are too large
+ * to return on both response surfaces, so callers read further with `page` instead.
+ */
+export declare const pageSizeParam: z.ZodOptional<z.ZodLiteral<10 | 20>>;
 /**
  * The three reasons every search-family tool declares for a failure raised below the
  * handler — in the request builder or in `RisService`. Each tool still declares its own
@@ -23,10 +39,10 @@ export declare const isoDateString: z.ZodString;
  * the subset {@link failSearchError} resolves against.
  */
 type SearchFailureReason = 'invalid_query' | 'upstream_error' | 'upstream_timeout';
-/** The slice of a handler `ctx` {@link failSearchError} needs. */
-interface SearchFailureContext {
-    readonly fail: TypedFail<SearchFailureReason>;
-    readonly recoveryFor: TypedRecoveryFor<SearchFailureReason>;
+/** The slice of a handler `ctx` the search-failure mappers need. */
+interface SearchFailureContext<R extends string = SearchFailureReason> {
+    readonly fail: TypedFail<R>;
+    readonly recoveryFor: TypedRecoveryFor<R>;
 }
 /**
  * Map a request-builder or service failure onto the declared contract, so `reason` and
@@ -37,6 +53,13 @@ interface SearchFailureContext {
  * Returns the error for the caller to `throw`, keeping the throw visible at the call site.
  */
 export declare function failSearchError(error: unknown, ctx: SearchFailureContext): unknown;
+/**
+ * {@link failSearchError} for the tools that take a ministry. The request builder tags a
+ * ministry it cannot resolve with `data.reason: 'unresolved_ministry'`; that rejection maps to
+ * the tool's own `unresolved_ministry` contract entry, whose recovery points at the ministries
+ * table, instead of the generic `invalid_query` advice. Everything else maps as usual.
+ */
+export declare function failMinistrySearchError(error: unknown, ctx: SearchFailureContext<SearchFailureReason | typeof UNRESOLVED_MINISTRY_REASON>): unknown;
 /** A request-builder unsupported-parameter rejection, as the builder recorded it. */
 export interface UnsupportedParam {
     /** Values of the same parameter that *are* mapped for the target application. */

package/dist/mcp-server/tools/definitions/_shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_shared.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAsB3C;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,aAMwE,CAAC;AAEnG;;;;;GAKG;AACH,KAAK,mBAAmB,GAAG,eAAe,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;AAEnF,kEAAkE;AAClE,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,mBAAmB,CAAC,CAAC;IAC9C,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC,mBAAmB,CAAC,CAAC;CAC7D;AAkBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAMlF;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,GAC1D,OAAO,CAWT"}
+{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_shared.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,OAAO,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAqB/E;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,aAMwE,CAAC;AAEnG;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,aAKpB,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,aAAa,sCAQvB,CAAC;AAEJ;;;;;GAKG;AACH,KAAK,mBAAmB,GAAG,eAAe,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;AAEnF,oEAAoE;AACpE,UAAU,oBAAoB,CAAC,CAAC,SAAS,MAAM,GAAG,mBAAmB;IACnE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAC3C;AAkBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAMlF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,oBAAoB,CAAC,mBAAmB,GAAG,OAAO,0BAA0B,CAAC,GACjF,OAAO,CAOT;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,GAC1D,OAAO,CAWT"}

package/dist/mcp-server/tools/definitions/_shared.js

@@ -5,6 +5,7 @@
  */
 import { z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode, McpError, validationError } from '@cyanheads/mcp-ts-core/errors';
+import { UNRESOLVED_MINISTRY_REASON } from '../../../services/ris/request-builder.js';
 /** Months with 30 days — the only non-February lengths a day of 31 can overshoot. */
 const THIRTY_DAY_MONTHS = new Set([4, 6, 9, 11]);
 /**
@@ -36,6 +37,28 @@ export const isoDateString = z
     .string()
     .regex(/^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$/u, 'Expected an ISO calendar date in YYYY-MM-DD form.')
     .refine(isRealCalendarDate, 'No such calendar date — check the day against the month and year.');
+/**
+ * A free-text search filter, validated client-side: a supplied value must carry a
+ * non-whitespace character. RIS reads an empty filter as no filter and ignores some
+ * whitespace-only ones, so a blank would answer the unfiltered query the caller meant to
+ * narrow; omitting the field is the one way to leave a filter unset. The pattern reaches the
+ * advertised JSON Schema, so a schema-validating client rejects a blank before the call.
+ */
+export const filterText = z
+    .string()
+    .regex(/\S/u, 'Blank or whitespace-only — send a value, or omit the field to leave it unfiltered.');
+/**
+ * Documents per page on every paginated tool. RIS pages by page number over a fixed page
+ * size, so `page` / `pageSize` / `totalCount` / `truncated` stay exact at either size here;
+ * the service still speaks all four RIS sizes, but pages of 50 or 100 records are too large
+ * to return on both response surfaces, so callers read further with `page` instead.
+ */
+export const pageSizeParam = z
+    .literal([10, 20], {
+    error: 'Expected 10 or 20 (default 20) — larger pages are not served; raise page to read further results.',
+})
+    .optional()
+    .describe('Documents per page: 10 or 20 (default 20). For more results, keep the size and raise page.');
 /**
  * Framework codes raised below the handler, mapped to the contract reason describing them.
  *
@@ -67,6 +90,20 @@ export function failSearchError(error, ctx) {
         ? error
         : ctx.fail(reason, error.message, { ...ctx.recoveryFor(reason) });
 }
+/**
+ * {@link failSearchError} for the tools that take a ministry. The request builder tags a
+ * ministry it cannot resolve with `data.reason: 'unresolved_ministry'`; that rejection maps to
+ * the tool's own `unresolved_ministry` contract entry, whose recovery points at the ministries
+ * table, instead of the generic `invalid_query` advice. Everything else maps as usual.
+ */
+export function failMinistrySearchError(error, ctx) {
+    if (error instanceof McpError && error.data?.reason === UNRESOLVED_MINISTRY_REASON) {
+        return ctx.fail(UNRESOLVED_MINISTRY_REASON, error.message, {
+            ...ctx.recoveryFor(UNRESOLVED_MINISTRY_REASON),
+        });
+    }
+    return failSearchError(error, ctx);
+}
 /**
  * Replace the request builder's unsupported-parameter message with one written in the
  * calling tool's own vocabulary, so the caller reads back a field it actually sent.

package/dist/mcp-server/tools/definitions/_shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"_shared.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_shared.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"_shared.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_shared.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/ris-get-document.tool.d.ts

@@ -14,7 +14,10 @@
  * retrievable outline rather than a silent truncation — its §/Artikel/Anlage sections, or
  * `Part n of N` byte windows where it carries no such headings; a follow-up call with
  * `sections:[…]` returns just the chosen entries, and a selector matching nothing gets the
- * outline back with a notice rather than the whole document. The shared
+ * outline back with a notice rather than the whole document. Raw `html` and `xml` are never
+ * sliced: over the same budget they come back as a `kind: link` result that carries no text
+ * and points at `content_urls`, which fetches the whole artifact in one GET. Raw text that
+ * does return is fenced in `content[]`, so markup never renders there as markdown. The shared
  * {@link renderDocument} helper backs both this tool and the `ris://document/…` resource.
  * @module mcp-server/tools/definitions/ris-get-document
  */
@@ -43,6 +46,12 @@ export type DocumentFormat = 'markdown' | 'html' | 'xml' | 'urls_only';
  *
  * Handed to `outlineOnOverflow`, which measures `JSON.stringify` length (≈ UTF-8 bytes for
  * the mostly-Latin legal text); the exact `byte_size` is reported separately.
+ *
+ * The same number bounds raw `html` and `xml`, measured on `byte_size` — the figure the caller
+ * sees and the link notice cites. Those are never windowed (their bodies are typically one
+ * line, and a slice is not well-formed), so over the budget they return a `kind: link` result
+ * instead. Every HTML rendition opens with a 40–70 KB stylesheet header, so html practically
+ * never inlines; markdown is the reading format, and `content_urls.html` the authentic markup.
  */
 export declare const OUTLINE_BUDGET_BYTES = 40000;
 /** Constructed rendition URLs for a document, keyed by DataType. */
@@ -88,8 +97,10 @@ type ParsedDocumentUrl = {
 };
 /**
  * Parse a caller-supplied `document_url` into `(application, documentNumber)` — errors as
- * values (no throw). Enforces the same host + `/Dokumente/` allowlist as the service's
- * fetch guard, then reverse-maps the content-path segment to its application.
+ * values (no throw). Enforces the same origin + `/Dokumente/` allowlist as the service's
+ * fetch guard, then reverse-maps the content-path segment to its application. The origin a
+ * URL arrived on is not carried forward: the rendition is fetched from the URL the service
+ * constructs, which RIS serves identically on both content origins.
  */
 export declare function parseDocumentUrl(url: string, contentBaseUrl: string): ParsedDocumentUrl;
 /**
@@ -151,8 +162,8 @@ export declare function windowDocument(text: string, budget: number): DocumentSe
  * here, so every entry the outline advertises is retrievable by name.
  *
  * Markdown only. `html` and `xml` are byte-identical passthroughs of the published artifact
- * and a mid-document slice of either is not well-formed, so they stay whole at any size and
- * a caller who needs one has `content_urls`.
+ * and a mid-document slice of either is not well-formed, so they are never addressed in
+ * pieces: whole under the budget, a `kind: link` result pointing at `content_urls` over it.
  *
  * The two-entry floor matches `outlineOnOverflow`'s own short-circuit: an outline whose only
  * possible `sections` argument returns the same bytes costs a round-trip and buys nothing.
@@ -245,6 +256,7 @@ export declare const risGetDocument: import("@cyanheads/mcp-ts-core").ToolDefini
     truncated: z.ZodOptional<z.ZodBoolean>;
     kind: z.ZodEnum<{
         full: "full";
+        link: "link";
         outline: "outline";
     }>;
     sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -277,8 +289,8 @@ export declare const risGetDocument: import("@cyanheads/mcp-ts-core").ToolDefini
 }, {
     readonly reason: "unsupported_url";
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: "document_url fails the host + /Dokumente/ path-prefix allowlist, its path segment is not a recognized RIS application, or its trailing filename addresses neither the document’s own rendition nor one of its companion documents — thrown locally, nothing fetched.";
-    readonly recovery: "Only ris.bka.gv.at /Dokumente/ URLs are fetchable, and only a document’s own rendition or a companion filed in the same folder — copy the URL verbatim from a result’s content_urls or a ris_search_drafts record’s materials, or switch to document_number + application.";
+    readonly when: "document_url fails the origin + /Dokumente/ path-prefix allowlist (exactly https://www.ris.bka.gv.at and https://ogd.ris.bka.gv.at), its path segment is not a recognized RIS application, or its trailing filename addresses neither the document’s own rendition nor one of its companion documents — thrown locally, nothing fetched.";
+    readonly recovery: "Only /Dokumente/ URLs on www.ris.bka.gv.at or ogd.ris.bka.gv.at are fetchable, and only a document’s own rendition or a companion filed in the same folder — copy the URL verbatim from a result’s content_urls or a ris_search_drafts record’s materials, or switch to document_number + application.";
 }, {
     readonly reason: "document_not_found";
     readonly code: JsonRpcErrorCode.NotFound;

package/dist/mcp-server/tools/definitions/ris-get-document.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ris-get-document.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/ris-get-document.tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ris-get-document.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/ris-get-document.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/ris-get-document.tool.js

@@ -14,17 +14,20 @@
  * retrievable outline rather than a silent truncation — its §/Artikel/Anlage sections, or
  * `Part n of N` byte windows where it carries no such headings; a follow-up call with
  * `sections:[…]` returns just the chosen entries, and a selector matching nothing gets the
- * outline back with a notice rather than the whole document. The shared
+ * outline back with a notice rather than the whole document. Raw `html` and `xml` are never
+ * sliced: over the same budget they come back as a `kind: link` result that carries no text
+ * and points at `content_urls`, which fetches the whole artifact in one GET. Raw text that
+ * does return is fenced in `content[]`, so markup never renders there as markdown. The shared
  * {@link renderDocument} helper backs both this tool and the `ris://document/…` resource.
  * @module mcp-server/tools/definitions/ris-get-document
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode, McpError, validationError } from '@cyanheads/mcp-ts-core/errors';
-import { OUTLINE_VARIANT, outlineOnOverflow, } from '@cyanheads/mcp-ts-core/utils';
+import { markdown, OUTLINE_VARIANT, outlineOnOverflow, } from '@cyanheads/mcp-ts-core/utils';
 import { NodeHtmlMarkdown } from 'node-html-markdown';
 import { getServerConfig } from '../../../config/server-config.js';
 import { RIS_APPLICATIONS } from '../../../services/ris/reference/index.js';
-import { getRisService, RIS_CONTENT_FORMATS, } from '../../../services/ris/ris-service.js';
+import { fetchableOrigins, getRisService, RIS_CONTENT_FORMATS, } from '../../../services/ris/ris-service.js';
 /** The seven canonical binding labels (Design Decisions › Binding status). */
 const BINDING_STATUSES = [
     'authentic',
@@ -53,6 +56,12 @@ const BINDING_STATUSES = [
  *
  * Handed to `outlineOnOverflow`, which measures `JSON.stringify` length (≈ UTF-8 bytes for
  * the mostly-Latin legal text); the exact `byte_size` is reported separately.
+ *
+ * The same number bounds raw `html` and `xml`, measured on `byte_size` — the figure the caller
+ * sees and the link notice cites. Those are never windowed (their bodies are typically one
+ * line, and a slice is not well-formed), so over the budget they return a `kind: link` result
+ * instead. Every HTML rendition opens with a 40–70 KB stylesheet header, so html practically
+ * never inlines; markdown is the reading format, and `content_urls.html` the authentic markup.
  */
 export const OUTLINE_BUDGET_BYTES = 40_000;
 const APPLICATION_CODES = RIS_APPLICATIONS.map((app) => app.code);
@@ -151,8 +160,10 @@ function decodePathSegment(segment) {
 }
 /**
  * Parse a caller-supplied `document_url` into `(application, documentNumber)` — errors as
- * values (no throw). Enforces the same host + `/Dokumente/` allowlist as the service's
- * fetch guard, then reverse-maps the content-path segment to its application.
+ * values (no throw). Enforces the same origin + `/Dokumente/` allowlist as the service's
+ * fetch guard, then reverse-maps the content-path segment to its application. The origin a
+ * URL arrived on is not carried forward: the rendition is fetched from the URL the service
+ * constructs, which RIS serves identically on both content origins.
  */
 export function parseDocumentUrl(url, contentBaseUrl) {
     let parsed;
@@ -162,8 +173,9 @@ export function parseDocumentUrl(url, contentBaseUrl) {
     catch {
         return { error: `"${url}" is not a valid URL` };
     }
-    if (parsed.origin !== new URL(contentBaseUrl).origin) {
-        return { error: `only ${new URL(contentBaseUrl).origin} URLs are fetchable` };
+    const origins = fetchableOrigins(contentBaseUrl);
+    if (!origins.includes(parsed.origin)) {
+        return { error: `only ${origins.join(' or ')} URLs are fetchable` };
     }
     if (!parsed.pathname.startsWith('/Dokumente/')) {
         return { error: 'the path is outside the /Dokumente/ tree' };
@@ -419,8 +431,8 @@ export function windowDocument(text, budget) {
  * here, so every entry the outline advertises is retrievable by name.
  *
  * Markdown only. `html` and `xml` are byte-identical passthroughs of the published artifact
- * and a mid-document slice of either is not well-formed, so they stay whole at any size and
- * a caller who needs one has `content_urls`.
+ * and a mid-document slice of either is not well-formed, so they are never addressed in
+ * pieces: whole under the budget, a `kind: link` result pointing at `content_urls` over it.
  *
  * The two-entry floor matches `outlineOnOverflow`'s own short-circuit: an outline whose only
  * possible `sections` argument returns the same bytes costs a round-trip and buys nothing.
@@ -575,7 +587,7 @@ const ContentUrlsSchema = z
     .describe('Constructed rendition URLs. Empty for authentic-PDF-only (Bvb/GrA/KmGer) and metadata-only (BgblAlt) applications — see authentic_pdf_url and the notice. For a companion document (a draft’s Erläuterungen, Textgegenüberstellung, WFA, cover letter, or annex) these are the companion’s own XML/HTML/PDF, not the parent document’s — constructed rather than read back from RIS, so for the roughly one companion in eight that RIS files as a PDF only, xml and html return 404 and pdf is the one that resolves.');
 export const risGetDocument = tool('ris_get_document', {
     title: 'Get RIS Document',
-    description: 'Fetch one RIS document’s full text or its rendition URLs, with explicit binding status and the amtssigniert authentic PDF surfaced wherever it exists. Address the document exactly one of two ways: document_number plus application (both copied verbatim from a ris_search_* or ris_lookup_citation result), or a document_url from a result’s content_urls — or, for a draft’s companion documents (Erläuterungen, Textgegenüberstellung, WFA, cover letter, annexes), a ris_search_drafts record’s materials[].url, which is the only route to them. format: markdown (default — the HTML rendition converted to markdown), html (raw HTML rendition), xml (the RIS Nutzdaten XML), or urls_only (no fetch — every rendition URL, including the Authentisch PDF). Format availability varies by application and the tool degrades explicitly, never silently: consolidated law, gazettes, case law, drafts, and most sectoral collections carry full text; district and municipal promulgations and court rules (Bvb, GrA, KmGer) publish only the signed authentic PDF; party-transparency decisions and council minutes (Upts, Mrp) are PDF-only; the 1848–1940 imperial gazettes (BgblAlt) are metadata-only — for these a text-format request returns a format_unavailable notice with the usable URL, not an error. Every result carries binding_status; only authentic (amtssigniert) publications are legally binding. This tool returns content, not fresh metadata — the metadata rides the search/lookup step that produced the document number. When the markdown text overflows the 40,000-byte budget the tool returns an outline (kind: outline) instead of truncating: the document’s §/Artikel/Anlage sections where it carries at least two such headings, otherwise contiguous byte windows named Part 1 of N … Part N of N covering the whole text and listed in document order. Re-call with sections:[…] naming outline entries to retrieve just those; a name matching no entry returns the outline again with a notice rather than the whole document. Windows are cut at line breaks, not at sentence or § boundaries, so one can open mid-sentence — read them in order and pull the neighbour when a passage straddles a cut. Raw html and xml renditions are never sliced and return whole at any size. Markdown drops the screen-reader expansions RIS ships alongside each abbreviated citation, keeping the visible citation form; raw html/xml renditions are returned exactly as published.',
+    description: 'Fetch one RIS document’s full text or its rendition URLs, with explicit binding status and the amtssigniert authentic PDF surfaced wherever it exists. Address the document exactly one of two ways: document_number plus application (both copied verbatim from a ris_search_* or ris_lookup_citation result), or a document_url from a result’s content_urls — or, for a draft’s companion documents (Erläuterungen, Textgegenüberstellung, WFA, cover letter, annexes), a ris_search_drafts record’s materials[].url, which is the only route to them. format: markdown (default — the HTML rendition converted to markdown), html (raw HTML rendition), xml (the RIS Nutzdaten XML), or urls_only (no fetch — every rendition URL, including the Authentisch PDF). Format availability varies by application and the tool degrades explicitly, never silently: consolidated law, gazettes, case law, drafts, and most sectoral collections carry full text; district and municipal promulgations and court rules (Bvb, GrA, KmGer) publish only the signed authentic PDF; party-transparency decisions and council minutes (Upts, Mrp) are PDF-only; the 1848–1940 imperial gazettes (BgblAlt) are metadata-only — for these a text-format request returns a format_unavailable notice with the usable URL, not an error. Every result carries binding_status; only authentic (amtssigniert) publications are legally binding. This tool returns content, not fresh metadata — the metadata rides the search/lookup step that produced the document number. When the markdown text overflows the 40,000-byte budget the tool returns an outline (kind: outline) instead of truncating: the document’s §/Artikel/Anlage sections where it carries at least two such headings, otherwise contiguous byte windows named Part 1 of N … Part N of N covering the whole text and listed in document order. Re-call with sections:[…] naming outline entries to retrieve just those; a name matching no entry returns the outline again with a notice rather than the whole document. Windows are cut at line breaks, not at sentence or § boundaries, so one can open mid-sentence — read them in order and pull the neighbour when a passage straddles a cut. Raw html and xml renditions are never sliced: at or under the 40,000-byte budget they return whole; over it the result is kind: link — no text, truncated: true, the full byte_size, and content_urls, whose html or xml entry fetches the whole artifact in one GET. Every HTML rendition opens with a 40–70 KB stylesheet, so html practically always returns kind: link — read with markdown, parse with xml, and fetch content_urls.html for the authentic markup. Markdown drops the screen-reader expansions RIS ships alongside each abbreviated citation, keeping the visible citation form; raw html/xml renditions are returned exactly as published.',
     annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     input: z.object({
         document_number: z
@@ -589,35 +601,35 @@ export const risGetDocument = tool('ris_get_document', {
         document_url: z
             .string()
             .optional()
-            .describe('A https://www.ris.bka.gv.at/Dokumente/… rendition URL as returned in a result’s content_urls — the alternative to document_number + application. Also the only way to read a draft’s companion documents: pass a ris_search_drafts record’s materials[].url (the Erläuterungen, Textgegenüberstellung, WFA, cover letter, or annex), whose filenames are opaque and per-record and so cannot be reached through document_number. Every companion filename RIS publishes is accepted, whichever shape it carries. The URL’s own extension is only checked against the rendition extensions RIS uses and is then discarded — format selects which rendition is returned, for a companion exactly as for a main document. A filename that is neither this document’s own rendition nor one of its companions is rejected; companion filenames cannot be composed by hand, so copy one verbatim.'),
+            .describe('A /Dokumente/… rendition URL on https://www.ris.bka.gv.at or https://ogd.ris.bka.gv.at, passed exactly as a result’s content_urls returned it — the alternative to document_number + application. Also the only way to read a draft’s companion documents: pass a ris_search_drafts record’s materials[].url (the Erläuterungen, Textgegenüberstellung, WFA, cover letter, or annex), whose filenames are opaque and per-record and so cannot be reached through document_number. Every companion filename RIS publishes is accepted, whichever shape it carries. The URL’s own extension is only checked against the rendition extensions RIS uses and is then discarded — format selects which rendition is returned, for a companion exactly as for a main document. A filename that is neither this document’s own rendition nor one of its companions is rejected; companion filenames cannot be composed by hand, so copy one verbatim.'),
         format: z
             .enum(['markdown', 'html', 'xml', 'urls_only'])
             .default('markdown')
-            .describe('markdown (default — the HTML rendition converted to markdown), html (raw HTML rendition), xml (RIS Nutzdaten schema), or urls_only (no fetch — all rendition URLs incl. the authentic PDF).'),
+            .describe('markdown (default — the HTML rendition converted to markdown, and the format for reading), html (raw HTML rendition), xml (RIS Nutzdaten schema), or urls_only (no fetch — all rendition URLs incl. the authentic PDF). html and xml over 40,000 bytes return kind: link with no text — nearly every html rendition does, since each carries a 40–70 KB stylesheet — so fetch content_urls.html or content_urls.xml for the whole artifact.'),
         sections: z
             .array(z.string())
             .optional()
-            .describe('Entry names to retrieve, each copied verbatim from a prior outline response (kind: outline) — §/Artikel/Anlage section names, or window names of the form "Part 2 of 6". Omit for the full document, which returns an outline instead when the markdown overflows the 40,000-byte budget. A name that matches no entry is never silently ignored: a total miss returns the outline (kind: outline) with a notice, a partial miss returns the matched entries with a notice naming others to pick from. Applies to markdown only — html, xml, and urls_only are never sliced and return in full.'),
+            .describe('Entry names to retrieve, each copied verbatim from a prior outline response (kind: outline) — §/Artikel/Anlage section names, or window names of the form "Part 2 of 6". Omit for the full document, which returns an outline instead when the markdown overflows the 40,000-byte budget. A name that matches no entry is never silently ignored: a total miss returns the outline (kind: outline) with a notice, a partial miss returns the matched entries with a notice naming others to pick from. Applies to markdown only. html and xml are never sliced — the selector is ignored with a notice, and they return whole under the 40,000-byte budget and as kind: link over it; urls_only carries no text to select from.'),
     }),
     output: z.object({
         text: z
             .string()
             .optional()
-            .describe('The document text in the requested format. Absent for urls_only and when the application carries no text rendition (see the notice).'),
+            .describe('The document text in the requested format. Absent for urls_only, when the application carries no text rendition (see the notice), for an outline (kind: outline), and for an html or xml rendition over the 40,000-byte budget (kind: link).'),
         format: z
             .enum(['markdown', 'html', 'xml', 'urls_only'])
             .describe('The format served — echoes the requested format.'),
         byte_size: z
             .number()
             .optional()
-            .describe('Full UTF-8 byte size of the document text. Present when text was fetched — for an overflowed document (kind: outline) this reports the full text’s size, not the outline payload’s.'),
+            .describe('Full UTF-8 byte size of the document text. Present when text was fetched — for an overflowed document (kind: outline) or an over-budget html/xml rendition (kind: link) this reports the full text’s size, not the returned payload’s.'),
         truncated: z
             .boolean()
             .optional()
-            .describe('Present and true when the full text isn’t inline because an outline was returned instead (kind: outline) — either the document overflowed the byte budget, or a sections:[…] selector matched nothing. The notice names which. Retrieve entries via the sections input, or fetch content_urls for the whole artifact.'),
+            .describe('Present and true when the full text isn’t inline. kind: outline — the markdown overflowed the byte budget or a sections:[…] selector matched nothing (the notice names which); retrieve entries via the sections input. kind: link — an html or xml rendition overflowed the budget; fetch content_urls.html or content_urls.xml for the whole artifact, or re-call with format: markdown.'),
         kind: z
-            .enum(['full', 'outline'])
-            .describe('full — the complete response (document text, selected entries, or rendition URLs). outline — sections lists the retrievable entries instead of the text, either because the document overflowed the byte budget or because a sections:[…] selector matched nothing; re-call with sections:[…] naming entries from it.'),
+            .enum(['full', 'outline', 'link'])
+            .describe('full — the complete response (document text, selected entries, or rendition URLs). outline — sections lists the retrievable entries instead of the text, either because the markdown overflowed the byte budget or because a sections:[…] selector matched nothing; re-call with sections:[…] naming entries from it. link — an html or xml rendition over the 40,000-byte budget: no text, only byte_size and content_urls, whose entry for the requested format fetches the whole artifact in one GET; re-call with format: markdown to read it.'),
         sections: z
             .array(OUTLINE_VARIANT.shape.sections.element.describe('A retrievable entry — a §/Artikel/Anlage section or a Part n of N byte window, with its UTF-8 byte size.'))
             .optional()
@@ -637,7 +649,7 @@ export const risGetDocument = tool('ris_get_document', {
         notice: z
             .string()
             .optional()
-            .describe('Present when the requested text format is unavailable for this application (names why and the usable URL), when the document overflowed to a section outline (names how to retrieve sections), or when a sections:[…] entry matched no section (names the unmatched entries).'),
+            .describe('Present when the requested text format is unavailable for this application (names why and the usable URL), when the document overflowed to a section outline (names how to retrieve sections), when an html or xml rendition overflowed to a link (names content_urls.<format> and format: markdown), or when a sections:[…] entry matched no section or was ignored (names the unmatched entries).'),
     },
     errors: [
         {
@@ -649,8 +661,8 @@ export const risGetDocument = tool('ris_get_document', {
         {
             reason: 'unsupported_url',
             code: JsonRpcErrorCode.ValidationError,
-            when: 'document_url fails the host + /Dokumente/ path-prefix allowlist, its path segment is not a recognized RIS application, or its trailing filename addresses neither the document’s own rendition nor one of its companion documents — thrown locally, nothing fetched.',
-            recovery: 'Only ris.bka.gv.at /Dokumente/ URLs are fetchable, and only a document’s own rendition or a companion filed in the same folder — copy the URL verbatim from a result’s content_urls or a ris_search_drafts record’s materials, or switch to document_number + application.',
+            when: 'document_url fails the origin + /Dokumente/ path-prefix allowlist (exactly https://www.ris.bka.gv.at and https://ogd.ris.bka.gv.at), its path segment is not a recognized RIS application, or its trailing filename addresses neither the document’s own rendition nor one of its companion documents — thrown locally, nothing fetched.',
+            recovery: 'Only /Dokumente/ URLs on www.ris.bka.gv.at or ogd.ris.bka.gv.at are fetchable, and only a document’s own rendition or a companion filed in the same folder — copy the URL verbatim from a result’s content_urls or a ris_search_drafts record’s materials, or switch to document_number + application.',
         },
         {
             reason: 'document_not_found',
@@ -675,9 +687,8 @@ export const risGetDocument = tool('ris_get_document', {
     ],
     async handler(input, ctx) {
         const documentNumber = meaningful(input.document_number);
-        const application = meaningful(input.application);
         const documentUrl = meaningful(input.document_url);
-        const { format } = input;
+        const { application, format } = input;
         const failAddressing = (message) => ctx.fail('invalid_addressing', message, { ...ctx.recoveryFor('invalid_addressing') });
         let resolvedApplication;
         let resolvedDocumentNumber;
@@ -757,6 +768,18 @@ export const risGetDocument = tool('ris_get_document', {
         }
         const { byteSize } = rendition;
         const requestedSections = input.sections?.filter((name) => name.trim() !== '') ?? [];
+        // A raw rendition over the budget. Never sliced — its body is typically one line and a
+        // slice is not well-formed — so no text returns on either surface; content_urls fetches
+        // the whole artifact in one GET, and markdown is the bounded reading path.
+        if ((format === 'html' || format === 'xml') &&
+            byteSize !== undefined &&
+            byteSize > OUTLINE_BUDGET_BYTES) {
+            const ignored = requestedSections.length > 0
+                ? `sections:[…] was ignored — raw html and xml are never sliced, so ${quoteNames([...new Set(requestedSections)])} could not be resolved. `
+                : '';
+            ctx.enrich.notice(`${ignored}The ${format} rendition is ${byteSize} bytes, over the ${OUTLINE_BUDGET_BYTES}-byte budget for inline text, so no text is returned. Fetch the whole artifact in one GET from content_urls.${format} (${rendition.contentUrls[format]}), or re-call ris_get_document with the same addressing and format: "markdown" for readable text, which outlines a long document into retrievable sections.`);
+            return { ...base, kind: 'link', truncated: true, byte_size: byteSize };
+        }
         // Selective retrieval — the re-call after an outline. Every outcome is disclosed: a
         // partial match names the entries that were dropped, and a total miss returns the section
         // roster (driven by the no-match, not by the byte budget) so the caller can tell "your
@@ -826,12 +849,20 @@ export const risGetDocument = tool('ris_get_document', {
     // format() populates content[] — the markdown twin of structuredContent. Every output
     // field renders here; the notice rides the enrichment trailer. The full-text (`text`) and
     // outline (`sections`) arms render on field presence, independently — never branch on
-    // `kind` (format-parity walks one sample with every optional field populated at once).
+    // `kind` (format-parity walks one sample with every optional field populated at once). A
+    // truncated result with no `sections` is the link arm, which has no outline to point at.
+    // Raw html/xml is fenced with a fence longer than any backtick run in it, so the markup
+    // reaches the client as literal text — never rendered, never able to close the block.
     format: (result) => {
         const lines = [`## ${result.document_number} (${result.application})`];
         lines.push(`**Binding:** ${result.binding_status} | **Format:** ${result.format} | **Kind:** ${result.kind}`);
         if (result.byte_size !== undefined) {
-            lines.push(`**Size:** ${result.byte_size} bytes${result.truncated === true ? ' (truncated — retrieve sections from the outline below)' : ''}`);
+            const suffix = result.truncated !== true
+                ? ''
+                : result.sections !== undefined
+                    ? ' (truncated — retrieve sections from the outline below)'
+                    : ` (not inline — fetch content_urls.${result.format}, or re-call with format: markdown)`;
+            lines.push(`**Size:** ${result.byte_size} bytes${suffix}`);
         }
         if (result.authentic_pdf_url !== undefined) {
             lines.push(`**Authentic PDF:** ${result.authentic_pdf_url}`);
@@ -843,8 +874,11 @@ export const risGetDocument = tool('ris_get_document', {
             lines.push(`**Renditions:** ${urls.join(' · ')}`);
         if (result.sections !== undefined)
             lines.push('', renderOutlineSections(result.sections));
-        if (result.text !== undefined)
-            lines.push('', result.text);
+        if (result.text !== undefined) {
+            lines.push('', result.format === 'markdown'
+                ? result.text
+                : markdown().codeBlock(result.text, result.format).build());
+        }
         return [{ type: 'text', text: lines.join('\n') }];
     },
 });