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

package/AGENTS.md

@@ -1,11 +1,11 @@
 # Developer Protocol
 
 **Server:** ris-austria-mcp-server
-**Version:** 0.5.0
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
+**Version:** 0.5.2
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
-**Zod:** ^4.6.5
+**MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
+**Zod:** ^4.6.7
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -140,12 +140,14 @@ to env-var names so a configuration failure names the variable the operator can
 
 ### Server identity and instructions
 
-The entry point pins the machine identity and immutable public catalog cache hints:
+The entry point pins the machine identity, the server instructions, and immutable public catalog
+cache hints:
 
 ```ts
 await createApp({
   name: 'ris-austria-mcp-server',
   title: 'ris-austria-mcp-server',
+  instructions: INSTRUCTIONS, // one paragraph: coverage, entry points, addressing, chains, binding
   sessionMode: 'stateless',
   cacheHints: {
     'tools/list': { ttlMs: 3_600_000, cacheScope: 'public' },
@@ -162,6 +164,9 @@ await createApp({
 ```
 
 `package.json` is the canonical description source; do not duplicate it into `createApp()`.
+`INSTRUCTIONS` in `src/index.ts` stays under 2,048 UTF-8 bytes (Claude Code truncates past that)
+and names only registered `ris_*` tools — `tests/tools/framework-contract.test.ts` pins both, so
+renaming a tool or a parameter it cites means updating the string.
 
 ### Session posture and shutdown
 
@@ -199,7 +204,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -211,7 +216,7 @@ errors: [
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);
-  if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
   return item;
 }
 ```
@@ -276,7 +281,7 @@ src/
 
 ## Skills
 
-Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
+Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
 
 **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
 
@@ -349,13 +354,15 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
+**CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
+
 ---
 
 ## Bundling
 
-`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
 
-**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
+**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
 
 **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
 
