feat(intelligent-assistant): add optional OKP document retrieval

[maysunfaisal]

Target branch

• I have verified this PR targets the correct branch (see branching strategy)

Description

This PR integrates Offline Knowledge Portal (OKP) as an optional product-documentation source for Developer Hub Intelligent Assistant in RHDH Local.

• Keeps Intelligent Assistant enabled by default without OKP, a Red Hat registry login, or the large OKP image download.
• Adds an explicit Compose override for enabling OKP-backed RHDH documentation and clickable citations.
• Updates Lightspeed Core to use the unified configuration, with separate tracked OKP and generated no-OKP variants.
• Generates and validates the no-OKP Lightspeed configuration during configuration synchronization.
• Adds ARM-compatible OKP startup handling.
• Adds Docker and Podman CI coverage for LCORE readiness and the default no-OKP behavior.
• Statically validates the OKP opt-in Compose configuration in CI without authenticating to registry.redhat.io or pulling the OKP image.
• Documents that RHDH product-documentation assistance is disabled by default and that enabling OKP increases initial download time and resource usage.

Which issue(s) does this PR fix or relate to

https://redhat.atlassian.net/browse/RHIDP-14136

PR acceptance criteria

• Tests updated and passing
• Documentation updated
• Built-in TechDocs updated if needed. Note that TechDocs changes may need to be reviewed by a Product Manager and/or Architect to ensure content accuracy, clarity, and alignment with user needs.

How to test changes / Special notes to the reviewer

Intelligent Assistant without OKP (default)

1. Create a local provider configuration and .env file:

   cp default.env .env
   cp configs/extra-files/lightspeed-stack-no-okp.yaml \
      configs/extra-files/lightspeed-stack.local.yaml

2. Uncomment an inference provider in configs/extra-files/lightspeed-stack.local.yaml, configure its credentials in .env, and add:

   LIGHTSPEED_STACK_CONFIG=./configs/extra-files/lightspeed-stack.local.yaml

3. Start RHDH Local without logging in to registry.redhat.io:

   podman compose up -d
   podman compose ps

4. Verify rhdh and lightspeed-core are running, no okp container exists, and the following commands return no output:

   podman exec lightspeed-core printenv OKP_SERVICE_URL
   podman exec lightspeed-core grep '^rag:' /app-root/lightspeed-stack.yaml

5. Open http://localhost:7007/intelligent-assistant and verify the chatbot works without OKP-backed documentation or citations.

Intelligent Assistant with OKP (opt-in)

1. Stop the default deployment and authenticate to the Red Hat registry:

   podman compose down
   podman login registry.redhat.io

2. Enable OKP and create an OKP-enabled local provider configuration:

   cp compose.okp-enabled.override.example.yaml compose.override.yaml
   cp configs/extra-files/lightspeed-stack.yaml \
      configs/extra-files/lightspeed-stack-okp.local.yaml

3. Uncomment the same inference provider in configs/extra-files/lightspeed-stack-okp.local.yaml, then add to .env:

   LIGHTSPEED_STACK_OKP_CONFIG=./configs/extra-files/lightspeed-stack-okp.local.yaml

4. Start and verify the opt-in deployment:

   podman compose up -d
   podman compose ps
   curl -f http://localhost:8081/

5. Verify rhdh, lightspeed-core, and okp are running, okp is healthy, and LCORE has the OKP URL:

   podman exec lightspeed-core printenv OKP_SERVICE_URL

6. Open http://localhost:7007/intelligent-assistant, ask an RHDH documentation question, and verify the response contains clickable OKP citations.

Docker users can replace podman with docker in the commands above.

Cleanup

podman compose down --volumes
rm -f compose.override.yaml

[Jdubrick]

/fs-review

[rm3l]

/agentic_review

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (4) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Default document lookup endpoint fails 🐞 Bug ≡ Correctness

Description

compose.okp-enabled.override.example.yaml sets OKP_SERVICE_URL to
http://host.docker.internal:8081, while the Compose project provides neither a host-gateway alias
for supported standalone Linux Docker nor a separate browser-facing URL for this container-oriented
hostname. On runtimes without that special alias, Lightspeed Core reaches hostname resolution
failure when retrieving from OKP, and host browsers cannot follow the citation URLs generated from
the same value.

