Grounded v0.3.0

Image

ghcr.io/ncecere/grounded:v0.3.0
ghcr.io/ncecere/grounded@sha256:23c757c29c74beab26678829d6f31598c1e3543bbf4fef12bc413bf77916b176

Deploy by digest. Verify the signature (keyless, GitHub Actions OIDC):

cosign verify ghcr.io/ncecere/grounded@sha256:23c757c29c74beab26678829d6f31598c1e3543bbf4fef12bc413bf77916b176 \
  --certificate-identity-regexp '^https://github.com/ncecere/grounded/\.github/workflows/.+@refs/tags/v0.3.0$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The OCR sidecar (optional, components/ocr-tesseract), signed the same way:

ghcr.io/ncecere/grounded-ocr:v0.3.0
ghcr.io/ncecere/grounded-ocr@sha256:64646a50bc8bf40ce3cf75ec922cfbe7dfa7a53b247081ed4d825586835a6c21

Release assets

• grounded-v0.3.0-<os>-<arch>.sbom.spdx.json: the image's SBOM (SPDX JSON) for each platform, as attached to the image.
• grounded-v0.3.0.digest.txt: the image reference by digest.
• checksums.txt: SHA-256 of the files above (sha256sum -c checksums.txt).

The SBOM and build provenance are also attached to the image as attestations, which the signature covers:
docker buildx imagetools inspect ghcr.io/ncecere/grounded@sha256:23c757c29c74beab26678829d6f31598c1e3543bbf4fef12bc413bf77916b176 --format '{{ json .SBOM }}'.

Grounded v0.3.0

v0.3.0 is about reach. Through the Model Context Protocol (MCP), Grounded works in both directions: other AI tools search its knowledge bases and ask its agents, and its agents call tools on MCP servers a platform admin approved. It also stores the health of models, connections and MCP servers, and can trace one answer end to end with OpenTelemetry. Every new feature is off until a platform admin turns it on or configures it. The full list of changes is in the changelog, and the plan with the owner's decisions is in v0.3.0.md.

A walkthrough by role (platform admin, auditor, team owner and editor, member) came before this release, and its findings were fixed. v0.3.0-rc.1 runs on the reference install before v0.3.0 is tagged.

Highlights

• Grounded as an MCP server (mcp.md). Coding agents and desktop assistants connect to <APP_URL>/mcp (Streamable HTTP, protocol revision 2026-07-28, and older clients back to 2024-11-05) with an API key that has the new MCP scope. Two tools: search returns passages with their titles, headings, links and citation numbers; ask returns an agent's answer with [n] markers, citations and, when SystemOne checks citations, a verdict for each claim. Each tool lists exactly the knowledge bases and agents the key may use. Limits, budgets, classification and the audit log apply as on the REST API. Turn it on under Admin → Overview → Features → MCP server.
• OAuth sign-in for MCP clients (experimental). With it on, a person connects an AI tool by signing in to Grounded in their browser and approving the tool, with no API key to copy. Grounded is a small OAuth 2.1 authorization server for its own /mcp, in front of your sign-in provider. A token acts as the person over their current teams, and nothing on the REST API. Each person sees and disconnects their Connected apps; platform admins see and disconnect anyone's.
• MCP tools in agents (mcp-client.md). A platform admin registers a remote MCP server (Admin → Models → MCP servers), sets the most sensitive data it may receive, reads its tools and approves them one by one after reading their descriptions. Editors choose approved tools under Agent → Build → Tools. During an answer, calls are bounded (timeout, response size, the team's MCP tool calls per answer, at most 25), admitted by the team's budget, metered (optionally priced per call), audited without their arguments or results, and each result is cited as a numbered source that claim checks verify like a passage.
• Stored health (operations/health.md). Every Test of a connection, model or MCP server stores its result, and the worker re-tests enabled ones every 15 minutes at no cost. The lists show "Healthy · 3 minutes ago" or "Failing · since 2 hours ago" with a Health filter; failures appear under Needs attention on the admin Overview; the GroundedHealthCheckFailing alert fires after 30 minutes.
• OpenTelemetry tracing (operations/tracing.md). With OTEL_EXPORTER_OTLP_ENDPOINT set, one answer is one trace across the HTTP request, retrieval, model calls, SystemOne checks, MCP tool calls in both directions and background jobs. Spans carry IDs, counts and durations, never questions, answers, passages or tool arguments.
• Faster answers, and they say what they're doing. An answer's first words come sooner: a follow-up is rewritten into a search query only when it depends on the conversation, the search runs while the question's moderation and scope checks answer, and SystemOne passage judging waits at most a time limit (Admin → SystemOne → Passage judging time limit, 1.5 s by default; passages not judged by then are kept, as if unjudged). Until the first words, the chat says the step: "Understanding the question…", "Searching 's knowledge…", "Checking the passages…", "Writing the answer…" (or "Writing and checking the answer…" when answers are checked before they're shown).
• Reasoning effort. A chat model marked Accepts reasoning effort (Admin → Models → Compatibility) lets each agent choose low, medium or high (Build → Advanced), and query rewrites ask it for low effort. Publish is disabled while the draft has problems publishing would refuse, and says how many.
• A clearer audit log. Each entry says how the person acted: signed in, with an API key or through a connected app, by name. The platform log shows the caller's address. OAuth and tool-call entries say what happened ("App renewed its sign-in", "Connection revoked: a refresh token was reused (possible theft)", "An agent's MCP tool call was refused (call limit)").
• Quieter server errors. A request its client cancelled (a reload, a closed tab) is logged at info and counted as status 499, not as a 500 in the 5xx metrics and the error objective, and every log line uses the configured format.

Requirements

Unchanged from v0.2.0. Tracing needs an OTLP receiver (Tempo, Jaeger or an OpenTelemetry Collector) only if you turn it on.

Upgrading from v0.2.2

A rolling upgrade with no downtime. Take a backup as for any upgrade (operations/upgrades.md), then change every ?ref=v0.2.2 in your overlay to ?ref=v0.3.0 and pin the new digests of ghcr.io/ncecere/grounded and, if you run OCR, ghcr.io/ncecere/grounded-ocr.

Migrations 00035 to 00039 run on start (schema version 34 → 39). They are expand-only, so v0.2.2 pods keep working against the new schema while the rollout proceeds:

Migration	What it adds
00035_mcp_server	The MCP server switch (a new one-row table, off), and mcp in the API-key scope and answer-channel constraints (widened, validated without locking writes)
00036_health_checks	The health_checks table and the health_subjects view
00037_mcp_client	MCP servers, their tools and approvals, the tools of each agent version, the mcp_calls price unit and the mcp_server health kind (new tables; constraints widened)
00038_mcp_oauth	The OAuth sign-in setting (a column on mcp_settings, off) and the OAuth clients, grants, codes and tokens tables
00039_message_retrieval	The retrieval step of an answer (a nullable column on messages), so a reopened answer shows its "Searched the knowledge base for …" step

New settings (all optional; .env.example describes each):

Setting	Default	What it does
HEALTH_CHECK_INTERVAL	15m	How often the worker re-tests enabled connections, models and MCP servers (5m to 24h, or off). It sends no completions, embeddings or tool calls
OTEL_EXPORTER_OTLP_ENDPOINT	unset (tracing off)	The OTLP receiver. Tracing stays off without it
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf	Or grpc
OTEL_EXPORTER_OTLP_HEADERS	unset	Headers for the receiver, such as a token (also OTEL_EXPORTER_OTLP_HEADERS_FILE); a secret, never logged
OTEL_SERVICE_NAME	grounded	The service name on spans
OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG	parentbased_traceidratio, 1.0	Which traces are kept. Invalid values stop the process at start

Kubernetes: the new optional component components/tracing sets the OTLP endpoint (a placeholder to patch) and adds egress to the collector on TCP 4318 (4317 for gRPC) in the monitoring namespace. It isn't in the base. MCP servers are reached through the existing grounded-app-egress-web policy (TCP 80 and 443); a server on another port needs its own egress rule. /mcp, /oauth/… and /.well-known/oauth-… are served by the api pods behind the same ingress, so nothing changes there. The alert rules and dashboards gain the health metrics and GroundedHealthCheckFailing: regenerate your copies if you vendor them.

Things people will notice:

• Admin → Overview → Features has two new rows, MCP server and OAuth sign-in for MCP clients, both off.
• Admin → Models has an MCP servers page, and Connections, Models and MCP servers have a Health column. Existing connections and models show "Not tested yet" until the first scheduled check, a few minutes after the worker starts.
• API keys have a new MCP scope, and people who connect an AI tool through OAuth see it under Connected apps.
• Agent → Build has a Tools section. It only lists tools once a platform admin has approved some, and the agent's chat model must support tools (a platform admin ticks **S...

Grounded v0.3.0-rc.4

Release candidate for v0.3.0. Test it before relying on it; the final release follows.

Image

ghcr.io/ncecere/grounded:v0.3.0-rc.4
ghcr.io/ncecere/grounded@sha256:26c77bec7387c4e9c228e315ea364a75a6fba41923a170366c33d7f28f13b9d8

Deploy by digest. Verify the signature (keyless, GitHub Actions OIDC):

cosign verify ghcr.io/ncecere/grounded@sha256:26c77bec7387c4e9c228e315ea364a75a6fba41923a170366c33d7f28f13b9d8 \
  --certificate-identity-regexp '^https://github.com/ncecere/grounded/\.github/workflows/.+@refs/tags/v0.3.0-rc.4$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The OCR sidecar (optional, components/ocr-tesseract), signed the same way:

ghcr.io/ncecere/grounded-ocr:v0.3.0-rc.4
ghcr.io/ncecere/grounded-ocr@sha256:52f940d5ea68e2a3bd6c567a32f5ee20b4f0f3438a8de7b67901b4a16e8231c9

Release assets

• grounded-v0.3.0-rc.4-<os>-<arch>.sbom.spdx.json: the image's SBOM (SPDX JSON) for each platform, as attached to the image.
• grounded-v0.3.0-rc.4.digest.txt: the image reference by digest.
• checksums.txt: SHA-256 of the files above (sha256sum -c checksums.txt).

The SBOM and build provenance are also attached to the image as attestations, which the signature covers:
docker buildx imagetools inspect ghcr.io/ncecere/grounded@sha256:26c77bec7387c4e9c228e315ea364a75a6fba41923a170366c33d7f28f13b9d8 --format '{{ json .SBOM }}'.

Grounded v0.3.0

v0.3.0 is about reach. Through the Model Context Protocol (MCP), Grounded works in both directions: other AI tools search its knowledge bases and ask its agents, and its agents call tools on MCP servers a platform admin approved. It also stores the health of models, connections and MCP servers, and can trace one answer end to end with OpenTelemetry. Every new feature is off until a platform admin turns it on or configures it. The full list of changes is in the changelog, and the plan with the owner's decisions is in v0.3.0.md.

A walkthrough by role (platform admin, auditor, team owner and editor, member) came before this release, and its findings were fixed. v0.3.0-rc.1 runs on the reference install before v0.3.0 is tagged.

Highlights

• Grounded as an MCP server (mcp.md). Coding agents and desktop assistants connect to <APP_URL>/mcp (Streamable HTTP, protocol revision 2026-07-28, and older clients back to 2024-11-05) with an API key that has the new MCP scope. Two tools: search returns passages with their titles, headings, links and citation numbers; ask returns an agent's answer with [n] markers, citations and, when SystemOne checks citations, a verdict for each claim. Each tool lists exactly the knowledge bases and agents the key may use. Limits, budgets, classification and the audit log apply as on the REST API. Turn it on under Admin → Overview → Features → MCP server.
• OAuth sign-in for MCP clients (experimental). With it on, a person connects an AI tool by signing in to Grounded in their browser and approving the tool, with no API key to copy. Grounded is a small OAuth 2.1 authorization server for its own /mcp, in front of your sign-in provider. A token acts as the person over their current teams, and nothing on the REST API. Each person sees and disconnects their Connected apps; platform admins see and disconnect anyone's.
• MCP tools in agents (mcp-client.md). A platform admin registers a remote MCP server (Admin → Models → MCP servers), sets the most sensitive data it may receive, reads its tools and approves them one by one after reading their descriptions. Editors choose approved tools under Agent → Build → Tools. During an answer, calls are bounded (timeout, response size, the team's MCP tool calls per answer, at most 25), admitted by the team's budget, metered (optionally priced per call), audited without their arguments or results, and each result is cited as a numbered source that claim checks verify like a passage.
• Stored health (operations/health.md). Every Test of a connection, model or MCP server stores its result, and the worker re-tests enabled ones every 15 minutes at no cost. The lists show "Healthy · 3 minutes ago" or "Failing · since 2 hours ago" with a Health filter; failures appear under Needs attention on the admin Overview; the GroundedHealthCheckFailing alert fires after 30 minutes.
• OpenTelemetry tracing (operations/tracing.md). With OTEL_EXPORTER_OTLP_ENDPOINT set, one answer is one trace across the HTTP request, retrieval, model calls, SystemOne checks, MCP tool calls in both directions and background jobs. Spans carry IDs, counts and durations, never questions, answers, passages or tool arguments.
• A clearer audit log. Each entry says how the person acted: signed in, with an API key or through a connected app, by name. The platform log shows the caller's address. OAuth and tool-call entries say what happened ("App renewed its sign-in", "Connection revoked: a refresh token was reused (possible theft)", "An agent's MCP tool call was refused (call limit)").
• Quieter server errors. A request its client cancelled (a reload, a closed tab) is logged at info and counted as status 499, not as a 500 in the 5xx metrics and the error objective, and every log line uses the configured format.

Requirements

Unchanged from v0.2.0. Tracing needs an OTLP receiver (Tempo, Jaeger or an OpenTelemetry Collector) only if you turn it on.

Upgrading from v0.2.2

A rolling upgrade with no downtime. Take a backup as for any upgrade (operations/upgrades.md), then change every ?ref=v0.2.2 in your overlay to ?ref=v0.3.0 and pin the new digests of ghcr.io/ncecere/grounded and, if you run OCR, ghcr.io/ncecere/grounded-ocr.

Migrations 00035 to 00039 run on start (schema version 34 → 39). They are expand-only, so v0.2.2 pods keep working against the new schema while the rollout proceeds:

Migration	What it adds
00035_mcp_server	The MCP server switch (a new one-row table, off), and mcp in the API-key scope and answer-channel constraints (widened, validated without locking writes)
00036_health_checks	The health_checks table and the health_subjects view
00037_mcp_client	MCP servers, their tools and approvals, the tools of each agent version, the mcp_calls price unit and the mcp_server health kind (new tables; constraints widened)
00038_mcp_oauth	The OAuth sign-in setting (a column on mcp_settings, off) and the OAuth clients, grants, codes and tokens tables
00039_message_retrieval	The retrieval step of an answer (a nullable column on messages), so a reopened answer shows its "Searched the knowledge base for …" step

New settings (all optional; .env.example describes each):

Setting	Default	What it does
HEALTH_CHECK_INTERVAL	15m	How often the worker re-tests enabled connections, models and MCP servers (5m to 24h, or off). It sends no completions, embeddings or tool calls
OTEL_EXPORTER_OTLP_ENDPOINT	unset (tracing off)	The OTLP receiver. Tracing stays off without it
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf	Or grpc
OTEL_EXPORTER_OTLP_HEADERS	unset	Headers for the receiver, such as a token (also OTEL_EXPORTER_OTLP_HEADERS_FILE); a secret, never logged
OTEL_SERVICE_NAME	grounded	The service name on spans
OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG	parentbased_traceidratio, 1.0	Which traces are kept. Invalid values stop the process at start

Kubernetes: the new optional component components/tracing sets the OTLP endpoint (a placeholder to patch) and adds egress to the collector on TCP 4318 (4317 for gRPC) in the monitoring namespace. It isn't in the base. MCP servers are reached through the existing grounded-app-egress-web policy (TCP 80 and 443); a server on another port needs its own egress rule. /mcp, /oauth/… and /.well-known/oauth-… are served by the api pods behind the same ingress, so nothing changes there. The alert rules and dashboards gain the health metrics and GroundedHealthCheckFailing: regenerate your copies if you vendor them.

Things people will notice:

• Admin → Overview → Features has two new rows, MCP server and OAuth sign-in for MCP clients, both off.
• Admin → Models has an MCP servers page, and Connections, Models and MCP servers have a Health column. Existing connections and models show "Not tested yet" until the first scheduled check, a few minutes after the worker starts.
• API keys have a new MCP scope, and people who connect an AI tool through OAuth see it under Connected apps.
• Agent → Build has a Tools section. It only lists tools once a platform admin has approved some, and the agent's chat model must support tools (a platform admin ticks Supports tool calling on the model in Admin → Models).
• Limits → Queries & chat has MCP tool calls per answer (default 5, at most 25), and Costs has an MCP tools spend category.
• The audit log has the areas and actions of the new features (mcp.*, mcp_server.*, mcp_tool.*, oauth.*, platform.mcp, platform.mcp_oauth), and each entry says how the person acted.
• Metrics: new grounded_mcp_tool_calls_total, grounded_mcp_client_calls_total, grounded_mcp_client_call_duration_seconds, grounded_health_failing, grounded_health_failing_seconds, grounded_health_checks_total and grounded_health_check_duration_seconds; the route group mcp, outside the latency objective; and status 499 for requests the client cancelled (operations/monitoring.md).
• API (additive): the MCP server, MCP server...

Grounded v0.3.0-rc.3

Release candidate for v0.3.0. Test it before relying on it; the final release follows.

Image

ghcr.io/ncecere/grounded:v0.3.0-rc.3
ghcr.io/ncecere/grounded@sha256:c60e70c98f5fce8ebca5c6fcfd4f1858a039572025acc820fa0c54d044871bdb

Deploy by digest. Verify the signature (keyless, GitHub Actions OIDC):

cosign verify ghcr.io/ncecere/grounded@sha256:c60e70c98f5fce8ebca5c6fcfd4f1858a039572025acc820fa0c54d044871bdb \
  --certificate-identity-regexp '^https://github.com/ncecere/grounded/\.github/workflows/.+@refs/tags/v0.3.0-rc.3$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The OCR sidecar (optional, components/ocr-tesseract), signed the same way:

ghcr.io/ncecere/grounded-ocr:v0.3.0-rc.3
ghcr.io/ncecere/grounded-ocr@sha256:ba03740f065bb0f2c381f5bbc54e4c9c67800dea987bdc914e24e57f5eeb9593

Release assets

• grounded-v0.3.0-rc.3-<os>-<arch>.sbom.spdx.json: the image's SBOM (SPDX JSON) for each platform, as attached to the image.
• grounded-v0.3.0-rc.3.digest.txt: the image reference by digest.
• checksums.txt: SHA-256 of the files above (sha256sum -c checksums.txt).

The SBOM and build provenance are also attached to the image as attestations, which the signature covers:
docker buildx imagetools inspect ghcr.io/ncecere/grounded@sha256:c60e70c98f5fce8ebca5c6fcfd4f1858a039572025acc820fa0c54d044871bdb --format '{{ json .SBOM }}'.

Grounded v0.3.0

v0.3.0 is about reach. Through the Model Context Protocol (MCP), Grounded works in both directions: other AI tools search its knowledge bases and ask its agents, and its agents call tools on MCP servers a platform admin approved. It also stores the health of models, connections and MCP servers, and can trace one answer end to end with OpenTelemetry. Every new feature is off until a platform admin turns it on or configures it. The full list of changes is in the changelog, and the plan with the owner's decisions is in v0.3.0.md.

A walkthrough by role (platform admin, auditor, team owner and editor, member) came before this release, and its findings were fixed. v0.3.0-rc.1 runs on the reference install before v0.3.0 is tagged.

Highlights

• Grounded as an MCP server (mcp.md). Coding agents and desktop assistants connect to <APP_URL>/mcp (Streamable HTTP, protocol revision 2026-07-28, and older clients back to 2024-11-05) with an API key that has the new MCP scope. Two tools: search returns passages with their titles, headings, links and citation numbers; ask returns an agent's answer with [n] markers, citations and, when SystemOne checks citations, a verdict for each claim. Each tool lists exactly the knowledge bases and agents the key may use. Limits, budgets, classification and the audit log apply as on the REST API. Turn it on under Admin → Overview → Features → MCP server.
• OAuth sign-in for MCP clients (experimental). With it on, a person connects an AI tool by signing in to Grounded in their browser and approving the tool, with no API key to copy. Grounded is a small OAuth 2.1 authorization server for its own /mcp, in front of your sign-in provider. A token acts as the person over their current teams, and nothing on the REST API. Each person sees and disconnects their Connected apps; platform admins see and disconnect anyone's.
• MCP tools in agents (mcp-client.md). A platform admin registers a remote MCP server (Admin → Models → MCP servers), sets the most sensitive data it may receive, reads its tools and approves them one by one after reading their descriptions. Editors choose approved tools under Agent → Build → Tools. During an answer, calls are bounded (timeout, response size, the team's MCP tool calls per answer, at most 25), admitted by the team's budget, metered (optionally priced per call), audited without their arguments or results, and each result is cited as a numbered source that claim checks verify like a passage.
• Stored health (operations/health.md). Every Test of a connection, model or MCP server stores its result, and the worker re-tests enabled ones every 15 minutes at no cost. The lists show "Healthy · 3 minutes ago" or "Failing · since 2 hours ago" with a Health filter; failures appear under Needs attention on the admin Overview; the GroundedHealthCheckFailing alert fires after 30 minutes.
• OpenTelemetry tracing (operations/tracing.md). With OTEL_EXPORTER_OTLP_ENDPOINT set, one answer is one trace across the HTTP request, retrieval, model calls, SystemOne checks, MCP tool calls in both directions and background jobs. Spans carry IDs, counts and durations, never questions, answers, passages or tool arguments.
• A clearer audit log. Each entry says how the person acted: signed in, with an API key or through a connected app, by name. The platform log shows the caller's address. OAuth and tool-call entries say what happened ("App renewed its sign-in", "Connection revoked: a refresh token was reused (possible theft)", "An agent's MCP tool call was refused (call limit)").
• Quieter server errors. A request its client cancelled (a reload, a closed tab) is logged at info and counted as status 499, not as a 500 in the 5xx metrics and the error objective, and every log line uses the configured format.

Requirements

Unchanged from v0.2.0. Tracing needs an OTLP receiver (Tempo, Jaeger or an OpenTelemetry Collector) only if you turn it on.

Upgrading from v0.2.2

A rolling upgrade with no downtime. Take a backup as for any upgrade (operations/upgrades.md), then change every ?ref=v0.2.2 in your overlay to ?ref=v0.3.0 and pin the new digests of ghcr.io/ncecere/grounded and, if you run OCR, ghcr.io/ncecere/grounded-ocr.

Migrations 00035 to 00039 run on start (schema version 34 → 39). They are expand-only, so v0.2.2 pods keep working against the new schema while the rollout proceeds:

Migration	What it adds
00035_mcp_server	The MCP server switch (a new one-row table, off), and mcp in the API-key scope and answer-channel constraints (widened, validated without locking writes)
00036_health_checks	The health_checks table and the health_subjects view
00037_mcp_client	MCP servers, their tools and approvals, the tools of each agent version, the mcp_calls price unit and the mcp_server health kind (new tables; constraints widened)
00038_mcp_oauth	The OAuth sign-in setting (a column on mcp_settings, off) and the OAuth clients, grants, codes and tokens tables
00039_message_retrieval	The retrieval step of an answer (a nullable column on messages), so a reopened answer shows its "Searched the knowledge base for …" step

New settings (all optional; .env.example describes each):

Setting	Default	What it does
HEALTH_CHECK_INTERVAL	15m	How often the worker re-tests enabled connections, models and MCP servers (5m to 24h, or off). It sends no completions, embeddings or tool calls
OTEL_EXPORTER_OTLP_ENDPOINT	unset (tracing off)	The OTLP receiver. Tracing stays off without it
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf	Or grpc
OTEL_EXPORTER_OTLP_HEADERS	unset	Headers for the receiver, such as a token (also OTEL_EXPORTER_OTLP_HEADERS_FILE); a secret, never logged
OTEL_SERVICE_NAME	grounded	The service name on spans
OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG	parentbased_traceidratio, 1.0	Which traces are kept. Invalid values stop the process at start

Kubernetes: the new optional component components/tracing sets the OTLP endpoint (a placeholder to patch) and adds egress to the collector on TCP 4318 (4317 for gRPC) in the monitoring namespace. It isn't in the base. MCP servers are reached through the existing grounded-app-egress-web policy (TCP 80 and 443); a server on another port needs its own egress rule. /mcp, /oauth/… and /.well-known/oauth-… are served by the api pods behind the same ingress, so nothing changes there. The alert rules and dashboards gain the health metrics and GroundedHealthCheckFailing: regenerate your copies if you vendor them.

Things people will notice:

• Admin → Overview → Features has two new rows, MCP server and OAuth sign-in for MCP clients, both off.
• Admin → Models has an MCP servers page, and Connections, Models and MCP servers have a Health column. Existing connections and models show "Not tested yet" until the first scheduled check, a few minutes after the worker starts.
• API keys have a new MCP scope, and people who connect an AI tool through OAuth see it under Connected apps.
• Agent → Build has a Tools section. It only lists tools once a platform admin has approved some, and the agent's chat model must support tools (a platform admin ticks Supports tool calling on the model in Admin → Models).
• Limits → Queries & chat has MCP tool calls per answer (default 5, at most 25), and Costs has an MCP tools spend category.
• The audit log has the areas and actions of the new features (mcp.*, mcp_server.*, mcp_tool.*, oauth.*, platform.mcp, platform.mcp_oauth), and each entry says how the person acted.
• Metrics: new grounded_mcp_tool_calls_total, grounded_mcp_client_calls_total, grounded_mcp_client_call_duration_seconds, grounded_health_failing, grounded_health_failing_seconds, grounded_health_checks_total and grounded_health_check_duration_seconds; the route group mcp, outside the latency objective; and status 499 for requests the client cancelled (operations/monitoring.md).
• API (additive): the MCP server, MCP server...

Grounded v0.3.0-rc.2

Release candidate for v0.3.0. Test it before relying on it; the final release follows.

Image

ghcr.io/ncecere/grounded:v0.3.0-rc.2
ghcr.io/ncecere/grounded@sha256:cd67ba93ce48d2cda39fed582b00d24f1a86d129daf8ee6ca78b5a047e31ea34

Deploy by digest. Verify the signature (keyless, GitHub Actions OIDC):

cosign verify ghcr.io/ncecere/grounded@sha256:cd67ba93ce48d2cda39fed582b00d24f1a86d129daf8ee6ca78b5a047e31ea34 \
  --certificate-identity-regexp '^https://github.com/ncecere/grounded/\.github/workflows/.+@refs/tags/v0.3.0-rc.2$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The OCR sidecar (optional, components/ocr-tesseract), signed the same way:

ghcr.io/ncecere/grounded-ocr:v0.3.0-rc.2
ghcr.io/ncecere/grounded-ocr@sha256:bc444838893b7244c807e1589ce1c4ef42e2e97b9a48dba9205f370868c71665

Release assets

• grounded-v0.3.0-rc.2-<os>-<arch>.sbom.spdx.json: the image's SBOM (SPDX JSON) for each platform, as attached to the image.
• grounded-v0.3.0-rc.2.digest.txt: the image reference by digest.
• checksums.txt: SHA-256 of the files above (sha256sum -c checksums.txt).

The SBOM and build provenance are also attached to the image as attestations, which the signature covers:
docker buildx imagetools inspect ghcr.io/ncecere/grounded@sha256:cd67ba93ce48d2cda39fed582b00d24f1a86d129daf8ee6ca78b5a047e31ea34 --format '{{ json .SBOM }}'.

Grounded v0.3.0

v0.3.0 is about reach. Through the Model Context Protocol (MCP), Grounded works in both directions: other AI tools search its knowledge bases and ask its agents, and its agents call tools on MCP servers a platform admin approved. It also stores the health of models, connections and MCP servers, and can trace one answer end to end with OpenTelemetry. Every new feature is off until a platform admin turns it on or configures it. The full list of changes is in the changelog, and the plan with the owner's decisions is in v0.3.0.md.

A walkthrough by role (platform admin, auditor, team owner and editor, member) came before this release, and its findings were fixed. v0.3.0-rc.1 runs on the reference install before v0.3.0 is tagged.

Highlights

• Grounded as an MCP server (mcp.md). Coding agents and desktop assistants connect to <APP_URL>/mcp (Streamable HTTP, protocol revision 2026-07-28, and older clients back to 2024-11-05) with an API key that has the new MCP scope. Two tools: search returns passages with their titles, headings, links and citation numbers; ask returns an agent's answer with [n] markers, citations and, when SystemOne checks citations, a verdict for each claim. Each tool lists exactly the knowledge bases and agents the key may use. Limits, budgets, classification and the audit log apply as on the REST API. Turn it on under Admin → Overview → Features → MCP server.
• OAuth sign-in for MCP clients (experimental). With it on, a person connects an AI tool by signing in to Grounded in their browser and approving the tool, with no API key to copy. Grounded is a small OAuth 2.1 authorization server for its own /mcp, in front of your sign-in provider. A token acts as the person over their current teams, and nothing on the REST API. Each person sees and disconnects their Connected apps; platform admins see and disconnect anyone's.
• MCP tools in agents (mcp-client.md). A platform admin registers a remote MCP server (Admin → Models → MCP servers), sets the most sensitive data it may receive, reads its tools and approves them one by one after reading their descriptions. Editors choose approved tools under Agent → Build → Tools. During an answer, calls are bounded (timeout, response size, the team's MCP tool calls per answer, at most 25), admitted by the team's budget, metered (optionally priced per call), audited without their arguments or results, and each result is cited as a numbered source that claim checks verify like a passage.
• Stored health (operations/health.md). Every Test of a connection, model or MCP server stores its result, and the worker re-tests enabled ones every 15 minutes at no cost. The lists show "Healthy · 3 minutes ago" or "Failing · since 2 hours ago" with a Health filter; failures appear under Needs attention on the admin Overview; the GroundedHealthCheckFailing alert fires after 30 minutes.
• OpenTelemetry tracing (operations/tracing.md). With OTEL_EXPORTER_OTLP_ENDPOINT set, one answer is one trace across the HTTP request, retrieval, model calls, SystemOne checks, MCP tool calls in both directions and background jobs. Spans carry IDs, counts and durations, never questions, answers, passages or tool arguments.
• A clearer audit log. Each entry says how the person acted: signed in, with an API key or through a connected app, by name. The platform log shows the caller's address. OAuth and tool-call entries say what happened ("App renewed its sign-in", "Connection revoked: a refresh token was reused (possible theft)", "An agent's MCP tool call was refused (call limit)").
• Quieter server errors. A request its client cancelled (a reload, a closed tab) is logged at info and counted as status 499, not as a 500 in the 5xx metrics and the error objective, and every log line uses the configured format.

Requirements

Unchanged from v0.2.0. Tracing needs an OTLP receiver (Tempo, Jaeger or an OpenTelemetry Collector) only if you turn it on.

Upgrading from v0.2.2

A rolling upgrade with no downtime. Take a backup as for any upgrade (operations/upgrades.md), then change every ?ref=v0.2.2 in your overlay to ?ref=v0.3.0 and pin the new digests of ghcr.io/ncecere/grounded and, if you run OCR, ghcr.io/ncecere/grounded-ocr.

Migrations 00035 to 00039 run on start (schema version 34 → 39). They are expand-only, so v0.2.2 pods keep working against the new schema while the rollout proceeds:

Migration	What it adds
00035_mcp_server	The MCP server switch (a new one-row table, off), and mcp in the API-key scope and answer-channel constraints (widened, validated without locking writes)
00036_health_checks	The health_checks table and the health_subjects view
00037_mcp_client	MCP servers, their tools and approvals, the tools of each agent version, the mcp_calls price unit and the mcp_server health kind (new tables; constraints widened)
00038_mcp_oauth	The OAuth sign-in setting (a column on mcp_settings, off) and the OAuth clients, grants, codes and tokens tables
00039_message_retrieval	The retrieval step of an answer (a nullable column on messages), so a reopened answer shows its "Searched the knowledge base for …" step

New settings (all optional; .env.example describes each):

Setting	Default	What it does
HEALTH_CHECK_INTERVAL	15m	How often the worker re-tests enabled connections, models and MCP servers (5m to 24h, or off). It sends no completions, embeddings or tool calls
OTEL_EXPORTER_OTLP_ENDPOINT	unset (tracing off)	The OTLP receiver. Tracing stays off without it
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf	Or grpc
OTEL_EXPORTER_OTLP_HEADERS	unset	Headers for the receiver, such as a token (also OTEL_EXPORTER_OTLP_HEADERS_FILE); a secret, never logged
OTEL_SERVICE_NAME	grounded	The service name on spans
OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG	parentbased_traceidratio, 1.0	Which traces are kept. Invalid values stop the process at start

Kubernetes: the new optional component components/tracing sets the OTLP endpoint (a placeholder to patch) and adds egress to the collector on TCP 4318 (4317 for gRPC) in the monitoring namespace. It isn't in the base. MCP servers are reached through the existing grounded-app-egress-web policy (TCP 80 and 443); a server on another port needs its own egress rule. /mcp, /oauth/… and /.well-known/oauth-… are served by the api pods behind the same ingress, so nothing changes there. The alert rules and dashboards gain the health metrics and GroundedHealthCheckFailing: regenerate your copies if you vendor them.

Things people will notice:

• Admin → Overview → Features has two new rows, MCP server and OAuth sign-in for MCP clients, both off.
• Admin → Models has an MCP servers page, and Connections, Models and MCP servers have a Health column. Existing connections and models show "Not tested yet" until the first scheduled check, a few minutes after the worker starts.
• API keys have a new MCP scope, and people who connect an AI tool through OAuth see it under Connected apps.
• Agent → Build has a Tools section. It only lists tools once a platform admin has approved some, and the agent's chat model must support tools (a platform admin ticks Supports tool calling on the model in Admin → Models).
• Limits → Queries & chat has MCP tool calls per answer (default 5, at most 25), and Costs has an MCP tools spend category.
• The audit log has the areas and actions of the new features (mcp.*, mcp_server.*, mcp_tool.*, oauth.*, platform.mcp, platform.mcp_oauth), and each entry says how the person acted.
• Metrics: new grounded_mcp_tool_calls_total, grounded_mcp_client_calls_total, grounded_mcp_client_call_duration_seconds, grounded_health_failing, grounded_health_failing_seconds, grounded_health_checks_total and grounded_health_check_duration_seconds; the route group mcp, outside the latency objective; and status 499 for requests the client cancelled (operations/monitoring.md).
• API (additive): the MCP server, MCP server...

Grounded v0.3.0-rc.1

Release candidate for v0.3.0. Test it before relying on it; the final release follows.

Image

ghcr.io/ncecere/grounded:v0.3.0-rc.1
ghcr.io/ncecere/grounded@sha256:6891af6a2006ab096a2640fe7e92d58da19ea45fdf4435cf54fa4c8500c2db38

Deploy by digest. Verify the signature (keyless, GitHub Actions OIDC):

cosign verify ghcr.io/ncecere/grounded@sha256:6891af6a2006ab096a2640fe7e92d58da19ea45fdf4435cf54fa4c8500c2db38 \
  --certificate-identity-regexp '^https://github.com/ncecere/grounded/\.github/workflows/.+@refs/tags/v0.3.0-rc.1$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The OCR sidecar (optional, components/ocr-tesseract), signed the same way:

ghcr.io/ncecere/grounded-ocr:v0.3.0-rc.1
ghcr.io/ncecere/grounded-ocr@sha256:9997e6128f439e291f12b0f4bb35157985a45bda7f39c78393abdb25662f2a5f

Release assets

• grounded-v0.3.0-rc.1-<os>-<arch>.sbom.spdx.json: the image's SBOM (SPDX JSON) for each platform, as attached to the image.
• grounded-v0.3.0-rc.1.digest.txt: the image reference by digest.
• checksums.txt: SHA-256 of the files above (sha256sum -c checksums.txt).

The SBOM and build provenance are also attached to the image as attestations, which the signature covers:
docker buildx imagetools inspect ghcr.io/ncecere/grounded@sha256:6891af6a2006ab096a2640fe7e92d58da19ea45fdf4435cf54fa4c8500c2db38 --format '{{ json .SBOM }}'.

Grounded v0.3.0

v0.3.0 is about reach. Through the Model Context Protocol (MCP), Grounded works in both directions: other AI tools search its knowledge bases and ask its agents, and its agents call tools on MCP servers a platform admin approved. It also stores the health of models, connections and MCP servers, and can trace one answer end to end with OpenTelemetry. Every new feature is off until a platform admin turns it on or configures it. The full list of changes is in the changelog, and the plan with the owner's decisions is in v0.3.0.md.

A walkthrough by role (platform admin, auditor, team owner and editor, member) came before this release, and its findings were fixed. v0.3.0-rc.1 runs on the reference install before v0.3.0 is tagged.

Highlights

• Grounded as an MCP server (mcp.md). Coding agents and desktop assistants connect to <APP_URL>/mcp (Streamable HTTP, protocol revision 2026-07-28, and older clients back to 2024-11-05) with an API key that has the new MCP scope. Two tools: search returns passages with their titles, headings, links and citation numbers; ask returns an agent's answer with [n] markers, citations and, when SystemOne checks citations, a verdict for each claim. Each tool lists exactly the knowledge bases and agents the key may use. Limits, budgets, classification and the audit log apply as on the REST API. Turn it on under Admin → Overview → Features → MCP server.
• OAuth sign-in for MCP clients (experimental). With it on, a person connects an AI tool by signing in to Grounded in their browser and approving the tool, with no API key to copy. Grounded is a small OAuth 2.1 authorization server for its own /mcp, in front of your sign-in provider. A token acts as the person over their current teams, and nothing on the REST API. Each person sees and disconnects their Connected apps; platform admins see and disconnect anyone's.
• MCP tools in agents (mcp-client.md). A platform admin registers a remote MCP server (Admin → Models → MCP servers), sets the most sensitive data it may receive, reads its tools and approves them one by one after reading their descriptions. Editors choose approved tools under Agent → Build → Tools. During an answer, calls are bounded (timeout, response size, the team's MCP tool calls per answer, at most 25), admitted by the team's budget, metered (optionally priced per call), audited without their arguments or results, and each result is cited as a numbered source that claim checks verify like a passage.
• Stored health (operations/health.md). Every Test of a connection, model or MCP server stores its result, and the worker re-tests enabled ones every 15 minutes at no cost. The lists show "Healthy · 3 minutes ago" or "Failing · since 2 hours ago" with a Health filter; failures appear under Needs attention on the admin Overview; the GroundedHealthCheckFailing alert fires after 30 minutes.
• OpenTelemetry tracing (operations/tracing.md). With OTEL_EXPORTER_OTLP_ENDPOINT set, one answer is one trace across the HTTP request, retrieval, model calls, SystemOne checks, MCP tool calls in both directions and background jobs. Spans carry IDs, counts and durations, never questions, answers, passages or tool arguments.
• A clearer audit log. Each entry says how the person acted: signed in, with an API key or through a connected app, by name. The platform log shows the caller's address. OAuth and tool-call entries say what happened ("App renewed its sign-in", "Connection revoked: a refresh token was reused (possible theft)", "An agent's MCP tool call was refused (call limit)").
• Quieter server errors. A request its client cancelled (a reload, a closed tab) is logged at info and counted as status 499, not as a 500 in the 5xx metrics and the error objective, and every log line uses the configured format.

Requirements

Unchanged from v0.2.0. Tracing needs an OTLP receiver (Tempo, Jaeger or an OpenTelemetry Collector) only if you turn it on.

Upgrading from v0.2.2

A rolling upgrade with no downtime. Take a backup as for any upgrade (operations/upgrades.md), then change every ?ref=v0.2.2 in your overlay to ?ref=v0.3.0 and pin the new digests of ghcr.io/ncecere/grounded and, if you run OCR, ghcr.io/ncecere/grounded-ocr.

Migrations 00035 to 00039 run on start (schema version 34 → 39). They are expand-only, so v0.2.2 pods keep working against the new schema while the rollout proceeds:

Migration	What it adds
00035_mcp_server	The MCP server switch (a new one-row table, off), and mcp in the API-key scope and answer-channel constraints (widened, validated without locking writes)
00036_health_checks	The health_checks table and the health_subjects view
00037_mcp_client	MCP servers, their tools and approvals, the tools of each agent version, the mcp_calls price unit and the mcp_server health kind (new tables; constraints widened)
00038_mcp_oauth	The OAuth sign-in setting (a column on mcp_settings, off) and the OAuth clients, grants, codes and tokens tables
00039_message_retrieval	The retrieval step of an answer (a nullable column on messages), so a reopened answer shows its "Searched the knowledge base for …" step

New settings (all optional; .env.example describes each):

Setting	Default	What it does
HEALTH_CHECK_INTERVAL	15m	How often the worker re-tests enabled connections, models and MCP servers (5m to 24h, or off). It sends no completions, embeddings or tool calls
OTEL_EXPORTER_OTLP_ENDPOINT	unset (tracing off)	The OTLP receiver. Tracing stays off without it
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf	Or grpc
OTEL_EXPORTER_OTLP_HEADERS	unset	Headers for the receiver, such as a token (also OTEL_EXPORTER_OTLP_HEADERS_FILE); a secret, never logged
OTEL_SERVICE_NAME	grounded	The service name on spans
OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG	parentbased_traceidratio, 1.0	Which traces are kept. Invalid values stop the process at start

Kubernetes: the new optional component components/tracing sets the OTLP endpoint (a placeholder to patch) and adds egress to the collector on TCP 4318 (4317 for gRPC) in the monitoring namespace. It isn't in the base. MCP servers are reached through the existing grounded-app-egress-web policy (TCP 80 and 443); a server on another port needs its own egress rule. /mcp, /oauth/… and /.well-known/oauth-… are served by the api pods behind the same ingress, so nothing changes there. The alert rules and dashboards gain the health metrics and GroundedHealthCheckFailing: regenerate your copies if you vendor them.

Things people will notice:

• Admin → Overview → Features has two new rows, MCP server and OAuth sign-in for MCP clients, both off.
• Admin → Models has an MCP servers page, and Connections, Models and MCP servers have a Health column. Existing connections and models show "Not tested yet" until the first scheduled check, a few minutes after the worker starts.
• API keys have a new MCP scope, and people who connect an AI tool through OAuth see it under Connected apps.
• Agent → Build has a Tools section. It only lists tools once a platform admin has approved some, and the agent's chat model must support tools (a platform admin ticks Supports tool calling on the model in Admin → Models).
• Limits → Queries & chat has MCP tool calls per answer (default 5, at most 25), and Costs has an MCP tools spend category.
• The audit log has the areas and actions of the new features (mcp.*, mcp_server.*, mcp_tool.*, oauth.*, platform.mcp, platform.mcp_oauth), and each entry says how the person acted.
• Metrics: new grounded_mcp_tool_calls_total, grounded_mcp_client_calls_total, grounded_mcp_client_call_duration_seconds, grounded_health_failing, grounded_health_failing_seconds, grounded_health_checks_total and grounded_health_check_duration_seconds; the route group mcp, outside the latency objective; and status 499 for requests the client cancelled (operations/monitoring.md).
• API (additive): the MCP server, MCP server...

Grounded v0.2.2

Image

ghcr.io/ncecere/grounded:v0.2.2
ghcr.io/ncecere/grounded@sha256:7e6e44faed623890fbb020a100fd2505c589848de9be5b10d874f96f41dd5fb2

Deploy by digest. Verify the signature (keyless, GitHub Actions OIDC):

cosign verify ghcr.io/ncecere/grounded@sha256:7e6e44faed623890fbb020a100fd2505c589848de9be5b10d874f96f41dd5fb2 \
  --certificate-identity-regexp '^https://github.com/ncecere/grounded/\.github/workflows/.+@refs/tags/v0.2.2$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The OCR sidecar (optional, components/ocr-tesseract), signed the same way:

ghcr.io/ncecere/grounded-ocr:v0.2.2
ghcr.io/ncecere/grounded-ocr@sha256:226e51f2b4b100c130394acdf26e1c218a96c8b0e3b0f988e76532147ce9fa29

Release assets

• grounded-v0.2.2-<os>-<arch>.sbom.spdx.json: the image's SBOM (SPDX JSON) for each platform, as attached to the image.
• grounded-v0.2.2.digest.txt: the image reference by digest.
• checksums.txt: SHA-256 of the files above (sha256sum -c checksums.txt).

The SBOM and build provenance are also attached to the image as attestations, which the signature covers:
docker buildx imagetools inspect ghcr.io/ncecere/grounded@sha256:7e6e44faed623890fbb020a100fd2505c589848de9be5b10d874f96f41dd5fb2 --format '{{ json .SBOM }}'.

Grounded v0.2.2

A small-fixes release after v0.2.1: no new features, no database migrations. The full list is in the changelog.

Fixes

• SystemOne connections test correctly. Admin → Connections → Test (and grounded doctor) asked a SystemOne service for /models, which it doesn't serve, and reported a working connection as failing. A SystemOne connection is now tested with a small SystemOne request; OpenAI-compatible gateways are still tested with GET /models.
• Withdraw a domain request. The person who asked, or a team admin or owner, can withdraw a pending request from Data sources → Crawl domains (DELETE /v1/teams/{team}/domain-requests/{requestId}, audited as crawl.domain_withdraw).
• The admin Overview's Features card no longer squeezes the Evaluations description into a narrow column beside its switch.
• Team initials come from the first two words ("IT Help Desk" is IH, not ID).
• Components: the evaluation score chart labels 0%, 50% and 100%; the score has an accessible tooltip; small lists drop the Columns menu until a column is hidden; list search boxes show their label; single-choice filters no longer show a duplicate chip; menus open inside the page's landmarks; a citation card's "Show source" is a built-in action; the team spend tables hide less important columns on phones; Enter in a combobox never submits the surrounding form.
• Local development: Docker Compose services restart with Docker, make deps-up also starts the OCR sidecar when it's configured, and make dev-up adds the fake model gateway.

Upgrading from v0.2.1

A rolling upgrade with no migrations. Change every ?ref=v0.2.1 in your overlay to ?ref=v0.2.2 and pin the new digests of ghcr.io/ncecere/grounded and, if you run OCR, ghcr.io/ncecere/grounded-ocr. The connection test response gains probe and systemOneModel (additive).

Verifying the images is as for v0.2.0, with the tag v0.2.2.

Grounded v0.2.1

Image

ghcr.io/ncecere/grounded:v0.2.1
ghcr.io/ncecere/grounded@sha256:a5cd09bde6d692d49fa2d4cd97b59f153b4310033da0613243d5182c5168a082

Deploy by digest. Verify the signature (keyless, GitHub Actions OIDC):

cosign verify ghcr.io/ncecere/grounded@sha256:a5cd09bde6d692d49fa2d4cd97b59f153b4310033da0613243d5182c5168a082 \
  --certificate-identity-regexp '^https://github.com/ncecere/grounded/\.github/workflows/.+@refs/tags/v0.2.1$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The OCR sidecar (optional, components/ocr-tesseract), signed the same way:

ghcr.io/ncecere/grounded-ocr:v0.2.1
ghcr.io/ncecere/grounded-ocr@sha256:0fb86be813bb9b66c4a1d2b8f84a8fdf4b2a70e8b58dd61e63d2c710fcab8ec0

Release assets

• grounded-v0.2.1-<os>-<arch>.sbom.spdx.json: the image's SBOM (SPDX JSON) for each platform, as attached to the image.
• grounded-v0.2.1.digest.txt: the image reference by digest.
• checksums.txt: SHA-256 of the files above (sha256sum -c checksums.txt).

The SBOM and build provenance are also attached to the image as attestations, which the signature covers:
docker buildx imagetools inspect ghcr.io/ncecere/grounded@sha256:a5cd09bde6d692d49fa2d4cd97b59f153b4310033da0613243d5182c5168a082 --format '{{ json .SBOM }}'.

Grounded v0.2.1

v0.2.1 is about navigation and clarity. v0.2.0 added evaluations, costs and budgets, OCR and SSO groups; a review by role found that they had piled up in the admin sidebar, the money pages and the evaluation screens. This release moves, merges and explains what exists — it adds no new features — and finishes per-claim verification. The full list of changes is in the changelog, and the plan with the owner's decisions is in v0.2.1.md.

v0.2.1-rc.1 ran on the reference install before this release; v0.2.1 is the same code, apart from documentation. These notes cover both.

Highlights

• A shorter admin sidebar. Eight collapsible groups — People, Content, Models, Usage & spend, Safety, Records, Operations — that fit a laptop screen, with the current page always visible. Legal holds is now a tab of Retention and Profile migrations a tab of Embedding profiles; old addresses redirect.
• What's switched on, at a glance. The admin Overview has a Features card with each optional feature's state (evaluations, cost tracking, OCR, SSO groups, SystemOne, public access, maintenance) and a link to where it's set. The evaluations switch lives there now.
• The team Overview answers "how are we doing?" Each evaluation set's latest score and trend, and — for owners and admins — this month's spend against the budget. A new Evaluations item in the team sidebar lists every set in the team.
• Spend and limits apart. Team settings' Usage & spend shows spend in one line with the breakdown folded away; Crawl domains moved to a tab of Data sources, so Team settings has five tabs. The Costs Overview is about half as tall, with one "Top spenders" card.
• A simpler agent editor. Six tabs (Build · Evaluations · Appearance · Share · Analytics · Settings); version history, compare and revert are in the header's version badge.
• Per-claim verification. With SystemOne citation checks on, each factual sentence of an answer is a claim with one verdict — supported, not supported or uncited — shown with its text in the citation card ("9 of 10 claims supported"). Evaluations count the same claims, so chat and results agree. The API adds claims[], including on the OpenAI-compatible endpoint (additive).
• Chat. Sources start collapsed; a citation chip opens its claim card (Enter from the keyboard), with "Show source" to jump to the passage.
• Fixes from the walkthrough: editors no longer see budget entries in the team audit log (owners and admins only, like spend); evaluation trends skip runs that have no score; Compare versions includes SystemOne settings; the first Tab reaches "Skip to content"; ⌘K opens moved tabs directly; and many smaller copy, keyboard and phone-layout fixes.

Requirements

Unchanged from v0.2.0.

Upgrading from v0.2.0

A rolling upgrade with no downtime and no database migrations (the schema stays at version 34). Take a backup as for any upgrade (operations/upgrades.md), then change every ?ref=v0.2.0 in your overlay to ?ref=v0.2.1 and pin the new digests of ghcr.io/ncecere/grounded and, if you run OCR, ghcr.io/ncecere/grounded-ocr.

Things people will notice:

• Moved pages: Admin → Legal holds and Admin → Profile migrations are tabs of Retention and Embedding profiles; a team's Crawl domains is a tab of Data sources; an agent's Versions tab is the header's version badge. Old links and bookmarks redirect.
• The evaluations switch moved from Admin → Limits → Evaluations to Admin → Overview → Features.
• Clicking a citation chip opens the claim card instead of jumping straight to the source.
• Answers stored before v0.2.1 keep showing a verdict per citation marker; new answers show claims.

Known limitations

The v0.2.0 limitations still apply. Editors can't withdraw their own domain request yet, and a few shared-component refinements (chart axis ticks, a visible label on table search boxes, breadcrumbs that collapse only when they overflow) are on the roadmap.

Verifying the images

As for v0.2.0, with the tag v0.2.1: docker run --rm ghcr.io/ncecere/grounded@sha256:<digest> version prints grounded v0.2.1 (<commit>), and each release has SPDX SBOMs, digest files and a checksums.txt.

Reporting problems

Report bugs and requests as GitHub issues. Report vulnerabilities privately, as SECURITY.md describes.

Grounded v0.2.1-rc.1

Release candidate for v0.2.1. Test it before relying on it; the final release follows.

Image

ghcr.io/ncecere/grounded:v0.2.1-rc.1
ghcr.io/ncecere/grounded@sha256:eaddb4e35d0ecfaa38bb44c11e0bf3d334627808c430f4e4491ac1439b3150b1

Deploy by digest. Verify the signature (keyless, GitHub Actions OIDC):

cosign verify ghcr.io/ncecere/grounded@sha256:eaddb4e35d0ecfaa38bb44c11e0bf3d334627808c430f4e4491ac1439b3150b1 \
  --certificate-identity-regexp '^https://github.com/ncecere/grounded/\.github/workflows/.+@refs/tags/v0.2.1-rc.1$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The OCR sidecar (optional, components/ocr-tesseract), signed the same way:

ghcr.io/ncecere/grounded-ocr:v0.2.1-rc.1
ghcr.io/ncecere/grounded-ocr@sha256:15777aa5a4449349278f6e69c75b395d3f00581072105d7a0dd26cdc0db9183d

Release assets

• grounded-v0.2.1-rc.1-<os>-<arch>.sbom.spdx.json: the image's SBOM (SPDX JSON) for each platform, as attached to the image.
• grounded-v0.2.1-rc.1.digest.txt: the image reference by digest.
• checksums.txt: SHA-256 of the files above (sha256sum -c checksums.txt).

The SBOM and build provenance are also attached to the image as attestations, which the signature covers:
docker buildx imagetools inspect ghcr.io/ncecere/grounded@sha256:eaddb4e35d0ecfaa38bb44c11e0bf3d334627808c430f4e4491ac1439b3150b1 --format '{{ json .SBOM }}'.

No release notes file (docs/releases/v0.2.1.md).

Grounded v0.2.0

Image

ghcr.io/ncecere/grounded:v0.2.0
ghcr.io/ncecere/grounded@sha256:2f896d385feb201d03c3d2a38b6bb1d77ac22f54abfb82093c54894a9a7d3bfd

Deploy by digest. Verify the signature (keyless, GitHub Actions OIDC):

cosign verify ghcr.io/ncecere/grounded@sha256:2f896d385feb201d03c3d2a38b6bb1d77ac22f54abfb82093c54894a9a7d3bfd \
  --certificate-identity-regexp '^https://github.com/ncecere/grounded/\.github/workflows/.+@refs/tags/v0.2.0$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The OCR sidecar (optional, components/ocr-tesseract), signed the same way:

ghcr.io/ncecere/grounded-ocr:v0.2.0
ghcr.io/ncecere/grounded-ocr@sha256:1f17eb7d7b979460b91b6673278585230dcc7b33965505d413a2c6aa38cd9099

Release assets

• grounded-v0.2.0-<os>-<arch>.sbom.spdx.json: the image's SBOM (SPDX JSON) for each platform, as attached to the image.
• grounded-v0.2.0.digest.txt: the image reference by digest.
• checksums.txt: SHA-256 of the files above (sha256sum -c checksums.txt).

The SBOM and build provenance are also attached to the image as attestations, which the signature covers:
docker buildx imagetools inspect ghcr.io/ncecere/grounded@sha256:2f896d385feb201d03c3d2a38b6bb1d77ac22f54abfb82093c54894a9a7d3bfd --format '{{ json .SBOM }}'.

Grounded v0.2.0

v0.2.0 is about measuring answer quality and running many teams. Teams can now test their knowledge bases and agents with evaluation sets. Platform admins can map identity-provider groups to teams, price model use and enforce monthly budgets, and read scanned documents with OCR. Every new feature is optional, and all but evaluations are off until an admin turns them on. The full list of changes is in the changelog, and the plan with the owner's decisions is in v0.2.0.md.

v0.2.0-rc.1 ran on the reference install before this release; v0.2.0 is the same code, apart from the release job and documentation. These notes cover both.

Highlights

• Evaluations (A2). A knowledge base and an agent have an Evaluations tab for team editors and above. A set is a list of test questions, each with the documents a good result finds (picked documents, URL prefixes or filenames) and, for answers, phrases it must mention. Questions are typed, imported from CSV or ragbench's URL-judged JSONL, or added from your own conversations and the agent's Try it panel. A retrieval check (recall@k and MRR, nearly free) or a full-answer check (cites an expected document, mentions the phrases, doesn't refuse wrongly; SystemOne support rate when on) shows what failed and what came back instead, with a score over time and a comparison of two runs. Sets can run automatically after a publish, a profile migration switch, or nightly when documents changed, and a drop notifies the team's editors. Nothing from other people's conversations is copied (ADR-0010 is unchanged). Platform admins can turn evaluations off under Admin → Limits → Evaluations. Guide: operations/evaluations.md.
• Costs and budgets (E2). Off by default. Admins enter dated prices per model and unit, and choose Track only (spend per team, agent and model, with a daily chart and CSV) or Enforce (monthly team budgets in the platform's time zone, a warning at 80%, and at 100% the team's chats, searches and ingestion pause until an admin raises the budget, grants an extension, or the month ends). Teams can override the platform's mode, so one team can pilot Enforce. Team owners and admins see their spend; members only see the banner. Runbook: operations/costs.md.
• OCR for scanned documents (B4). Off by default. Admin → Parsing turns it on with one backend: the new Tesseract sidecar image ghcr.io/ncecere/grounded-ocr (Kustomize component ocr-tesseract), Apache Tika's -full image, or a vision model from the catalog. Only pages without a text layer are read, and PNG, JPEG and single-page TIFF uploads become one-page documents. OCR is bounded per document, per worker and per team per day (ocr_pages_per_day, where documents wait rather than fail), can be turned off per source, and documents skipped as scanned before can be retried together. A vision model's OCR is priced per token; Tesseract and Tika pages are counted, not priced. Runbook: operations/ocr.md.
• SSO group mapping (E1). Admin → Group mapping maps an identity-provider group to a team role. At each sign-in, memberships the mapping created are added, raised, lowered or removed. Memberships made by hand, by invite or by Assign owner are never touched, and a rule never removes a team's last owner. Every rule shows a dry run before it's saved. Runbook: operations/sso-groups.md.
• Search in the command palette (E15). ⌘K finds agents, knowledge bases, sources and your conversations across all your teams (no longer the first ten), and, for platform staff, teams, users, models, connections, embedding profiles and shared sources, through the new GET /v1/search.
• Many small fixes. A deleted agent's conversations open read-only; a raised crawl limit wakes waiting crawls at once; revoked API keys open from audit links; one date rule across the app; an agent Settings tab; knowledge-base top-k inherited by agents until overridden; clearer feedback buttons; clickable table rows with one button each; toasts announced as status messages. See the changelog.
• Release and CI. Each release now attaches SPDX SBOMs, digest files and checksums.txt. The authorization matrix runs as its own CI job, and a tag build fails unless the image reports exactly its tag: v0.1.0's binary reported v0.1, and v0.2.0 reports grounded v0.2.0 (<commit>).

Requirements

Unchanged from v0.1.0: Kubernetes 1.30+, PostgreSQL 17 with pgvector 0.8+ (and the vector, citext, btree_gin and pg_trgm extensions), Valkey or Redis 7+, S3-compatible storage, an OpenAI-compatible gateway and an OIDC provider. New optional pieces:

Optional	Notes
Tesseract OCR	The ocr-tesseract component runs ghcr.io/ncecere/grounded-ocr (Tesseract 5, common languages built in; derive an image for more). Or use Tika's -full image, or a vision model.
A groups claim	For SSO group mapping, your OIDC provider must send the user's groups in a claim (OIDC_GROUPS_CLAIM, default groups; Authentik sends it with the profile scope).

Upgrading from v0.1.0

v0.2.0 is a rolling upgrade from v0.1.0 with no downtime. Take and validate a backup first, as for any upgrade (operations/upgrades.md).

1. Bump the base and the image together. Change every ?ref=v0.1.0 in your overlay to ?ref=v0.2.0, and pin the new digest of ghcr.io/ncecere/grounded. If you still vendor the base, re-vendor at v0.2.0, or switch to the remote base now. The image is public, so the private-registry component and its pull secret can go.
2. Migrations. 00030_search_indexes to 00034_evaluations only add tables, columns, indexes and allowed values, so v0.1.0 pods keep working while the new ones start. They run in each new pod's init container, as before.
3. New settings, all optional: OIDC_GROUPS_CLAIM (SSO group mapping), OCR_TESSERACT_URL, OCR_TIMEOUT, OCR_MAX_PAGES_PER_DOCUMENT and OCR_CONCURRENCY (OCR), EVALUATION_CONCURRENCY (evaluation runs), and RETENTION_EVALUATION_RUNS_DAYS. .env.example documents each.
4. OCR, if you want it. Add the ocr-tesseract component and pin ghcr.io/ncecere/grounded-ocr by digest in your overlay, like the main image. It passes the restricted Pod Security Standard. Then turn OCR on in Admin → Parsing and press Test.
5. What changes for users straight away. Only evaluations: team editors see an Evaluations tab. Costs, OCR and group mapping stay off until an admin sets them up. Evaluation runs are deleted after 180 days by default (retention kind evaluation_runs), unlike other kinds, which keep everything until configured.

Downgrading isn't supported. To go back, restore a backup taken before the upgrade.

Known limitations

v0.2.0 is pre-1.0; the v0.1.0 limitations about performance, capacity and availability still apply. New in this release:

• Budgets are checked with a short cache, so a team can overshoot its budget by about 30 seconds of use. Documents already being ingested when a budget runs out finish; only pending ones wait. Re-embedding during a profile migration isn't checked against budgets.
• Costs before v0.2.0. Usage that retention had already purged before the upgrade is only kept per UTC day, so budget months and report days before the upgrade are exact only to the UTC day.
• OCR reads only the first page of a multi-page TIFF (with a warning), and the per-document page cap is an environment variable, not an admin setting. Tesseract's accuracy depends on the scan's resolution; a vision model reads forms and tables better.
• Evaluations check an agent's retrieval and answers, not its tools beyond knowledge-base search. Questions come only from editors, imports and their own conversations: people can't yet share a failed question with the team.
• Not in v0.2.0 (roadmap candidates, not commitments): cross-encoder reranking (A1b, parked until a rerank model is available), citation marks per claim (A13), SCIM (E4), per-agent budgets, per-page prices for Tesseract and Tika, and multi-page TIFF.

Verifying the images

Images are published for linux/amd64 and linux/arm64 to ghcr.io/ncecere/grounded and, new in v0.2.0, ghcr.io/ncecere/grounded-ocr. The tags are v0.2.0, v0.2 and latest-release; release candidates get only their own tag, such as v0.2.0-rc.1. There is no latest tag...

Grounded v0.2.0-rc.1

Release candidate for v0.2.0. Test it before relying on it; the final release follows.

Image

ghcr.io/ncecere/grounded:v0.2.0-rc.1
ghcr.io/ncecere/grounded@sha256:7584fe9a372c8fb697f84352b49800e8c1dc2d7bf2f489c91153dbed1573402b

Deploy by digest. Verify the signature (keyless, GitHub Actions OIDC):

cosign verify ghcr.io/ncecere/grounded@sha256:7584fe9a372c8fb697f84352b49800e8c1dc2d7bf2f489c91153dbed1573402b \
  --certificate-identity-regexp '^https://github.com/ncecere/grounded/\.github/workflows/.+@refs/tags/v0.2.0-rc.1$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The OCR sidecar (optional, components/ocr-tesseract), signed the same way:

ghcr.io/ncecere/grounded-ocr:v0.2.0-rc.1
ghcr.io/ncecere/grounded-ocr@sha256:33631aef944587336cfc0e1912fe90e0cea305ecca3a6f6c4bea9345fc60a0f2

Release assets

• grounded-v0.2.0-rc.1-<os>-<arch>.sbom.spdx.json: the image's SBOM (SPDX JSON) for each platform, as attached to the image.
• grounded-v0.2.0-rc.1.digest.txt: the image reference by digest.
• checksums.txt: SHA-256 of the files above (sha256sum -c checksums.txt).

The SBOM and build provenance are also attached to the image as attestations, which the signature covers:
docker buildx imagetools inspect ghcr.io/ncecere/grounded@sha256:7584fe9a372c8fb697f84352b49800e8c1dc2d7bf2f489c91153dbed1573402b --format '{{ json .SBOM }}'.

Grounded v0.2.0

v0.2.0 is about measuring answer quality and running many teams. Teams can now test their knowledge bases and agents with evaluation sets. Platform admins can map identity-provider groups to teams, price model use and enforce monthly budgets, and read scanned documents with OCR. Every new feature is optional, and all but evaluations are off until an admin turns them on. The full list of changes is in the changelog, and the plan with the owner's decisions is in v0.2.0.md.

Release candidates are tagged v0.2.0-rc.N before the final v0.2.0. These notes cover both.

Highlights

• Evaluations (A2). A knowledge base and an agent have an Evaluations tab for team editors and above. A set is a list of test questions, each with the documents a good result finds (picked documents, URL prefixes or filenames) and, for answers, phrases it must mention. Questions are typed, imported from CSV or ragbench's URL-judged JSONL, or added from your own conversations and the agent's Try it panel. A retrieval check (recall@k and MRR, nearly free) or a full-answer check (cites an expected document, mentions the phrases, doesn't refuse wrongly; SystemOne support rate when on) shows what failed and what came back instead, with a score over time and a comparison of two runs. Sets can run automatically after a publish, a profile migration switch, or nightly when documents changed, and a drop notifies the team's editors. Nothing from other people's conversations is copied (ADR-0010 is unchanged). Platform admins can turn evaluations off under Admin → Limits → Evaluations. Guide: operations/evaluations.md.
• Costs and budgets (E2). Off by default. Admins enter dated prices per model and unit, and choose Track only (spend per team, agent and model, with a daily chart and CSV) or Enforce (monthly team budgets in the platform's time zone, a warning at 80%, and at 100% the team's chats, searches and ingestion pause until an admin raises the budget, grants an extension, or the month ends). Teams can override the platform's mode, so one team can pilot Enforce. Team owners and admins see their spend; members only see the banner. Runbook: operations/costs.md.
• OCR for scanned documents (B4). Off by default. Admin → Parsing turns it on with one backend: the new Tesseract sidecar image ghcr.io/ncecere/grounded-ocr (Kustomize component ocr-tesseract), Apache Tika's -full image, or a vision model from the catalog. Only pages without a text layer are read, and PNG, JPEG and single-page TIFF uploads become one-page documents. OCR is bounded per document, per worker and per team per day (ocr_pages_per_day, where documents wait rather than fail), can be turned off per source, and documents skipped as scanned before can be retried together. A vision model's OCR is priced per token; Tesseract and Tika pages are counted, not priced. Runbook: operations/ocr.md.
• SSO group mapping (E1). Admin → Group mapping maps an identity-provider group to a team role. At each sign-in, memberships the mapping created are added, raised, lowered or removed. Memberships made by hand, by invite or by Assign owner are never touched, and a rule never removes a team's last owner. Every rule shows a dry run before it's saved. Runbook: operations/sso-groups.md.
• Search in the command palette (E15). ⌘K finds agents, knowledge bases, sources and your conversations across all your teams (no longer the first ten), and, for platform staff, teams, users, models, connections, embedding profiles and shared sources, through the new GET /v1/search.
• Many small fixes. A deleted agent's conversations open read-only; a raised crawl limit wakes waiting crawls at once; revoked API keys open from audit links; one date rule across the app; an agent Settings tab; knowledge-base top-k inherited by agents until overridden; clearer feedback buttons; clickable table rows with one button each; toasts announced as status messages. See the changelog.
• Release and CI. Each release now attaches SPDX SBOMs, digest files and checksums.txt. The authorization matrix runs as its own CI job, and a tag build fails unless the image reports exactly its tag: v0.1.0's binary reported v0.1, and v0.2.0 reports grounded v0.2.0 (<commit>).

Requirements

Unchanged from v0.1.0: Kubernetes 1.30+, PostgreSQL 17 with pgvector 0.8+ (and the vector, citext, btree_gin and pg_trgm extensions), Valkey or Redis 7+, S3-compatible storage, an OpenAI-compatible gateway and an OIDC provider. New optional pieces:

Optional	Notes
Tesseract OCR	The ocr-tesseract component runs ghcr.io/ncecere/grounded-ocr (Tesseract 5, common languages built in; derive an image for more). Or use Tika's -full image, or a vision model.
A groups claim	For SSO group mapping, your OIDC provider must send the user's groups in a claim (OIDC_GROUPS_CLAIM, default groups; Authentik sends it with the profile scope).

Upgrading from v0.1.0

v0.2.0 is a rolling upgrade from v0.1.0 with no downtime. Take and validate a backup first, as for any upgrade (operations/upgrades.md).

1. Bump the base and the image together. Change every ?ref=v0.1.0 in your overlay to ?ref=v0.2.0, and pin the new digest of ghcr.io/ncecere/grounded. If you still vendor the base, re-vendor at v0.2.0, or switch to the remote base now. The image is public, so the private-registry component and its pull secret can go.
2. Migrations. 00030_search_indexes to 00034_evaluations only add tables, columns, indexes and allowed values, so v0.1.0 pods keep working while the new ones start. They run in each new pod's init container, as before.
3. New settings, all optional: OIDC_GROUPS_CLAIM (SSO group mapping), OCR_TESSERACT_URL, OCR_TIMEOUT, OCR_MAX_PAGES_PER_DOCUMENT and OCR_CONCURRENCY (OCR), EVALUATION_CONCURRENCY (evaluation runs), and RETENTION_EVALUATION_RUNS_DAYS. .env.example documents each.
4. OCR, if you want it. Add the ocr-tesseract component and pin ghcr.io/ncecere/grounded-ocr by digest in your overlay, like the main image. It passes the restricted Pod Security Standard. Then turn OCR on in Admin → Parsing and press Test.
5. What changes for users straight away. Only evaluations: team editors see an Evaluations tab. Costs, OCR and group mapping stay off until an admin sets them up. Evaluation runs are deleted after 180 days by default (retention kind evaluation_runs), unlike other kinds, which keep everything until configured.

Downgrading isn't supported. To go back, restore a backup taken before the upgrade.

Known limitations

v0.2.0 is pre-1.0; the v0.1.0 limitations about performance, capacity and availability still apply. New in this release:

• Budgets are checked with a short cache, so a team can overshoot its budget by about 30 seconds of use. Documents already being ingested when a budget runs out finish; only pending ones wait. Re-embedding during a profile migration isn't checked against budgets.
• Costs before v0.2.0. Usage that retention had already purged before the upgrade is only kept per UTC day, so budget months and report days before the upgrade are exact only to the UTC day.
• OCR reads only the first page of a multi-page TIFF (with a warning), and the per-document page cap is an environment variable, not an admin setting. Tesseract's accuracy depends on the scan's resolution; a vision model reads forms and tables better.
• Evaluations check an agent's retrieval and answers, not its tools beyond knowledge-base search. Questions come only from editors, imports and their own conversations: people can't yet share a failed question with the team.
• Not in v0.2.0 (roadmap candidates, not commitments): cross-encoder reranking (A1b, parked until a rerank model is available), citation marks per claim (A13), SCIM (E4), per-agent budgets, per-page prices for Tesseract and Tika, and multi-page TIFF.

Verifying the images

Images are published for linux/amd64 and linux/arm64 to ghcr.io/ncecere/grounded and, new in v0.2.0, ghcr.io/ncecere/grounded-ocr. The tags are v0.2.0, v0.2 and latest-release; release candidates get only their o...