@@ -382,15 +389,15 @@ security: false                            # optional — true ONLY for a source
 
 `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
 
-**Section order:** Added, Changed, Deprecated, Removed, Fixed, Security, then Dependencies. Include only sections with entries — don't ship empty headers.
+**Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries — don't ship empty headers.
 
-**Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `framework-skills/release-and-publish/SKILL.md` for the tag format.
+**Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
 
 ---
 
 ## Publishing
 
-**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
+**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
 
 ---
 
@@ -420,7 +427,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
-- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name; `interface.shortDescription` from `package.json` description
-- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; user-supplied variables are listed in `env_vars`, never empty `env` values
-- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name; user-supplied variables declared in `userConfig` and referenced as `${user_config.<option>}`
+- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
+- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
+- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
 - [ ] `npm run devcheck` passes

package/CLAUDE.md

@@ -1,11 +1,11 @@
 # Developer Protocol
 
 **Server:** ris-austria-mcp-server
-**Version:** 0.5.0
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
+**Version:** 0.5.2
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
-**Zod:** ^4.6.5
+**MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
+**Zod:** ^4.6.7
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -140,12 +140,14 @@ to env-var names so a configuration failure names the variable the operator can
 
 ### Server identity and instructions
 
-The entry point pins the machine identity and immutable public catalog cache hints:
+The entry point pins the machine identity, the server instructions, and immutable public catalog
+cache hints:
 
 ```ts
 await createApp({
   name: 'ris-austria-mcp-server',
   title: 'ris-austria-mcp-server',
+  instructions: INSTRUCTIONS, // one paragraph: coverage, entry points, addressing, chains, binding
   sessionMode: 'stateless',
   cacheHints: {
     'tools/list': { ttlMs: 3_600_000, cacheScope: 'public' },
@@ -162,6 +164,9 @@ await createApp({
 ```
 
 `package.json` is the canonical description source; do not duplicate it into `createApp()`.
+`INSTRUCTIONS` in `src/index.ts` stays under 2,048 UTF-8 bytes (Claude Code truncates past that)
+and names only registered `ris_*` tools — `tests/tools/framework-contract.test.ts` pins both, so
+renaming a tool or a parameter it cites means updating the string.
 
 ### Session posture and shutdown
 
@@ -199,7 +204,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -211,7 +216,7 @@ errors: [
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);
-  if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
   return item;
 }
 ```
@@ -276,7 +281,7 @@ src/
 
 ## Skills
 
-Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
+Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
 
 **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
 
@@ -349,13 +354,15 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
+**CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
+
 ---
 
 ## Bundling
 
-`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
 
-**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
+**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
 
 **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
 
@@ -382,15 +389,15 @@ security: false                            # optional — true ONLY for a source
 
 `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
 
-**Section order:** Added, Changed, Deprecated, Removed, Fixed, Security, then Dependencies. Include only sections with entries — don't ship empty headers.
+**Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries — don't ship empty headers.
 
-**Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `framework-skills/release-and-publish/SKILL.md` for the tag format.
+**Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
 
 ---
 
 ## Publishing
 
-**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
+**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
 
 ---
 
@@ -420,7 +427,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
-- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name; `interface.shortDescription` from `package.json` description
-- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; user-supplied variables are listed in `env_vars`, never empty `env` values
-- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name; user-supplied variables declared in `userConfig` and referenced as `${user_config.<option>}`
+- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
+- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
+- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
 - [ ] `npm run devcheck` passes

package/Dockerfile

@@ -3,8 +3,18 @@
 #
 # This stage installs all dependencies (including dev), builds the TypeScript
 # source code into JavaScript, and prepares the production assets.
+#
+# Pinned to $BUILDPLATFORM rather than the target platform: `bun run build` emits
+# JavaScript, and only `dist/` crosses into the production stage. Built for the
+# target instead, the non-native leg of a `--platform linux/amd64,linux/arm64`
+# build runs under QEMU, where bun >= 1.4 aborts with a JavaScriptCore allocator
+# assertion and fails the multi-arch push.
+#
+# The constraint this assumes: the build stage produces platform-independent
+# output. A stage that compiles a native addon needs the target-arch toolchain
+# and cannot cross-compile this way — drop the flag there.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS build
 
 WORKDIR /usr/src/app
 
@@ -24,59 +34,106 @@ RUN bun run build
 
 
 # ==============================================================================
-# Production Stage
+# Production Dependencies Stage
 #
-# This stage creates a minimal, optimized, and secure image for running the
-# application. It uses a slim base image and only includes production
-# dependencies and build artifacts.
+# Installs the production dependency tree for the target platform. Every step
+# here can run JavaScript — bunfig.toml's security scanner runs as a Bun
+# program, and so do the OTel and musl-prune scripts — so the stage runs on
+# $BUILDPLATFORM and cross-installs with `--os`/`--cpu`, which pick each
+# platform-specific optional dependency (native bindings such as DuckDB's) for
+# the target. Only `node_modules` leaves this stage.
+#
+# A clean image rather than `FROM build`: the build stage's node_modules holds
+# devDependencies.
 # ==============================================================================
-FROM oven/bun:1.4.0-slim AS production
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS deps
 
 WORKDIR /usr/src/app
 
-# Set the environment to production for performance and to ensure only
-# production dependencies are installed.
-ENV NODE_ENV=production
-
-# OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
-ARG APP_VERSION
-LABEL org.opencontainers.image.title="ris-austria-mcp-server"
-LABEL org.opencontainers.image.description="Search Austrian consolidated federal & state law, court decisions, and the authentic Bundesgesetzblatt from the official RIS via MCP. Keyless. STDIO or Streamable HTTP."
-LABEL org.opencontainers.image.licenses="Apache-2.0"
-LABEL org.opencontainers.image.version="${APP_VERSION}"
-LABEL org.opencontainers.image.source="https://github.com/cyanheads/ris-austria-mcp-server"
-
-# Copy dependency manifests
-COPY package.json bun.lock ./
+# Copy dependency manifests. `bunfig.toml` rides along so every install below
+# passes its release-age gate and security scanner, as a local install does.
+COPY package.json bun.lock bunfig.toml ./
+
+# The scanner bunfig.toml names is a devDependency, and Bun installs a missing
+# scanner through the same production-filtered install, which omits it and
+# aborts. Seed it from the build stage's full install instead. Remove this line,
+# and the `rm` at the end of this stage, if bunfig.toml stops naming a scanner.
+COPY --from=build /usr/src/app/node_modules/@socketsecurity/bun-security-scanner ./node_modules/@socketsecurity/bun-security-scanner
+
+# Docker names the target architecture `amd64`/`arm64`; Bun's `--cpu` takes
+# `x64`/`arm64`. Mapped once here, read by both installs below. `oven/bun`
+# publishes only these two architectures, so any other target fails here.
+ARG TARGETOS
+ARG TARGETARCH
+RUN case "$TARGETARCH" in \
+      amd64) echo x64 ;; \
+      arm64) echo arm64 ;; \
+      *) echo "Unsupported TARGETARCH '$TARGETARCH': expected amd64 or arm64" >&2; exit 1 ;; \
+    esac > .bun-cpu
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
 # `--omit=peer` drops the framework's optional peer tiers (test runner, service
 # SDKs, parsers) that Bun would otherwise auto-install. Anything this server
 # actually imports belongs in its own `dependencies`, so nothing needed at
-# runtime is lost. The OTEL step below carries the same flag — without it, that
-# install re-resolves the graph and pulls every optional peer back in.
+# runtime is lost.
 RUN --mount=type=cache,target=/root/.bun/install/cache \
-    bun install --production --omit=peer --frozen-lockfile --ignore-scripts
+    bun install --production --omit=peer --frozen-lockfile --ignore-scripts \
+      --os="$TARGETOS" --cpu="$(cat .bun-cpu)"
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
-# These are not bundled by default to keep the base image lean. Enable at build time
-# with: docker build --build-arg OTEL_ENABLED=true
+# Installed by default. Omit them for a leaner image at build time
+# with: docker build --build-arg OTEL_ENABLED=false
+# The script reads the list and each range from the installed framework's
+# `peerDependencies` and passes the target flags on to its `bun install`.
+COPY scripts/install-otel.ts ./scripts/
 ARG OTEL_ENABLED=true
 RUN --mount=type=cache,target=/root/.bun/install/cache \
     if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
-        @opentelemetry/instrumentation-http \
-        @opentelemetry/exporter-metrics-otlp-http \
-        @opentelemetry/exporter-trace-otlp-http \
-        @opentelemetry/instrumentation-pino \
-        @opentelemetry/resources \
-        @opentelemetry/sdk-metrics \
-        @opentelemetry/sdk-node \
-        @opentelemetry/sdk-trace-node \
-        @opentelemetry/semantic-conventions; \
+      bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
     fi
 
+# `--os`/`--cpu` have no libc counterpart, so a native dependency published in
+# glibc and musl variants (DuckDB's bindings, for one) installs both. The
+# runtime image is Debian (glibc) and never loads the musl copy; the script
+# deletes every package whose own `libc` admits only musl. It follows every
+# install, since a later `bun install` restores what it removes. A server on a
+# musl (Alpine) runtime image drops these two lines.
+COPY scripts/prune-musl-packages.ts ./scripts/
+RUN bun scripts/prune-musl-packages.ts
+
+# The seeded scanner served only the installs above; keep it out of the image.
+RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
+
+
+# ==============================================================================
+# Production Stage
+#
+# This stage creates a minimal, optimized, and secure image for running the
+# application. It uses a slim base image and only includes production
+# dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
+# and CMD, which run on the real target at container start.
+# ==============================================================================
+FROM oven/bun:1.4.3-slim AS production
+
+WORKDIR /usr/src/app
+
+# Set the environment to production for performance.
+ENV NODE_ENV=production
+
+# OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
+ARG APP_VERSION
+LABEL org.opencontainers.image.title="ris-austria-mcp-server"
+LABEL org.opencontainers.image.description="Search Austrian consolidated federal & state law, court decisions, and the authentic Bundesgesetzblatt from the official RIS via MCP. Keyless. STDIO or Streamable HTTP."
+LABEL org.opencontainers.image.licenses="Apache-2.0"
+LABEL org.opencontainers.image.version="${APP_VERSION}"
+LABEL org.opencontainers.image.source="https://github.com/cyanheads/ris-austria-mcp-server"
+
+# The manifest comes from the build context: the deps stage's copy was rewritten
+# by the OTel install, and the runtime reads only its name, version, and type.
+COPY package.json ./
+COPY --from=deps /usr/src/app/node_modules ./node_modules
+
 # Copy the compiled application code from the build stage
 COPY --from=build /usr/src/app/dist ./dist
 
@@ -118,7 +175,6 @@ ENV MCP_TRANSPORT_TYPE="http"
 ENV MCP_SESSION_MODE="stateless"
 ENV MCP_LOG_LEVEL="info"
 ENV LOGS_DIR="/var/log/ris-austria-mcp-server"
-ENV MCP_FORCE_CONSOLE_LOGGING="true"
 
 # Expose the port the server listens on
 EXPOSE ${MCP_HTTP_PORT}

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.5.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/ris-austria-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/ris-austria-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/ris-austria-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.5.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/ris-austria-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/ris-austria-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/ris-austria-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -29,7 +29,7 @@
 
 ## Overview
 
-Austrian law from [RIS](https://www.ris.bka.gv.at/), the government's official legal information system: consolidated federal, state, and municipal law, case law from Austria's courts and tribunals, the authentic gazettes back to 1848, the pre-parliamentary lawmaking pipeline, and ministerial decrees. Covers all 39 applications of the keyless RIS OGD REST API (v2.6, CC BY 4.0) and labels every document with its binding status, since only the authentic (amtssigniert) gazette text is legally binding. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
+Austrian law from [RIS](https://www.ris.bka.gv.at/), the government's official legal information system: federal, state, and municipal law, court decisions, official gazettes back to 1848, draft legislation, and ministerial decrees. Every document is labeled with its binding status. No API key required.
 
 ### Tools
 
@@ -40,7 +40,7 @@ Austrian law from [RIS](https://www.ris.bka.gv.at/), the government's official l
 | `ris_search_gazette` | Browse the federal, state, district, and municipal gazettes, with federal history auto-routed back to 1848 |
 | `ris_search_drafts` | Search ministerial review drafts (Begutachtungsentwürfe) and government bills (Regierungsvorlagen) |
 | `ris_search_announcements` | Search seven sectoral collections, from social-insurance notices to ministerial decrees and council-of-ministers minutes |
-| `ris_lookup_citation` | Resolve one Austrian legal citation ("§ 6 DSG", "BGBl. I Nr. 165/1999", a Geschäftszahl) to its document |
+| `ris_lookup_citation` | Resolve one Austrian legal citation ("§ 6 DSG", "BGBl. I Nr. 165/1999", a Geschäftszahl or ECLI) to its document |
 | `ris_get_document` | Fetch one document as markdown, HTML, or XML, or just its rendition URLs, with its binding status |
 | `ris_track_changes` | List every document added, changed, or deleted in one application within a date window |
 | `ris_list_reference` | Look up RIS vocabularies offline: applications, courts, states, ministries, gazette parts, citation formats, search syntax |
@@ -59,14 +59,14 @@ The resource mirrors `ris_get_document`, so tool-only clients lose nothing.
 
 - `query` (full text) and `title` (title, short title, or abbreviation such as "DSG"); `scope` is `federal` (default) or a Bundesland, `municipality` switches a state scope to municipal law, and `language: english` searches the ~138 English translations
 - `in_force_as_of` defaults to today in Austria and is echoed as `appliedInForceAsOf`; `include_all_versions` and the `entered_force_*` / `left_force_*` windows are mutually exclusive alternatives
-- Records carry `law_id` (filter on it to get every section of a law), `section_label`, in-force dates, `eli`, `celex_references`, and `content_urls`; `section_from`/`section_to`, `index`, and `sort_by` narrow further
+- Records carry `law_id` (filter on it to get every section of a law), `section_label`, `abbreviation` and `keywords` where RIS assigns them, in-force dates, `eli`, `celex_references`, and `content_urls`; `section_from`/`section_to`, `index`, and `sort_by` narrow further
 
 ---
 
 ### `ris_search_case_law` <sub>tool</sub>
 
-- `court` is required, one code per call; filter by `query`, cited `norm` ("DSG §1"), `case_number`, `decided_from`/`decided_to`, `decision_type` (`headnote`, `full_text`, `all`), and court-conditional filters such as `court_name` (justiz), `state` (lvwg/uvs), or `collection_number` (vfgh/vwgh/uvs)
-- Records carry `case_numbers`, `decision_date`, `ecli`, `norms_cited`, and `guiding_principle` on headnotes; `court: normenliste` returns indexed laws under `norm_index` instead of decisions
+- `court` is required, one code per call; filter by `query`, cited `norm` ("DSG §1"), `case_number`, `decided_from`/`decided_to`, `decision_type` (`headnote`, `full_text`, or `all`, the default, for both), and court-conditional filters such as `court_name` (justiz), `state` (lvwg/uvs), or `collection_number` (vfgh/vwgh/uvs)
+- Records carry `case_numbers` (one per element; a headnote lists every decision it covers), `decision_date`, `ecli`, `norms_cited`, and `guiding_principle` on headnotes; `court: normenliste` returns indexed laws under `norm_index` instead of decisions
 - A conditional filter sent to the wrong court fails as `court_filter_mismatch` before any upstream call
 
 ---
@@ -76,6 +76,8 @@ The resource mirrors `ris_get_document`, so tool-only clients lose nothing.
 - `scope` is `federal` (default), a Bundesland, `district`, or `municipal`; filter by `number`, `part`, `type`, `published_from`/`published_to`, `issuer`, `district_authority`, or `municipality`. State scopes also take `series` (`law_gazette` / `ordinance_gazette`) and `state_era` (`current` / `legacy`)
 - Federal queries route to one era tier (BgblAuth 2004+, BgblPdf 1945–2003, BgblAlt 1848–1940), echoed as `servedApplication`; a date range crossing a tier boundary fails as `cross_tier_range` with the dates to split at
 - Records carry `binding` (`authentic`, `historical_record`, `consolidated_informational`), `authentic_pdf_url` where one exists, and `alex_url` (the ÖNB scan) for 1848–1940 entries
+- `celex_references` lists the EU acts an entry transposes (federal gazettes, LGBl, and Niederösterreich's LgblNO). LgblNO entries also carry `systematic_number` (Gliederungszahl) and `issue`, and 1848–1940 entries carry `issue` and `start_page`
+- Federal entries from 1848–2003 carry `promulgation`, the gazette that published them ("StGBl. Nr. 1/1945", "Staatsgesetzblatt für die Republik Österreich"), which tells apart two gazettes that share a `gazette_number`
 
 ---
 
@@ -91,13 +93,15 @@ The resource mirrors `ris_get_document`, so tool-only clients lose nothing.
 - `collection` is required: `social_insurance`, `veterinary`, `court_rules`, `trade_exam_rules`, `health_structure_plans`, `ministerial_decrees`, or `council_minutes`. Each accepts its own filter set, and a filter outside it fails as `collection_filter_mismatch`. That includes `changed_since` on `social_insurance` and `veterinary`, where RIS ignores it
 - `issuer` expands ministry abbreviations ("BMF") and social-insurance carrier abbreviations ("ÖGK")
 - Records carry `binding` (`authentic` for five collections, `administrative_directive` for decrees, `preparatory` for council minutes), `authentic_pdf_url`, and `document_url`, the only browsable view of council minutes and decrees
+- Records also carry each collection's own metadata where RIS supplies it: `case_numbers`, `type`, `in_force_from`/`in_force_until`, `keywords`, and `note`; a decree's `approved` date, `department`, `promulgation` (eJABl citation), and `norms_cited`; `court_name` on court rules, `plan_state` on health-structure plans, and `session_number` and `legislature` on council minutes
 
 ---
 
 ### `ris_lookup_citation` <sub>tool</sub>
 
-- One `citation` per call, auto-classified as a norm ("§ 6 DSG", "DSG §1"), gazette number ("BGBl. I Nr. 165/1999", "RGBl. Nr. 189/1902"), case number ("Ro 2026/03/0016"), or collection number ("VfSlg 19.632/2012"). `kind` forces a route, `court` and `state` hints narrow it, and `in_force_as_of` pins a norm's version (default today)
+- One `citation` per call, auto-classified as a norm ("§ 6 DSG", "DSG §1"), gazette number ("BGBl. I Nr. 165/1999", year-first "BGBl I 2018/24", "RGBl. Nr. 189/1902"), case number ("Ro 2026/03/0016", court-prefixed "VfGH G 13/2025") or ECLI ("ECLI:AT:VFGH:2026:G13.2025"), or collection number ("VfSlg 19.632/2012"). `kind` forces a route, `court` and `state` hints narrow it, and `in_force_as_of` pins a norm's version (default today)
 - Returns `found`, `kind`, and a `record` in the matching search tool's shape, with `alternatives_count` when more than one document matched. A miss returns `found: false` with `guidance` instead of an error
+- Matches are ranked before one is picked: a norm resolves to the cited law's abbreviation ("§ 2 EStG" → EStG 1988 § 2, not a Verordnung citing it), a case number to the decision text rather than a Rechtssatz, a gazette number to the gazette it cites ("StGBl. Nr. 1/1945" → the proclamation, not BGBl. Nr. 1/1945), and "BGBl. Nr. 50/2025" without its part comes back as ambiguous, naming parts I, II, and III
 
 ---
 
@@ -114,6 +118,7 @@ The resource mirrors `ris_get_document`, so tool-only clients lose nothing.
 
 - `application` (any of the 39 codes) plus `changed_from`/`changed_to`; `include_deleted` adds removals, which no other tool reports
 - Records carry `changed`, `published`, and `binding_status`; deletion records set `deleted: true` with `deleted_at`
+- Consolidated-law rows (BrKons, LrKons) carry `section_label` and `law_id`, and court-decision rows carry `case_numbers` and `decision_date`, so rows of one law or untitled decisions can be told apart without fetching each document
 
 ---
 

package/changelog/0.5.x/0.5.1.md

@@ -0,0 +1,33 @@
+---
+summary: "Framework ^0.13.6 → ^0.13.14: error envelopes carry a request ID and drop stack traces, request context, and rootCause; tool arguments sent as numeric or boolean strings, lone strings for arrays, or null optionals are repaired instead of rejected; registry npm entries launch via npx; the Docker image installs dependencies on the build platform."
+breaking: false
+security: false
+---
+
+# 0.5.1 — 2026-10-08
+
+## Changed
+
+- **Tool and resource error `data` carries `requestId`**, and a tool error's text closes with `request <id>` (mcp-ts-core 0.13.10).
+- **Error `data` no longer carries stack traces** (0.13.7), request context (0.13.8), or `rootCause` (0.13.13); fetch errors name a URL by origin only (0.13.12).
+- **Tool-argument pre-validation repairs more inputs instead of rejecting them**: an integer sent for a string and a JSON-stringified object (0.13.9); numeric or boolean strings, a lone string for an array, and `null` at an optional key (0.13.14).
+- **`ctx.fail` throw sites name only the reason**; the framework fills the declared `recovery` from the `errors[]` entry (0.13.10). Tests assert the hint on the contract path (`runToolContract`, the worker handler).
+- **`server.json` npm entries set `runtimeHint: "npx"`** and drop the `run start:*` arguments; the `streamable-http` entry fixes `MCP_TRANSPORT_TYPE` as `http` (0.13.11).
+- **Docker**: a `deps` stage on `$BUILDPLATFORM` cross-installs production dependencies with `--os`/`--cpu` and installs the OTel peers at the framework's declared ranges with `scripts/install-otel.ts` (0.13.10), then drops musl-only bindings with `scripts/prune-musl-packages.ts` (0.13.11), so a multi-arch build no longer runs Bun under QEMU; the image's installs pass `bunfig.toml`'s release-age gate and security scanner (0.13.8); base images `oven/bun` 1.4.0 → 1.4.2 (0.13.7); `ENV MCP_FORCE_CONSOLE_LOGGING` removed (0.13.8).
+- **`.dockerignore` excludes every `.env*` file** and the MCP Registry token files, and `.gitignore` ignores `.env*` except `.env.example`, `.env.template`, and `.env.sample` (0.13.11); `.mcpbignore` excludes `docs/idea.md` and `logs/` (0.13.9).
+- **`package.json`** adds `"!dist/*.mcpb"` to `files` (0.13.8) and sets `packageManager` `bun@1.4.2` (0.13.7).
+- **`.env.example`** documents the per-signal `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `_METRICS_ENDPOINT` (0.13.7), `LOG_TOOL_FAILURE_PAYLOADS`, `LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES`, and `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` (0.13.8), `MCP_REQUEST_STATE_KEY` (0.13.10), and `LOG_LLM_INTERACTIONS` (0.13.13).
+- **`.github/workflows/codeql.yml`** runs a per-language matrix (`actions`, `javascript-typescript`), each uploading under `/language:<language>` (0.13.11).
+- **Framework scripts resynced** (`devcheck`, `lint-mcp`, `lint-packaging`, `release-github`, `check-skill-versions`, `check-framework-antipatterns`): `lint:packaging` checks `"!dist/*.mcpb"` in `files` (0.13.8), the manifest version and the Dockerfile build platform (0.13.9, 0.13.10), and the `server.json` npm launch shape (0.13.11); `lint:mcp` fails on a definition or `server.json` it cannot load, and `release:github` validates the tag annotation (0.13.9); devcheck's TODO scan works on macOS and its secret-file scan covers root-level files (0.13.11); the antipattern gate's whitespace match works on macOS (0.13.13).
+- **`framework-skills/`** synced to mcp-ts-core 0.13.14; `CLAUDE.md`, `AGENTS.md`, and the README badges updated to the new framework, MCP SDK, and Bun versions.
+
+## Fixed
+
+- **`ris-service` debug log** `RIS content fetched` records the rendition file name (`file`) instead of the full URL, keeping URLs out of log fields as mcp-ts-core 0.13.12 does for its own records.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.6 → ^0.13.14 (`@modelcontextprotocol/server` ^2.0.0 → ^2.2.0, 0.13.9 and 0.13.11)
+- `pino-pretty` ^13.1.3 → ^13.2.0
+- dev: `@biomejs/biome` 2.5.14 → 2.5.15, `@types/node` ^26.6.2 → ^26.6.4, `ignore` ^7.0.9 → ^7.0.12, `tsc-alias` ^1.9.5 → ^1.9.7, `vitest` ^5.0.1 → ^5.0.3
+- lockfile only: `source-map-js` 1.2.1 → 1.2.2

package/changelog/0.5.x/0.5.2.md

@@ -0,0 +1,46 @@
+---
+summary: "ris_lookup_citation resolves ECLIs, court-prefixed and year-first cites, picks the cited document instead of the first hit, and parses citations in linear time; records gain abbreviation, keywords, CELEX, and decree fields; state parameters take German names; the server sends instructions."
+breaking: false
+security: true
+---
+
+# 0.5.2 — 2026-10-17
+
+## Added
+
+- **`ris_lookup_citation` resolves ECLIs** ("ECLI:AT:VFGH:2026:G13.2025"), **court-prefixed case numbers** ("VfGH G 13/2025"), and **year-first gazette cites** ("BGBl I 2018/24") ([#50](https://github.com/cyanheads/ris-austria-mcp-server/issues/50)).
+- **Server instructions** at `initialize`: the entry point per input, the `document_number` and application pairing, and the binding rule ([#57](https://github.com/cyanheads/ris-austria-mcp-server/issues/57)).
+- **`ris_search_gazette` records add `celex_references`** (`[]` when none), **`systematic_number`** (Niederösterreich Gliederungszahl), **`issue`**, and **`start_page`** ([#55](https://github.com/cyanheads/ris-austria-mcp-server/issues/55)), and **`promulgation`**, the gazette that carried a 1848–2003 federal entry ([#65](https://github.com/cyanheads/ris-austria-mcp-server/issues/65)).
+- **`ris_search_legislation` records add `keywords`** ([#63](https://github.com/cyanheads/ris-austria-mcp-server/issues/63)); RIS's `<br/>` keyword-group breaks join with a comma on every tool.
+- **`ris_track_changes` rows add `section_label` and `law_id`** (BrKons, LrKons) and **`case_numbers` and `decision_date`** (court decisions) ([#56](https://github.com/cyanheads/ris-austria-mcp-server/issues/56)).
+- **`ris_search_announcements` records add** `case_numbers`, `type`, `in_force_from`/`in_force_until`, `keywords`, `note`, `court_name`, `plan_state`, `session_number`, `legislature`, and a decree's `approved`, `department`, and `promulgation`; a decree's `norms_cited`, always empty before, is populated ([#54](https://github.com/cyanheads/ris-austria-mcp-server/issues/54)).
+
+## Changed
+
+- **State parameters accept German and English state names** ("Tirol", "niederösterreich", "Vienna") on `scope` (legislation, gazette), `state` (case law, lookup), and `plan_state` (announcements) ([#58](https://github.com/cyanheads/ris-austria-mcp-server/issues/58)).
+- **`ris_search_case_law` `decision_type: all` (the default) also searches decision texts on `vfgh`, `vwgh`, and `justiz`**, which returned Rechtssätze only, so totals rise ([#62](https://github.com/cyanheads/ris-austria-mcp-server/issues/62)).
+- **`ris_search_announcements` `type` is checked locally** on `court_rules`, `trade_exam_rules`, and `veterinary`, in any letter case; `trade_exam_rules` lists all five values and `Undefined` searches unfiltered ([#59](https://github.com/cyanheads/ris-austria-mcp-server/issues/59)).
+- **`ris_search_case_law` `issuing_body` is checked locally** on `dsk` and `pvak`, and `dsk` accepts `ParlamentarischesDatenschutzkomitee` (2025+) ([#61](https://github.com/cyanheads/ris-austria-mcp-server/issues/61)).
+- **A value rejected locally recovers by naming the field to correct**; its `invalid_query` recovery no longer opens with paging advice.
+- **`framework-skills/`** synced to mcp-ts-core 0.13.15; `CLAUDE.md`, `AGENTS.md`, and the README badges updated to the new framework, MCP SDK, and Bun versions; Dockerfile base images and `packageManager` move to Bun 1.4.3.
+
+## Fixed
+
+- **`ris_lookup_citation` picks the cited document, not the first hit** ([#48](https://github.com/cyanheads/ris-austria-mcp-server/issues/48)): a norm resolves to the law whose abbreviation is cited ("§ 2 EStG" → EStG 1988), a case number to its decision text before its Rechtssätze, and a gazette cite to the gazette it names. A partless "BGBl. Nr. 50/2025" matching parts I, II, and III returns `found: false` naming each.
+- **Geschäftszahl court detection** covers VfGH numbers without a space, VwGH `Fr`/`AW` and pre-2014 numbers, BVwG hyphenated and `I`-chamber numbers, and the LVwG formats ([#49](https://github.com/cyanheads/ris-austria-mcp-server/issues/49)).
+- **`ris_lookup_citation` "N more matched" recipe carries the filter that matched**, so running it lists the alternatives counted ([#64](https://github.com/cyanheads/ris-austria-mcp-server/issues/64)).
+- **"StGBl. Nr. 1/1945" resolves**; the 1918–1920 StGBl. and changeover-year numbers pick the cited gazette ([#65](https://github.com/cyanheads/ris-austria-mcp-server/issues/65)).
+- **`ris_search_legislation` `abbreviation` is populated** for consolidated federal and state law ([#51](https://github.com/cyanheads/ris-austria-mcp-server/issues/51)).
+- **`case_numbers` holds one Geschäftszahl per element**: a Justiz headnote's `;`-joined list and companions, and a VfGH headnote's comma-joined numbers, are split ([#53](https://github.com/cyanheads/ris-austria-mcp-server/issues/53)).
+- **`ris_get_document` markdown prints each Absatz, Ziffer, and litera under its RIS label**, with no generated list number ([#52](https://github.com/cyanheads/ris-austria-mcp-server/issues/52)), and escapes an ordinal ("1. Oktober") only where it would open a list item ([#60](https://github.com/cyanheads/ris-austria-mcp-server/issues/60)); the `ris://document` resource follows.
+
+## Security
+
+- **`ris_lookup_citation` parses citations in linear time**: its norm and gazette-number patterns were quadratic, so one long citation could hold the server's CPU for minutes.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.14 → ^0.13.15 (`@modelcontextprotocol/server` ^2.2.0 → ^2.3.1)
+- `zod` ^4.6.5 → ^4.6.7
+- dev: `@types/node` ^26.6.4 → ^26.6.5, `vitest` ^5.0.3 → ^5.0.4
+- Bun 1.4.2 → 1.4.3 (`packageManager`, Dockerfile)