Code

compose.okp-enabled.override.example.yaml[11]

+      OKP_SERVICE_URL: ${OKP_SERVICE_URL:-http://host.docker.internal:8081}

Relevance

●● Moderate

Portability concern is plausible, but no closely matching historical acceptance or rejection
precedent was found.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The override passes the Docker Desktop-specific host.docker.internal value to Lightspeed Core, and
the active RAG configuration consumes it as the OKP endpoint for both container retrieval and
browser-facing citations. The documentation supports standalone Docker Engine and distinguishes
Docker and Podman host aliases, but the Compose service defines no extra_hosts or other
host-gateway mapping and provides no separate public citation URL, demonstrating that the configured
endpoint is not portable to both clients.

compose.okp-enabled.override.example.yaml[8-11]
configs/extra-files/lightspeed-stack.yaml[146-154]
compose.yaml[59-80]
docs/intelligent-assistant/working-with-intelligent-assistant.md[262-277]
compose.okp-enabled.override.example.yaml[4-11]
docs/rhdh-local-guide/getting-started.md[6-12]
docs/intelligent-assistant/working-with-intelligent-assistant.md[170-178]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The default OKP endpoint depends on `host.docker.internal`, which this Compose project does not configure for standalone Linux Docker and which is also unsuitable as a browser-facing hostname there. The configured URLs must allow both Lightspeed Core to reach OKP from its container and host browsers to open generated citations.

## Fix Focus Areas
- compose.okp-enabled.override.example.yaml[4-11]
- configs/extra-files/lightspeed-stack.yaml[146-154]
- docs/intelligent-assistant/working-with-intelligent-assistant.md[262-275]

## Recommended Fix
Use separate internal and public OKP endpoints: connect Lightspeed Core to the Compose service at `http://okp:8080`, and generate browser-facing citations with a public base such as `http://localhost:8081`. If separate endpoints are not supported, add the required configuration support; alternatively, use a runtime-independent address reachable from both clients or add the required host-gateway mapping while configuring citations to use `localhost:8081`. Keep the documented default aligned with actual container and browser reachability instead of defaulting both uses to a runtime-specific hostname.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Disabling leaves OKP running 🐞 Bug ≡ Correctness ⭐ New

Description

Enable OKP Document Retrieval says starting the base stack without the overlay disables OKP, but
Compose does not remove an already-created service merely because a later up omits its definition.
After a user has enabled OKP, following this instruction or adding the documented assistant-disable
override leaves the okp container and its published port running while only Lightspeed Core is
disabled.

Code

docs/intelligent-assistant/working-with-intelligent-assistant.md[278]

+Start the base stack without `-f intelligent-assistant/compose-with-okp.yaml` to disable OKP again. Intelligent Assistant remains enabled, but responses no longer include OKP-backed product documentation or citations.

Relevance

●●● Strong

Concrete Compose lifecycle bug; prior Lightspeed work established explicit service-disable paths.

PR-#218

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The opt-in command creates okp as an independent service that publishes ports, while the disable
override only assigns a profile to lightspeed-core. The documentation's later base-only startup
therefore omits OKP from the model but performs no operation that stops or removes its existing
container.

docs/intelligent-assistant/working-with-intelligent-assistant.md[256-278]
intelligent-assistant/compose-with-okp.yaml[13-23]
compose.intelligent-assistant-disabled.override.example.yaml[1-6]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The documented disable procedures omit removal of an existing OKP container, so it remains active after users restart without the OKP overlay or disable Lightspeed Core.

## Fix Focus Areas
- docs/intelligent-assistant/working-with-intelligent-assistant.md[256-278]
- docs/intelligent-assistant/working-with-intelligent-assistant.md[355-362]

## Recommended Fix
Update both disable procedures to instruct users who previously enabled OKP to stop and remove the `okp` service using the same base and OKP Compose files before restarting the base stack. Include equivalent Podman and Docker commands, such as `compose ... stop okp` followed by `compose ... rm -f okp`, so the container and published ports are actually removed without tearing down unrelated services.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Network peers reach Solr administration 🐞 Bug ⛨ Security

Description

The OKP override publishes Solr port 8983 on every host interface via 8983:8983, even though it is
documented only as a local diagnostic interface. When OKP is enabled, any network peer that can
reach the developer's machine can access Solr's HTTP administration endpoint rather than access
being limited to the local health check and operator.

Code

compose.okp-enabled.override.example.yaml[23]

+      - "8983:8983"

Relevance

●●● Strong

Restricting diagnostic ports is a concrete security hardening fix consistent with prior accepted
configuration corrections.

PR-#34

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The unqualified 8983:8983 Compose mapping publishes Solr without a host IP restriction, while the
command starts Solr and the health check accesses its administration and diagnostic endpoint. The
maintenance documentation characterizes port 8983 as local diagnostics, and existing Compose
configuration demonstrates the intended pattern by explicitly binding host-local diagnostic ports to
127.0.0.1.

compose.okp-enabled.override.example.yaml[21-35]
compose.yaml[15-18]
docs/intelligent-assistant/maintaining-intelligent-assistant.md[105-105]
compose.okp-enabled.override.example.yaml[21-23]
compose.okp-enabled.override.example.yaml[34-38]
docs/intelligent-assistant/maintaining-intelligent-assistant.md[99-105]
compose.yaml[14-18]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The opt-in Compose override exposes Solr's diagnostic and administration endpoint on all host interfaces even though only local access is required.

## Fix Focus Areas
- compose.okp-enabled.override.example.yaml[21-23]
- docs/intelligent-assistant/maintaining-intelligent-assistant.md[105-105]

## Recommended Fix
Change the Solr publication to a loopback-only binding such as `127.0.0.1:8983:8983`, or remove it entirely if host-side diagnostics are unnecessary. Keep the container-local health check pointed at port 8983, retain any HTTP publication only as broadly reachable as required for browser citations, and update the port documentation if its access scope changes.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. ARM assistant regressions escape CI 🐞 Bug ☼ Reliability

Description

The nightly matrix explicitly excludes the new intelligent-assistant profile from ARM runners.
Because the remaining ARM profiles set disable_intelligent_assistant to true, no ARM job executes
the added Lightspeed Core readiness validation despite this change introducing ARM-specific startup
handling.

Code

.github/workflows/nightly.yaml[R93-96]

+          - os: ubuntu-24.04-arm
+            composeConfig:
+              name: "intelligent-assistant"
+              cliArgs: "-f compose.yaml"

Relevance

●●● Strong

Recent workflow precedents accept preserving matrix coverage and adding missing configuration
scenarios.

PR-#180
PR-#229

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The added matrix entry appears under exclude, while disable_intelligent_assistant is false only
for the intelligent-assistant and legacy developer-lightspeed profiles. The runtime readiness step
itself runs only when the profile name is intelligent-assistant, so every surviving ARM job
bypasses it.

.github/workflows/nightly.yaml[78-104]
.github/workflows/nightly.yaml[140-143]
.github/actions/rhdh-local-compose-test/action.yaml[359-397]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The nightly matrix excludes the only ARM profile that keeps Intelligent Assistant enabled and invokes its runtime validation.

## Fix Focus Areas
- .github/workflows/nightly.yaml[93-96]
- .github/workflows/nightly.yaml[140-143]
- .github/actions/rhdh-local-compose-test/action.yaml[359-397]

## Recommended Fix
Remove the ARM `intelligent-assistant` exclusion while retaining a single representative ARM tool and user-configuration combination. Ensure that job reaches the Lightspeed Core readiness and mounted-configuration checks.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View medium (1)

5. Synced configurations can diverge ✓ Resolved 🐞 Bug ☼ Reliability

Description

TARGETS lists the same mutable upstream stack file twice, and the synchronization loop downloads
it independently before producing each destination. If the selected branch advances between
requests, lightspeed-stack.yaml and its no-OKP variant are generated from different upstream
revisions and can be committed together as though synchronized.

Code

scripts/sync-lightspeed-configs.sh[R12-13]

+  "lightspeed-core-configs/lightspeed-stack.yaml|${LIGHTSPEED_DIR}/lightspeed-stack.yaml|copy_fetched_file"
+  "lightspeed-core-configs/lightspeed-stack.yaml|${LIGHTSPEED_DIR}/lightspeed-stack-no-okp.yaml|strip_okp_config"

Relevance

●● Moderate

The synchronization race is technically plausible, but no historical precedent establishes team
treatment of this edge case.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Both new target entries name lightspeed-core-configs/lightspeed-stack.yaml, but the loop invokes
fetch_file separately for every target. The workflow passes a mutable release branch to the script
and stages all generated destinations from one run, so there is no immutable revision or shared
downloaded source enforcing consistency.

scripts/sync-lightspeed-configs.sh[11-34]
scripts/sync-lightspeed-configs.sh[126-144]
.github/workflows/sync-lightspeed-configs.yaml[36-50]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The full and no-OKP configurations are produced from separate requests to the same mutable branch, allowing one synchronization run to mix upstream revisions.

## Fix Focus Areas
- scripts/sync-lightspeed-configs.sh[11-34]
- scripts/sync-lightspeed-configs.sh[126-144]

## Recommended Fix
Fetch every distinct `source_path` once into the temporary directory and apply all destination transforms to that cached file. Alternatively, resolve the requested ref to one immutable commit SHA before downloading any targets and use that SHA for every request.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

⚠️ Tickets: not configured — ticket URL found in PR but could not be fetched — check ticket provider credentials

✅ Cross-repo context — repo relationships

  Explored: repo: redhat-developer/rhdh-plugins (sha: a62f863d)

  Explored: repo: redhat-developer/rhdh (sha: 023f4f28)

Review mode: 🧠 Deep: This push introduces substantial, independent runtime, Compose, shell-sync, and CI workflow logic across multiple paths, creating a high density of subtle integration and configuration defects that benefits from redundant review passes.

Tip of the day

💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Previous reviews

Review updated until commit d730540 🧠 Deep

Results up to commit f288dfc 🧠 Deep

🐞 Bugs (3) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Default document lookup endpoint fails 🐞 Bug ≡ Correctness

Description

compose.okp-enabled.override.example.yaml sets OKP_SERVICE_URL to
http://host.docker.internal:8081, while the Compose project provides neither a host-gateway alias
for supported standalone Linux Docker nor a separate browser-facing URL for this container-oriented
hostname. On runtimes without that special alias, Lightspeed Core reaches hostname resolution
failure when retrieving from OKP, and host browsers cannot follow the citation URLs generated from
the same value.

Code

compose.okp-enabled.override.example.yaml[11]

+      OKP_SERVICE_URL: ${OKP_SERVICE_URL:-http://host.docker.internal:8081}

Relevance

●● Moderate

Portability concern is plausible, but no closely matching historical acceptance or rejection
precedent was found.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The override passes the Docker Desktop-specific host.docker.internal value to Lightspeed Core, and
the active RAG configuration consumes it as the OKP endpoint for both container retrieval and
browser-facing citations. The documentation supports standalone Docker Engine and distinguishes
Docker and Podman host aliases, but the Compose service defines no extra_hosts or other
host-gateway mapping and provides no separate public citation URL, demonstrating that the configured
endpoint is not portable to both clients.

compose.okp-enabled.override.example.yaml[8-11]
configs/extra-files/lightspeed-stack.yaml[146-154]
compose.yaml[59-80]
docs/intelligent-assistant/working-with-intelligent-assistant.md[262-277]
compose.okp-enabled.override.example.yaml[4-11]
docs/rhdh-local-guide/getting-started.md[6-12]
docs/intelligent-assistant/working-with-intelligent-assistant.md[170-178]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The default OKP endpoint depends on `host.docker.internal`, which this Compose project does not configure for standalone Linux Docker and which is also unsuitable as a browser-facing hostname there. The configured URLs must allow both Lightspeed Core to reach OKP from its container and host browsers to open generated citations.

## Fix Focus Areas
- compose.okp-enabled.override.example.yaml[4-11]
- configs/extra-files/lightspeed-stack.yaml[146-154]
- docs/intelligent-assistant/working-with-intelligent-assistant.md[262-275]

## Recommended Fix
Use separate internal and public OKP endpoints: connect Lightspeed Core to the Compose service at `http://okp:8080`, and generate browser-facing citations with a public base such as `http://localhost:8081`. If separate endpoints are not supported, add the required configuration support; alternatively, use a runtime-independent address reachable from both clients or add the required host-gateway mapping while configuring citations to use `localhost:8081`. Keep the documented default aligned with actual container and browser reachability instead of defaulting both uses to a runtime-specific hostname.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Network peers reach Solr administration 🐞 Bug ⛨ Security

Description

The OKP override publishes Solr port 8983 on every host interface via 8983:8983, even though it is
documented only as a local diagnostic interface. When OKP is enabled, any network peer that can
reach the developer's machine can access Solr's HTTP administration endpoint rather than access
being limited to the local health check and operator.

Code

compose.okp-enabled.override.example.yaml[23]

+      - "8983:8983"

Relevance

●●● Strong

Restricting diagnostic ports is a concrete security hardening fix consistent with prior accepted
configuration corrections.

PR-#34

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The unqualified 8983:8983 Compose mapping publishes Solr without a host IP restriction, while the
command starts Solr and the health check accesses its administration and diagnostic endpoint. The
maintenance documentation characterizes port 8983 as local diagnostics, and existing Compose
configuration demonstrates the intended pattern by explicitly binding host-local diagnostic ports to
127.0.0.1.

compose.okp-enabled.override.example.yaml[21-35]
compose.yaml[15-18]
docs/intelligent-assistant/maintaining-intelligent-assistant.md[105-105]
compose.okp-enabled.override.example.yaml[21-23]
compose.okp-enabled.override.example.yaml[34-38]
docs/intelligent-assistant/maintaining-intelligent-assistant.md[99-105]
compose.yaml[14-18]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The opt-in Compose override exposes Solr's diagnostic and administration endpoint on all host interfaces even though only local access is required.

## Fix Focus Areas
- compose.okp-enabled.override.example.yaml[21-23]
- docs/intelligent-assistant/maintaining-intelligent-assistant.md[105-105]

## Recommended Fix
Change the Solr publication to a loopback-only binding such as `127.0.0.1:8983:8983`, or remove it entirely if host-side diagnostics are unnecessary. Keep the container-local health check pointed at port 8983, retain any HTTP publication only as broadly reachable as required for browser citations, and update the port documentation if its access scope changes.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. ARM assistant regressions escape CI 🐞 Bug ☼ Reliability

Description

The nightly matrix explicitly excludes the new intelligent-assistant profile from ARM runners.
Because the remaining ARM profiles set disable_intelligent_assistant to true, no ARM job executes
the added Lightspeed Core readiness validation despite this change introducing ARM-specific startup
handling.

Code

.github/workflows/nightly.yaml[R93-96]

+          - os: ubuntu-24.04-arm
+            composeConfig:
+              name: "intelligent-assistant"
+              cliArgs: "-f compose.yaml"

Relevance

●●● Strong

Recent workflow precedents accept preserving matrix coverage and adding missing configuration
scenarios.

PR-#180
PR-#229

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The added matrix entry appears under exclude, while disable_intelligent_assistant is false only
for the intelligent-assistant and legacy developer-lightspeed profiles. The runtime readiness step
itself runs only when the profile name is intelligent-assistant, so every surviving ARM job
bypasses it.

.github/workflows/nightly.yaml[78-104]
.github/workflows/nightly.yaml[140-143]
.github/actions/rhdh-local-compose-test/action.yaml[359-397]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The nightly matrix excludes the only ARM profile that keeps Intelligent Assistant enabled and invokes its runtime validation.

## Fix Focus Areas
- .github/workflows/nightly.yaml[93-96]
- .github/workflows/nightly.yaml[140-143]
- .github/actions/rhdh-local-compose-test/action.yaml[359-397]

## Recommended Fix
Remove the ARM `intelligent-assistant` exclusion while retaining a single representative ARM tool and user-configuration combination. Ensure that job reaches the Lightspeed Core readiness and mounted-configuration checks.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Synced configurations can diverge ✓ Resolved 🐞 Bug ☼ Reliability

Description

TARGETS lists the same mutable upstream stack file twice, and the synchronization loop downloads
it independently before producing each destination. If the selected branch advances between
requests, lightspeed-stack.yaml and its no-OKP variant are generated from different upstream
revisions and can be committed together as though synchronized.

Code

scripts/sync-lightspeed-configs.sh[R12-13]

+  "lightspeed-core-configs/lightspeed-stack.yaml|${LIGHTSPEED_DIR}/lightspeed-stack.yaml|copy_fetched_file"
+  "lightspeed-core-configs/lightspeed-stack.yaml|${LIGHTSPEED_DIR}/lightspeed-stack-no-okp.yaml|strip_okp_config"

Relevance

●● Moderate

The synchronization race is technically plausible, but no historical precedent establishes team
treatment of this edge case.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Both new target entries name lightspeed-core-configs/lightspeed-stack.yaml, but the loop invokes
fetch_file separately for every target. The workflow passes a mutable release branch to the script
and stages all generated destinations from one run, so there is no immutable revision or shared
downloaded source enforcing consistency.

scripts/sync-lightspeed-configs.sh[11-34]
scripts/sync-lightspeed-configs.sh[126-144]
.github/workflows/sync-lightspeed-configs.yaml[36-50]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The full and no-OKP configurations are produced from separate requests to the same mutable branch, allowing one synchronization run to mix upstream revisions.

## Fix Focus Areas
- scripts/sync-lightspeed-configs.sh[11-34]
- scripts/sync-lightspeed-configs.sh[126-144]

## Recommended Fix
Fetch every distinct `source_path` once into the temporary directory and apply all destination transforms to that cached file. Alternatively, resolve the requested ref to one immutable commit SHA before downloading any targets and use that SHA for every request.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[rm3l]

/agentic_review

[rhdh-qodo-merge]

Code review by qodo was updated up to the latest commit d730540

[michael-valdron]

fyi @rm3l

@maysunfaisal pulled in my #328 changes into here to have the IA part of RHDH Local updated in one go. Still have equivalent changes for operator and chart in their own PRs, redhat-developer/rhdh-operator#3612 and redhat-developer/rhdh-chart#549 respectively.

[michael-valdron]

@rm3l we had another team discussion about Ollama and decided for RHDH Local to leave the Ollama content in place for the time being given its not RHDH product supported.

@maysunfaisal has taken these changes out, but left in my change for the RC release of the target LCORE version.

cc @Jdubrick @yangcao77 @benwilcock

[maysunfaisal]

@rm3l addressed all your reviews, pls take a look, thank you

[rm3l]

so it is directly resolvable by browsers on Podman and Docker Desktop.
[...]
set OKP_SERVICE_URL in .env to a hostname or IP that is reachable from both the container and browser if host.docker.internal is unavailable

These seem confusing.. host.docker.internal did not resolve directly from the browser on my Linux. Also, I guess users might also point to an OKP running anywhere, not necessarily if host.docker.internal is unavailable, no?

WDYT about something like this (suggestion from Claude):

Suggested change

	By default, Lightspeed Core reaches the host-published OKP endpoint at `http://host.docker.internal:8081`. LCORE uses this same base URL for generated citation links, so it is directly resolvable by browsers on Podman and Docker Desktop. The endpoint is also available as `http://localhost:8081` on the host. On native Linux, set `OKP_SERVICE_URL` in `.env` to a hostname or IP that is reachable from both the container and browser if `host.docker.internal` is unavailable.
	Lightspeed Core uses `OKP_SERVICE_URL` for both document retrieval and browser-facing citation links, so the URL must be reachable from both the container and your browser. The default is `http://host.docker.internal:8081`.
	On Docker Desktop and Podman Desktop, `host.docker.internal` resolves in both contexts and no extra configuration is needed.
	On native Linux (Docker Engine or rootless Podman without a machine), the container resolves `host.docker.internal` but the host browser does not, which breaks citation links. Either add `127.0.0.1 host.docker.internal` to your host's `/etc/hosts`, or set `OKP_SERVICE_URL` in `.env` to your host's LAN IP (e.g., http://10.10.10.105:8081).
	To use an OKP instance running outside the compose stack, set `OKP_SERVICE_URL` in `.env` to its URL.

[maysunfaisal]

Updated the wording. OKP_SERVICE_URL is now clearly documented as the URL used by both LCORE and browser-facing citations. Desktop environments retain the default, while native Linux users can provide a shared host/LAN IP. I avoided recommending /etc/hosts because native Docker Engine might also lack host.docker.internal inside the container. Verified successfully with Docker on native Linux.

@rm3l rebased with main, could you please take a look and lgtm if its good, thanks...

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud