diff --git a/docs/site/README.md b/docs/site/README.md
new file mode 100644
index 00000000..99de3790
--- /dev/null
+++ b/docs/site/README.md
@@ -0,0 +1,55 @@
+# Solr MCP documentation site content
+
+This directory is the **source of truth** for the Apache Solr MCP documentation that
+is published on the Solr website at .
+
+Keeping the content here means every feature PR can update its documentation alongside
+the code change, in the same review.
+
+## What lives here
+
+```
+docs/site/content/
+├── pages/mcp/** Markdown pages (one file per published page)
+└── doap/solr-mcp.rdf DOAP project descriptor
+```
+
+These are plain [Pelican](https://getpelican.com/) content files. Each page carries
+front-matter that selects a template, e.g.:
+
+```
+Title: Quick Start
+URL: mcp/quick-start.html
+save_as: mcp/quick-start.html
+template: mcp/quick-start
+```
+
+## How it gets published (assembly at build time)
+
+The **presentation layer** (Pelican templates, theme, CSS, `pelicanconf.py`) lives in
+the [`apache/solr-site`](https://github.com/apache/solr-site) repository, not here, so
+the MCP pages share the rest of the Solr site's look and feel.
+
+At site-build time, `solr-site` fetches this directory at a pinned ref and copies it
+into its Pelican `content/` tree before running `pelican content -o output`:
+
+- `content/pages/mcp/**` ← `docs/site/content/pages/mcp/**`
+- `content/doap/solr-mcp.rdf` ← `docs/site/content/doap/solr-mcp.rdf`
+
+This is wired in `solr-site`'s `build.sh` (local preview) and its Pelican GitHub
+Actions workflows (`build-pelican.yml`, `pr-build-pelican.yml`). The published URLs are
+unchanged from when the content lived in `solr-site` directly.
+
+## Editing and previewing
+
+- **Edit** the Markdown here; that is all most doc changes require.
+- **Preview** with the full Solr theme by running `solr-site`'s `./build.sh -l` with a
+ sibling `solr-mcp` checkout — the build picks up `../solr-mcp/docs/site/content`
+ automatically when present, otherwise it clones the pinned ref.
+
+## Why content here, theme there
+
+A standalone build in this repo would have to vendor the Solr Pelican theme and would
+drift from the rest of the site. Splitting **content (here)** from **presentation
+(`solr-site`)** keeps a single themed build while letting documentation travel with the
+code — mirroring how the Solr Reference Guide is assembled into the site.
diff --git a/docs/site/content/doap/solr-mcp.rdf b/docs/site/content/doap/solr-mcp.rdf
new file mode 100644
index 00000000..40faa36a
--- /dev/null
+++ b/docs/site/content/doap/solr-mcp.rdf
@@ -0,0 +1,52 @@
+
+
+
+
+
+ 2025-10-26
+
+ Apache Solr MCP Server
+
+
+ Model Context Protocol server for Apache Solr
+
+
+
+ Java
+
+
+
+
+
+
+
+
+
+
+
+ Apache Solr Team
+
+
+
+
+
+
diff --git a/docs/site/content/pages/mcp/clients/claude-code.md b/docs/site/content/pages/mcp/clients/claude-code.md
new file mode 100644
index 00000000..decf18be
--- /dev/null
+++ b/docs/site/content/pages/mcp/clients/claude-code.md
@@ -0,0 +1,114 @@
+Title: Claude Code
+URL: mcp/clients/claude-code.html
+save_as: mcp/clients/claude-code.html
+template: mcp/client
+
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's CLI tool for Claude. It supports MCP servers via the `claude mcp add` command or a `.mcp.json` project file.
+
+***
+
+## CLI Syntax ##
+
+The general form of `claude mcp add` is (see [Claude Code MCP docs](https://code.claude.com/docs/en/mcp)):
+
+```bash
+claude mcp add [options] [args...]
+```
+
+The server `` comes first. For a **STDIO** server, pass any `-e KEY=value` options (repeatable) after the name, then `--`, then the launch command. The `--` stops Claude Code from reparsing the server's own flags as its own options, and `-e` stops consuming tokens at the `--`:
+
+```bash
+claude mcp add -e KEY=value -- [args...]
+```
+
+For an **HTTP** server, no `--` is needed — pass the URL with `--transport http`:
+
+```bash
+claude mcp add --transport http
+```
+
+***
+
+## STDIO Mode (Recommended) ##
+
+### CLI ###
+
+```bash
+# JAR
+claude mcp add solr-mcp \
+ -e SOLR_URL=http://localhost:8983/solr/ \
+ -- java -jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar
+
+# Docker (local image — build first with ./gradlew jibDockerBuild)
+claude mcp add solr-mcp \
+ -- docker run -i --rm -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+ solr-mcp:latest
+```
+
+### `.mcp.json` ###
+
+Add to your project root:
+
+**JAR:**
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "type": "stdio",
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": { "SOLR_URL": "http://localhost:8983/solr/" }
+ }
+ }
+}
+```
+
+**Docker (local image):**
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "type": "stdio",
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/",
+ "solr-mcp:latest"]
+ }
+ }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the `args` array.
+
+***
+
+## HTTP Mode ##
+
+Start the server first (see [Running the Server](https://github.com/apache/solr-mcp#running-the-server)), then:
+
+### CLI ###
+
+```bash
+claude mcp add --transport http solr-mcp http://localhost:8080/mcp
+```
+
+### `.mcp.json` ###
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "type": "http",
+ "url": "http://localhost:8080/mcp"
+ }
+ }
+}
+```
+
+### Secured HTTP (OAuth2) ###
+
+Claude Code detects the OAuth2 challenge from the server and initiates the authorization flow automatically. The configuration is the same as unsecured HTTP.
+
+See [Security](/mcp/security.html) for server-side OAuth2 setup.
diff --git a/docs/site/content/pages/mcp/clients/claude-desktop.md b/docs/site/content/pages/mcp/clients/claude-desktop.md
new file mode 100644
index 00000000..e849131d
--- /dev/null
+++ b/docs/site/content/pages/mcp/clients/claude-desktop.md
@@ -0,0 +1,110 @@
+Title: Claude Desktop
+URL: mcp/clients/claude-desktop.html
+save_as: mcp/clients/claude-desktop.html
+template: mcp/client
+
+[Claude Desktop](https://claude.ai/download) is Anthropic's desktop application for Claude. It supports MCP servers via STDIO and HTTP transports.
+
+### Configuration File
+
+* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Restart Claude Desktop after any configuration change.
+
+***
+
+## STDIO Mode (Recommended) ##
+
+STDIO mode communicates via stdin/stdout. This is the simplest setup for local use.
+
+### JAR ###
+
+Requires Java 25+ and a [built JAR](https://github.com/apache/solr-mcp#running-the-server) (`./gradlew build`).
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": {
+ "SOLR_URL": "http://localhost:8983/solr/"
+ }
+ }
+ }
+}
+```
+
+### Docker (local image) ###
+
+Build the image first: `./gradlew jibDockerBuild`
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/",
+ "solr-mcp:latest"]
+ }
+ }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the `args` array.
+
+***
+
+## HTTP Mode ##
+
+HTTP mode connects to a running MCP server via REST endpoints. Start the server first, then configure Claude Desktop to connect using `mcp-remote`.
+
+### Start the Server ###
+
+```bash
+# JAR
+PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
+
+# Or Gradle
+PROFILES=http ./gradlew bootRun
+
+# Or Docker (local image)
+docker run -p 8080:8080 --rm \
+ -e PROFILES=http \
+ -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+ solr-mcp:latest
+```
+
+### Configure Claude Desktop ###
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "npx",
+ "args": ["mcp-remote", "http://localhost:8080/mcp"]
+ }
+ }
+}
+```
+
+### Secured HTTP (OAuth2) ###
+
+When OAuth2 is enabled on the server, `mcp-remote` handles the authorization flow automatically—it discovers the authorization server and opens a browser for consent.
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "npx",
+ "args": ["mcp-remote", "http://localhost:8080/mcp", "--allow-http"]
+ }
+ }
+}
+```
+
+The `--allow-http` flag is needed for `http://` URLs (development). Omit it in production with HTTPS.
+
+See [Security](/mcp/security.html) for server-side OAuth2 setup.
diff --git a/docs/site/content/pages/mcp/clients/cursor.md b/docs/site/content/pages/mcp/clients/cursor.md
new file mode 100644
index 00000000..73a420f8
--- /dev/null
+++ b/docs/site/content/pages/mcp/clients/cursor.md
@@ -0,0 +1,75 @@
+Title: Cursor
+URL: mcp/clients/cursor.html
+save_as: mcp/clients/cursor.html
+template: mcp/client
+
+[Cursor](https://cursor.sh/) supports MCP servers natively via project configuration files or the Cursor Settings UI.
+
+***
+
+## STDIO Mode (Recommended) ##
+
+### Project Configuration (`.cursor/mcp.json`) ###
+
+Create `.cursor/mcp.json` in your project root:
+
+**JAR:**
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": { "SOLR_URL": "http://localhost:8983/solr/" }
+ }
+ }
+}
+```
+
+**Docker (local image — build first with `./gradlew jibDockerBuild`):**
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/",
+ "solr-mcp:latest"]
+ }
+ }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the `args` array.
+
+### Cursor Settings UI ###
+
+1. Open **Cursor Settings** (gear icon or Cmd+, / Ctrl+,)
+2. Navigate to **Features** > **MCP Servers**
+3. Click **Add New MCP Server**
+4. Enter:
+ * **Name**: `solr-mcp`
+ * **Type**: `command`
+ * **Command**: `java -jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar`
+
+***
+
+## HTTP Mode ##
+
+Start the server first (see [Running the Server](https://github.com/apache/solr-mcp#running-the-server)), then:
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "url": "http://localhost:8080/mcp"
+ }
+ }
+}
+```
+
+The configuration is the same for secured and unsecured HTTP. Cursor handles the MCP OAuth2 flow automatically.
+
+See the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol) for the latest configuration format.
diff --git a/docs/site/content/pages/mcp/clients/jetbrains.md b/docs/site/content/pages/mcp/clients/jetbrains.md
new file mode 100644
index 00000000..db42ce8d
--- /dev/null
+++ b/docs/site/content/pages/mcp/clients/jetbrains.md
@@ -0,0 +1,78 @@
+Title: JetBrains IDEs
+URL: mcp/clients/jetbrains.html
+save_as: mcp/clients/jetbrains.html
+template: mcp/client
+
+[JetBrains IDEs](https://www.jetbrains.com/) (IntelliJ IDEA, WebStorm, PyCharm, etc.) support MCP servers through the AI Assistant plugin.
+
+***
+
+## STDIO Mode (Recommended) ##
+
+### Project Configuration (`.junie/mcp/mcp.json`) ###
+
+Create `.junie/mcp/mcp.json` in your project root:
+
+**JAR:**
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": { "SOLR_URL": "http://localhost:8983/solr/" }
+ }
+ }
+}
+```
+
+**Docker (local image — build first with `./gradlew jibDockerBuild`):**
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/",
+ "solr-mcp:latest"]
+ }
+ }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the `args` array.
+
+### IDE Settings ###
+
+1. Open **Settings** (Cmd+, / Ctrl+Alt+S)
+2. Navigate to **Tools** > **AI Assistant** > **MCP Servers**
+3. Click **Add** (`+`)
+4. Configure:
+ * **Name**: `solr-mcp`
+ * **Transport**: `STDIO`
+ * **Command**: `java`
+ * **Arguments**: `-jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar`
+
+***
+
+## HTTP Mode ##
+
+Start the server first (see [Running the Server](https://github.com/apache/solr-mcp#running-the-server)), then:
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "url": "http://localhost:8080/mcp"
+ }
+ }
+}
+```
+
+Or in IDE Settings, select **SSE** transport and enter `http://localhost:8080/mcp` as the URL.
+
+The configuration is the same for secured and unsecured HTTP. JetBrains IDEs handle the MCP OAuth2 flow automatically.
+
+MCP support requires the AI Assistant plugin. See the [JetBrains MCP documentation](https://www.jetbrains.com/help/idea/model-context-protocol.html) for the latest configuration format.
diff --git a/docs/site/content/pages/mcp/clients/mcp-inspector.md b/docs/site/content/pages/mcp/clients/mcp-inspector.md
new file mode 100644
index 00000000..5dc72f63
--- /dev/null
+++ b/docs/site/content/pages/mcp/clients/mcp-inspector.md
@@ -0,0 +1,59 @@
+Title: MCP Inspector
+URL: mcp/clients/mcp-inspector.html
+save_as: mcp/clients/mcp-inspector.html
+template: mcp/client
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a web-based tool for testing and debugging MCP servers. It lets you browse available tools, invoke them interactively, and inspect responses.
+
+### Install ###
+
+```bash
+npx @modelcontextprotocol/inspector
+```
+
+This starts the Inspector UI at `http://localhost:6274`.
+
+***
+
+## STDIO Mode ##
+
+1. In MCP Inspector, select **STDIO** transport
+2. **Command**: `java`
+3. **Arguments**: `-jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar`
+4. Click **Connect**
+
+***
+
+## HTTP Mode ##
+
+1. Start the server in HTTP mode:
+
+ # JAR
+ PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
+
+ # Or Gradle
+ PROFILES=http ./gradlew bootRun
+
+ # Or Docker (local image — build first with ./gradlew jibDockerBuild)
+ docker run -p 8080:8080 --rm \
+ -e PROFILES=http \
+ -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+ solr-mcp:latest
+
+2. In MCP Inspector, enter: `http://localhost:8080/mcp`
+3. Click **Connect**
+
+**Linux users** (Docker option): add `--add-host=host.docker.internal:host-gateway` to the `docker run` command.
+
+***
+
+## OAuth2 ##
+
+When OAuth2 is enabled on the server, configure the Inspector's OAuth settings before connecting:
+
+1. Click the **OAuth** settings in the Inspector
+2. Enter your provider's Authorization URL, Token URL, Client ID, and Redirect URI (`http://localhost:6274/oauth/callback`)
+3. Complete the OAuth flow
+4. The Inspector will include the Bearer token in all subsequent requests
+
+See [Security](/mcp/security.html) for server-side OAuth2 setup with Auth0 and Keycloak.
diff --git a/docs/site/content/pages/mcp/clients/vs-code.md b/docs/site/content/pages/mcp/clients/vs-code.md
new file mode 100644
index 00000000..081cff26
--- /dev/null
+++ b/docs/site/content/pages/mcp/clients/vs-code.md
@@ -0,0 +1,85 @@
+Title: VS Code / GitHub Copilot
+URL: mcp/clients/vs-code.html
+save_as: mcp/clients/vs-code.html
+template: mcp/client
+
+[VS Code](https://code.visualstudio.com/) supports MCP servers through built-in MCP support (VS Code 1.99+). Solr MCP tools are available in GitHub Copilot Chat when using Agent mode.
+
+***
+
+## STDIO Mode (Recommended) ##
+
+### Workspace Configuration (`.vscode/mcp.json`) ###
+
+Create `.vscode/mcp.json` in your project root:
+
+**JAR:**
+
+```json
+{
+ "servers": {
+ "solr-mcp": {
+ "type": "stdio",
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": { "SOLR_URL": "http://localhost:8983/solr/" }
+ }
+ }
+}
+```
+
+**Docker (local image — build first with `./gradlew jibDockerBuild`):**
+
+```json
+{
+ "servers": {
+ "solr-mcp": {
+ "type": "stdio",
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/",
+ "solr-mcp:latest"]
+ }
+ }
+}
+```
+
+### User Settings (`settings.json`) ###
+
+Open VS Code Settings (JSON) and add:
+
+```json
+{
+ "mcp": {
+ "servers": {
+ "solr-mcp": {
+ "type": "stdio",
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": { "SOLR_URL": "http://localhost:8983/solr/" }
+ }
+ }
+ }
+}
+```
+
+***
+
+## HTTP Mode ##
+
+Start the server first (see [Running the Server](https://github.com/apache/solr-mcp#running-the-server)), then:
+
+```json
+{
+ "servers": {
+ "solr-mcp": {
+ "type": "http",
+ "url": "http://localhost:8080/mcp"
+ }
+ }
+}
+```
+
+The configuration is the same for secured and unsecured HTTP. VS Code handles the MCP OAuth2 flow automatically.
+
+See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for the latest configuration format.
diff --git a/docs/site/content/pages/mcp/community.md b/docs/site/content/pages/mcp/community.md
new file mode 100644
index 00000000..e2e5b9a2
--- /dev/null
+++ b/docs/site/content/pages/mcp/community.md
@@ -0,0 +1,42 @@
+Title: Community
+URL: mcp/community.html
+save_as: mcp/community.html
+template: mcp/community
+
+## Support ##
+
+The Solr MCP community provides user support for free through the [users mailing list](#mailing-lists-chat) and [slack channels](#slack).
+
+## Mailing Lists & Chat ##
+
+The Solr MCP server shares mailing lists with its parent project, Apache Solr.
+Available lists can be [found here]({filename}/pages/community.md#mailing-lists-chat).
+
+#### Slack ####
+
+* The project's main Slack channel is `#solr-mcp` in the `the-asf` organization.
+ Link:
+
+## Issue tracker ##
+
+The Solr MCP Server uses [Github issues](https://github.com/apache/solr-mcp/issues) in its repository for issue tracking.
+
+## How To Contribute ##
+
+Looking to contribute to the Solr MCP Server? Read the [CONTRIBUTING.md](https://github.com/apache/solr-mcp/blob/main/CONTRIBUTING.md) instructions and join us.
+
+## Code of Conduct ##
+
+For a large and diverse community like ours to be friendly, welcoming and respectful, we recognize the need for some guidelines. The project follows [Apache's Code of Conduct statement](https://www.apache.org/foundation/policies/conduct). Please take some time to read and understand it.
+
+If you feel there has been a violation of this code, please point out your concerns publicly in a friendly and matter of fact manner. Nonverbal communication is prone to misinterpretation and misunderstanding. Everyone has bad days and sometimes says things they regret later. Someone else's communication style may clash with yours, but the difference can be amicably resolved. After pointing out your concerns please be generous upon receiving an apology.
+
+Should there be repeated instances of code of conduct violations, or if there is an obvious and severe violation, the Solr PMC may become involved.
+
+### The Apache Way
+
+As an Apache project we strive to follow [The Apache Way](http://theapacheway.com/). If you are new to the community or to open source in general, you may benefit from understanding our core values as a community, and why we operate the way we do.
+
+## Version Control ##
+
+The project's Git repository is found at https://github.com/apache/solr-mcp or the mirror at https://gitbox.apache.org/repos/asf/solr-mcp.git
diff --git a/docs/site/content/pages/mcp/downloads.md b/docs/site/content/pages/mcp/downloads.md
new file mode 100644
index 00000000..8e59896a
--- /dev/null
+++ b/docs/site/content/pages/mcp/downloads.md
@@ -0,0 +1,5 @@
+Title: Downloads
+URL: mcp/downloads.html
+save_as: mcp/downloads.html
+template: mcp/downloads
+
diff --git a/docs/site/content/pages/mcp/features.md b/docs/site/content/pages/mcp/features.md
new file mode 100644
index 00000000..6e96e5ec
--- /dev/null
+++ b/docs/site/content/pages/mcp/features.md
@@ -0,0 +1,4 @@
+Title: Features
+URL: mcp/features.html
+save_as: mcp/features.html
+template: mcp/features
diff --git a/docs/site/content/pages/mcp/index.md b/docs/site/content/pages/mcp/index.md
new file mode 100644
index 00000000..b9d9a795
--- /dev/null
+++ b/docs/site/content/pages/mcp/index.md
@@ -0,0 +1,4 @@
+Title: Welcome
+URL: mcp/index.html
+save_as: mcp/index.html
+template: mcp/index
diff --git a/docs/site/content/pages/mcp/licensing.md b/docs/site/content/pages/mcp/licensing.md
new file mode 100644
index 00000000..d1bcb8fa
--- /dev/null
+++ b/docs/site/content/pages/mcp/licensing.md
@@ -0,0 +1,98 @@
+Title: Licensing & Notices
+URL: mcp/licensing.html
+save_as: mcp/licensing.html
+template: mcp/licensing
+
+## Overview ##
+
+Apache Solr MCP Server is licensed under the **Apache License 2.0**. Because the project is distributed in two different forms, it ships two different pairs of `LICENSE` and `NOTICE` files, each describing what is actually in that form:
+
+| Form | Artifacts | Contains | LICENSE / NOTICE |
+|------|-----------|----------|------------------|
+| **Source** | the source tree, `-sources` / `-javadoc` jars | only Apache-authored code | the base Apache-2.0 `LICENSE` + a minimal `NOTICE` |
+| **Binary** | the executable (fat) JAR and the Docker images built from it | Apache code **plus** every bundled third-party dependency | the base files **extended** with each bundled dependency's license and the notices those dependencies require |
+
+This split follows the [ASF licensing how-to](https://infra.apache.org/licensing-howto.html): a binary that bundles other projects' code must tell recipients the license of every bundled component, and must carry forward the attribution notices those components require. The source release, which contains only Apache-authored code, needs only the base files.
+
+***
+
+## Where the Files Live ##
+
+The **binary** `LICENSE` and `NOTICE` are bundled inside the executable JAR's `META-INF/` directory, so they travel with every distribution:
+
+* **Executable JAR** — `META-INF/LICENSE` and `META-INF/NOTICE` inside `solr-mcp-.jar`.
+* **Docker images** — the same files, since both the Jib JVM image and the native images package the JAR's contents. They are present on the classpath at `META-INF/` in the running container.
+
+To read them straight out of a built artifact:
+
+```bash
+unzip -p solr-mcp-.jar META-INF/LICENSE
+unzip -p solr-mcp-.jar META-INF/NOTICE
+```
+
+The **source** `LICENSE` and `NOTICE` are the files at the root of the [source repository](https://github.com/apache/solr-mcp) and are bundled, unchanged, into the thin `jar`, `-sources`, and `-javadoc` artifacts.
+
+***
+
+## Building the Files ##
+
+The binary `LICENSE` and `NOTICE` are **generated during the build** — they are not checked in, so they always match the exact set of dependencies that ship. Any normal build produces them:
+
+```bash
+./gradlew build # full build (tests + the executable JAR)
+./gradlew bootJar # just the executable JAR
+```
+
+To generate only the two files for inspection, without assembling the JAR:
+
+```bash
+./gradlew generateBinaryLicense generateBinaryNotice
+```
+
+They are written to:
+
+```text
+build/generated/license/LICENSE
+build/generated/license/NOTICE
+```
+
+… and bundled into `META-INF/` of the executable JAR. The build **fails** if a bundled dependency cannot be accounted for (see [How They Are Constructed](#how-they-are-constructed)), so an incomplete `LICENSE` can never be released by accident.
+
+***
+
+## How They Are Constructed ##
+
+Both files are assembled by a small Gradle convention plugin (`org.apache.solr.mcp.license-notice`, in `buildSrc/`) from two tasks.
+
+### LICENSE ###
+
+`generateBinaryLicense` writes the full Apache-2.0 license text, followed by a **third-party dependency appendix**. Each dependency that ships in the binary is listed with the license it is distributed under and a link to that license's text, for example:
+
+```text
+- org.apache.solr:solr-solrj:
+ License: Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html
+- ch.qos.logback:logback-classic:
+ License: EPL-2.0 — https://spdx.org/licenses/EPL-2.0.html
+ License: GNU Lesser General Public License — https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
+```
+
+The license for each dependency is taken from the project's [SBOM](#role-of-the-sbom). Licenses are listed exactly as the SBOM reports them: the appendix is a disclosure rather than a policy, so it applies no allow-list and no manual corrections, and a few upstream labels may be imprecise (they are always permissive). The link next to each entry points to the authoritative license text.
+
+### NOTICE ###
+
+`generateBinaryNotice` writes the project's own `NOTICE`, followed by the `NOTICE` files of the bundled dependencies that ship one — copied **verbatim**, de-duplicated, and each attributed to the dependency it came from. This satisfies the Apache-2.0 requirement to carry forward the attribution notices of redistributed code, so the notices from bundled Apache projects such as SolrJ are preserved automatically. It is intentionally limited to **required** notices; it is not a general credits list.
+
+***
+
+## Role of the SBOM ##
+
+The project also publishes a **CycloneDX Software Bill of Materials (SBOM)** — a machine-readable inventory of every bundled component, with versions, hashes, and licenses. It is generated by the `cyclonedxBom` task, embedded in the executable JAR at `META-INF/sbom/application.cdx.json`, and served at `/actuator/sbom/application` in HTTP mode.
+
+The SBOM and the `LICENSE`/`NOTICE` files play complementary roles:
+
+* The **SBOM** is the machine-readable inventory, designed for supply-chain and security tooling — *what is in here, at which versions, under which licenses?*
+* The **`LICENSE` and `NOTICE`** files are the human-readable legal artifacts that the Apache License and ASF release policy require.
+
+They are connected: the binary `LICENSE` appendix is **generated from the SBOM**, so the two never drift apart, and the appendix includes a pointer back to the SBOM for the full machine-readable detail. The SBOM does **not** replace `LICENSE`/`NOTICE` — in particular it has no concept of a `NOTICE` file, so the required attribution notices are aggregated directly from the dependencies instead.
+
+Unlike Apache Solr's main distribution, this project does **not** maintain a per-dependency `licenses/` folder; the SBOM plus the generated appendix cover the same ground with nothing to hand-maintain.
diff --git a/docs/site/content/pages/mcp/observability.md b/docs/site/content/pages/mcp/observability.md
new file mode 100644
index 00000000..46da40be
--- /dev/null
+++ b/docs/site/content/pages/mcp/observability.md
@@ -0,0 +1,114 @@
+Title: Observability
+URL: mcp/observability.html
+save_as: mcp/observability.html
+template: mcp/observability
+
+## Overview ##
+
+When running in **HTTP mode**, the Solr MCP Server exports telemetry data via OpenTelemetry to the **LGTM stack** (Loki, Grafana, Tempo, Mimir) for full observability.
+
+| Signal | Backend | What it shows |
+|--------|---------|---------------|
+| **Traces** | Tempo | Distributed traces for every MCP tool invocation, Solr query, and HTTP request |
+| **Metrics** | Mimir/Prometheus | JVM stats, HTTP request rates, Solr query latencies, cache hit ratios |
+| **Logs** | Loki | Structured application logs correlated with trace IDs |
+
+Every MCP tool invocation creates a trace span: search, indexing (JSON, CSV, XML), collection operations (list, stats, health, create), and schema retrieval. All incoming HTTP requests and outgoing Solr calls are automatically traced.
+
+***
+
+## Setup ##
+
+### Start the LGTM Stack ###
+
+The project's `compose.yaml` includes a Grafana OTEL LGTM all-in-one container:
+
+```bash
+docker compose up -d
+```
+
+This starts:
+
+| Service | URL | Purpose |
+|---------|-----|---------|
+| Grafana | http://localhost:3000 | Dashboards and exploration (no auth required) |
+| OTLP gRPC | localhost:4317 | Trace/metric/log ingestion (gRPC) |
+| OTLP HTTP | localhost:4318 | Trace/metric/log ingestion (HTTP) |
+
+### Run the Server with Observability ###
+
+```bash
+PROFILES=http ./gradlew bootRun
+```
+
+The server auto-configures OTLP export when the LGTM stack is running. Default configuration:
+
+```properties
+management.tracing.sampling.probability=1.0 # 100% sampling (dev)
+otel.exporter.otlp.endpoint=http://localhost:4317
+otel.exporter.otlp.protocol=grpc
+```
+
+***
+
+## Grafana ##
+
+Open [http://localhost:3000](http://localhost:3000) and click **Explore** in the left sidebar.
+
+### View Traces (Tempo) ###
+
+1. Select **Tempo** as the data source
+2. Use TraceQL to search:
+
+ {.service.name="solr-mcp"}
+
+3. Click on a trace to see the span waterfall—each MCP tool invocation, Solr query, and HTTP request is a separate span
+
+### View Logs (Loki) ###
+
+1. Select **Loki** as the data source
+2. Use LogQL to search:
+
+ {service_name="solr-mcp"} |= "search"
+
+3. Logs are automatically correlated with trace IDs—click a log line to jump to its trace
+
+### View Metrics (Prometheus) ###
+
+1. Select **Prometheus** as the data source
+2. Example queries:
+
+ # HTTP request rate
+ rate(http_server_requests_seconds_count[5m])
+
+ # JVM memory usage
+ jvm_memory_used_bytes
+
+ # Request latency (p99)
+ histogram_quantile(0.99, rate(http_server_requests_seconds_bucket[5m]))
+
+***
+
+## Actuator Endpoints ##
+
+The following health and metrics endpoints are exposed in HTTP mode:
+
+```bash
+curl http://localhost:8080/actuator/health # Health check
+curl http://localhost:8080/actuator/info # Build info
+curl http://localhost:8080/actuator/metrics # Available metrics
+curl http://localhost:8080/actuator/prometheus # Prometheus scrape endpoint
+curl http://localhost:8080/actuator/loggers # Logger levels
+```
+
+***
+
+## Production Configuration ##
+
+For production, reduce the sampling rate and configure the OTLP endpoint for your collector:
+
+```bash
+export OTEL_SAMPLING_PROBABILITY=0.1 # 10% sampling
+export OTEL_TRACES_URL=https://otel-collector.example.com:4317
+PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
+```
diff --git a/docs/site/content/pages/mcp/quick-start.md b/docs/site/content/pages/mcp/quick-start.md
new file mode 100644
index 00000000..f31f06c9
--- /dev/null
+++ b/docs/site/content/pages/mcp/quick-start.md
@@ -0,0 +1,132 @@
+Title: Quick Start
+URL: mcp/quick-start.html
+save_as: mcp/quick-start.html
+template: mcp/quick-start
+
+## Prerequisites ##
+
+* Java 25+ ([Eclipse Temurin](https://adoptium.net/) recommended)
+* [Docker](https://docs.docker.com/get-docker/) and Docker Compose
+* Apache Solr **8.11–10** (the bundled sample stack runs Solr 9; the server is tested against 8.11, 9.4, 9.9, 9.10, and 10)
+* An MCP client — this guide uses [Claude Desktop](https://claude.ai/download), but any MCP-compatible client works. See [Adding to AI Clients](/mcp/clients/claude-desktop.html) for other options.
+
+## Start Solr with Sample Data ##
+
+Clone the repository and start Solr in SolrCloud mode:
+
+```bash
+git clone https://github.com/apache/solr-mcp.git
+cd solr-mcp
+docker compose up -d
+```
+
+This starts Solr with ZooKeeper and creates two sample collections pre-loaded with data:
+
+* **films** — 1,100+ movie records with titles, directors, genres, and release dates
+* **books** — empty collection ready for indexing
+
+Wait ~30 seconds for Solr to fully initialize. Verify at [http://localhost:8983/solr/](http://localhost:8983/solr/).
+
+## Build the Server ##
+
+```bash
+./gradlew build
+```
+
+This produces `build/libs/solr-mcp-1.0.0-SNAPSHOT.jar`.
+
+## Configure Your MCP Client ##
+
+Add the following to your Claude Desktop configuration file:
+
+* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp/build/libs/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": { "SOLR_URL": "http://localhost:8983/solr/" }
+ }
+ }
+}
+```
+
+Restart Claude Desktop after saving.
+
+**Alternatively**, you can use a local Docker image:
+
+```bash
+./gradlew jibDockerBuild
+```
+
+Then configure Claude Desktop with:
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/",
+ "solr-mcp:latest"]
+ }
+ }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the args array.
+
+## Native Image (experimental) ##
+
+Opt-in GraalVM native image builds are available for both **STDIO** and **HTTP** transports. Native binaries start in milliseconds and use substantially less memory than the JVM image. Spring AOT bakes a profile-specific bean graph at build time, so each native image is single-transport — pick the one that matches your client.
+
+```bash
+# Build the native STDIO image
+./gradlew bootBuildImage -Pnative
+# Produces: solr-mcp:1.0.0-SNAPSHOT-native-stdio (also tagged :latest-native-stdio)
+
+# Build the native HTTP image
+./gradlew bootBuildImage -Pnative -Pprofile=http
+# Produces: solr-mcp:1.0.0-SNAPSHOT-native-http (also tagged :latest-native-http)
+```
+
+Configure Claude Desktop with the native STDIO image:
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/",
+ "solr-mcp:latest-native-stdio"]
+ }
+ }
+}
+```
+
+For dual-transport support from a single image (e.g. switch between modes via `PROFILES` env var without rebuilding), use the JVM Jib image above. The JVM image trades startup time and memory footprint for transport flexibility.
+
+## Try It Out ##
+
+Open Claude Desktop and try these prompts:
+
+* *"Search the films collection for movies directed by Steven Spielberg"*
+* *"What collections are available in Solr?"*
+* *"Show me the schema for the films collection"*
+* *"Find all sci-fi movies released after 2000 and show the genre breakdown"*
+* *"Index this JSON into the books collection: [{"id": "1", "title": "The Great Gatsby", "author": "F. Scott Fitzgerald"}]"*
+
+**Tip:** clients that support MCP completions autocomplete collection names — for the `{collection}` in the `solr://{collection}/schema` resource and for the `collection` argument of the `search-collection`, `index-data`, `view-schema`, and `design-schema` prompts.
+
+***
+
+## Next Steps ##
+
+* **[Adding to AI Clients](/mcp/clients/claude-desktop.html)** — configure Claude Code, VS Code, Cursor, JetBrains, or MCP Inspector
+* **[Features](/mcp/features.html)** — explore all available tools and resources
+* **[Security](/mcp/security.html)** — set up OAuth2 authentication for HTTP mode
+* **[Observability](/mcp/observability.html)** — enable tracing, metrics, and logging
diff --git a/docs/site/content/pages/mcp/resources.md b/docs/site/content/pages/mcp/resources.md
new file mode 100644
index 00000000..a64b238f
--- /dev/null
+++ b/docs/site/content/pages/mcp/resources.md
@@ -0,0 +1,48 @@
+Title: Resources
+URL: mcp/resources.html
+save_as: mcp/resources.html
+template: mcp/resources
+
+## Guides ##
+
+* **[Quick Start](/mcp/quick-start.html)** — get from zero to a working AI + Solr integration in under 2 minutes
+* **[Security (OAuth2)](/mcp/security.html)** — Auth0 and Keycloak setup for HTTP mode
+* **[Observability](/mcp/observability.html)** — traces, metrics, and logs via the LGTM stack
+* **[Licensing & Notices](/mcp/licensing.html)** — where the binary LICENSE/NOTICE live, how they are built, and the role of the SBOM
+
+## Documentation ##
+
+* [README](https://github.com/apache/solr-mcp#readme) — quick start, client configurations, and usage overview
+* [CONTRIBUTING](https://github.com/apache/solr-mcp/blob/main/CONTRIBUTING.md) — pull request process and commit conventions
+* [Architecture](https://github.com/apache/solr-mcp/blob/main/dev-docs/ARCHITECTURE.md) — project structure and design decisions
+* [Development Guide](https://github.com/apache/solr-mcp/blob/main/dev-docs/DEVELOPMENT.md) — build system, testing, and IDE setup
+* [Auth0 Setup](https://github.com/apache/solr-mcp/blob/main/docs/security/auth0.md) — detailed OAuth2 setup with Auth0
+* [Keycloak Setup](https://github.com/apache/solr-mcp/blob/main/docs/security/keycloak.md) — detailed OAuth2 setup with Keycloak
+
+***
+
+## References ##
+
+### MCP Protocol ###
+
+* [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
+* [MCP GitHub Organization](https://github.com/modelcontextprotocol)
+* [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
+
+### Spring AI MCP ###
+
+* [Spring AI MCP Server (Spring Boot)](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot.html)
+* [Spring AI MCP Project](https://spring.io/projects/spring-ai)
+* [Spring AI Community MCP Security](https://github.com/spring-ai-community/mcp-security)
+
+### Apache Solr ###
+
+* [Apache Solr Documentation](https://solr.apache.org/guide/)
+* [SolrJ Client Library](https://solr.apache.org/guide/solr/latest/deployment-guide/solrj.html)
+
+### Tools and Libraries ###
+
+* [Jib (Docker image builder)](https://github.com/GoogleContainerTools/jib)
+* [Testcontainers](https://www.testcontainers.org/)
+* [OpenTelemetry](https://opentelemetry.io/)
+* [Grafana LGTM Stack](https://github.com/grafana/docker-otel-lgtm)
diff --git a/docs/site/content/pages/mcp/security.md b/docs/site/content/pages/mcp/security.md
new file mode 100644
index 00000000..e9e399e7
--- /dev/null
+++ b/docs/site/content/pages/mcp/security.md
@@ -0,0 +1,175 @@
+Title: Security
+URL: mcp/security.html
+save_as: mcp/security.html
+template: mcp/security
+
+## Overview ##
+
+When running in HTTP mode, the Solr MCP Server supports **OAuth2 authentication** with JWT token validation. Security is **enabled by default** in HTTP mode — point it at an OAuth2 issuer to use it, or disable it for local development.
+
+* **Protocol**: OAuth2 Resource Server with JWT validation
+* **Supported providers**: Auth0, Keycloak, Okta, or any OAuth2/OIDC provider
+* **STDIO mode**: Security is not applicable (OS-level process isolation)
+* **HTTP mode**: **Secured by default** — set `OAUTH2_ISSUER_URI` to wire up a provider; disable for local dev only with `HTTP_SECURITY_ENABLED=false`
+
+### Configure Security ###
+
+HTTP mode is secured by default — you only need to point it at an OAuth2 issuer:
+
+```bash
+export PROFILES=http
+export OAUTH2_ISSUER_URI=https://your-provider.example.com/
+./gradlew bootRun
+```
+
+Or with Docker (local image — build first with `./gradlew jibDockerBuild`):
+
+```bash
+docker run -p 8080:8080 --rm \
+ -e PROFILES=http \
+ -e OAUTH2_ISSUER_URI=https://your-provider.example.com/ \
+ -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+ solr-mcp:latest
+```
+
+To turn authentication **off** for local development, set `HTTP_SECURITY_ENABLED=false`.
+
+***
+
+## Auth0 ##
+
+### 1. Create Auth0 Application ###
+
+1. Go to [Auth0 Dashboard](https://manage.auth0.com/) > **Applications** > **Create Application**
+2. Name: `Solr MCP Server`
+3. Type: **Machine to Machine Applications**
+4. Note your **Domain**, **Client ID**, and **Client Secret**
+
+### 2. Create Auth0 API ###
+
+1. Navigate to **Applications** > **APIs** > **Create API**
+2. Name: `Solr MCP API`
+3. Identifier (audience): `https://solr-mcp-api`
+4. Signing Algorithm: **RS256**
+
+### 3. Configure Callback URLs ###
+
+In your application settings, add to **Allowed Callback URLs**:
+
+ http://localhost:6274/oauth/callback,http://localhost:3334/oauth/callback,http://localhost:8080/login/oauth2/code/auth0
+
+Each callback URL serves a different client:
+
+* `http://localhost:6274/oauth/callback` — MCP Inspector
+* `http://localhost:3334/oauth/callback` — `mcp-remote` (Claude Desktop, VS Code, Cursor, JetBrains in HTTP mode)
+* `http://localhost:8080/login/oauth2/code/auth0` — Direct server OAuth2 code flow
+
+### 4. Run the Server ###
+
+```bash
+export PROFILES=http
+export OAUTH2_ISSUER_URI=https://your-tenant.auth0.com/
+./gradlew bootRun
+```
+
+### 5. Get an Access Token ###
+
+```bash
+curl --request POST \
+ --url https://your-tenant.auth0.com/oauth/token \
+ --header 'content-type: application/json' \
+ --data '{
+ "client_id": "YOUR_CLIENT_ID",
+ "client_secret": "YOUR_CLIENT_SECRET",
+ "audience": "https://solr-mcp-api",
+ "grant_type": "client_credentials"
+ }'
+```
+
+Or use the convenience script:
+
+```bash
+./scripts/get-auth0-token.sh \
+ --domain your-tenant.auth0.com \
+ --client-id YOUR_CLIENT_ID \
+ --client-secret YOUR_CLIENT_SECRET \
+ --audience https://solr-mcp-api
+```
+
+### 6. Use the Token ###
+
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+ http://localhost:8080/mcp
+```
+
+For the full step-by-step guide, see [Auth0 Setup Guide](https://github.com/apache/solr-mcp/blob/main/docs/security/auth0.md).
+
+***
+
+## Keycloak ##
+
+### 1. Start Keycloak ###
+
+```bash
+docker run -d --name keycloak \
+ -p 8180:8080 \
+ -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
+ -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
+ quay.io/keycloak/keycloak:26.0 start-dev
+```
+
+Access the admin console at `http://localhost:8180` (login: `admin` / `admin`).
+
+### 2. Create Realm and Client ###
+
+1. Create realm: `solr-mcp`
+2. Create client:
+ * Client ID: `solr-mcp-client`
+ * Client type: OpenID Connect
+ * Client authentication: OFF (public client)
+ * Valid redirect URIs: `http://localhost:6274/*`, `http://localhost:3334/*`, `http://localhost:8080/*`
+ * Web origins: `*`
+
+### 3. Create Test User ###
+
+1. Navigate to **Users** > **Add user**
+2. Username: `testuser`, Email verified: ON
+3. Set password in **Credentials** tab
+
+### 4. Run the Server ###
+
+```bash
+export PROFILES=http
+export OAUTH2_ISSUER_URI=http://localhost:8180/realms/solr-mcp
+./gradlew bootRun
+```
+
+### 5. Get a Token ###
+
+```bash
+curl -X POST "http://localhost:8180/realms/solr-mcp/protocol/openid-connect/token" \
+ -H "Content-Type: application/x-www-form-urlencoded" \
+ -d "client_id=solr-mcp-client" \
+ -d "username=testuser" \
+ -d "password=yourpassword" \
+ -d "grant_type=password"
+```
+
+For the full guide including role-based access control and production deployment, see [Keycloak Setup Guide](https://github.com/apache/solr-mcp/blob/main/docs/security/keycloak.md).
+
+***
+
+## How OAuth2 Works with MCP Clients ##
+
+When a client connects to a secured Solr MCP Server:
+
+1. Client connects to `/mcp`
+2. Server responds with `401` + OAuth2 metadata
+3. Client discovers the authorization server from `/.well-known/oauth-authorization-server`
+4. Client opens a browser for login/consent
+5. Client receives an authorization code, exchanges it for an access token (JWT)
+6. Client attaches the Bearer token to all subsequent MCP requests
+7. Server validates the JWT with the OAuth2 provider
+
+Most MCP clients handle this flow transparently—the configuration is the same for secured and unsecured HTTP servers. See the individual [client setup pages](/mcp/clients/claude-desktop.html) for details.
diff --git a/docs/superpowers/specs/2026-06-09-license-notice-and-docs-deploy-design.md b/docs/superpowers/specs/2026-06-09-license-notice-and-docs-deploy-design.md
new file mode 100644
index 00000000..5d4712d0
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-09-license-notice-and-docs-deploy-design.md
@@ -0,0 +1,161 @@
+# Design: Binary-release LICENSE/NOTICE tooling + docs-in-code-repo deploy
+
+Date: 2026-06-09
+Author: adityamparikh (with Claude)
+Addresses:
+- apache/solr-mcp#138 review comment [`r3361858982`](https://github.com/apache/solr-mcp/pull/138#discussion_r3361858982) + follow-up `r3383830232`
+- apache/solr-site#175 comment [`4664039372`](https://github.com/apache/solr-site/pull/175#issuecomment-4664039372)
+
+These are two independent deliverables tracked in one spec because they were raised together.
+
+---
+
+## Deliverable 1 — Binary-release LICENSE/NOTICE (solr-mcp)
+
+### Problem
+
+PR #138 adds the base Apache-2.0 `LICENSE` and a minimal `NOTICE`, and bundles them
+into the `META-INF/` of every jar. Per
+[infra.apache.org/licensing-howto](https://infra.apache.org/licensing-howto.html):
+
+- For the **source release**, those base files are correct — the source tree contains
+ only ASF-authored code under Apache-2.0.
+- For a **binary release**, the artifact bundles third-party bytecode, so:
+ - `LICENSE` must additionally enumerate every bundled non-Apache dependency and
+ point to its license (a link, not the full license text).
+ - `NOTICE` must lift the relevant NOTICE snippets of bundled **Apache-licensed**
+ dependencies (notably other ASF projects such as SolrJ).
+
+The project's binary artifact is the Spring Boot fat jar (`bootJar`) — it embeds every
+runtime dependency. There is no tgz/`distZip`/`installDist` packaging, so "binary
+release" == the `bootJar`. (An SBOM was added on a separate branch; per JanHoy it is
+complementary, not a substitute for LICENSE/NOTICE.)
+
+### Approach — SBOM-driven, in a buildSrc convention plugin
+
+> **As shipped (PR #138).** An earlier draft generated the appendix with the
+> `com.github.jk1.dependency-license-report` plugin plus a hand-kept supplement for the
+> Gradle-module-metadata-only ASF artifacts (SolrJ) that the POM-only plugin silently
+> drops. We instead **derive the appendix from the CycloneDX SBOM** (PR #142), which
+> already resolves a license for every component including SolrJ — so no supplement is
+> needed and there is a single source of dependency data. PR #138 is therefore stacked
+> on #142.
+
+Implemented as the `org.apache.solr.mcp.license-notice` convention plugin under
+`buildSrc/`, with two typed tasks. The root `build.gradle.kts` only applies the plugin.
+
+1. **`GenerateBinaryLicense`.** Reads the CycloneDX SBOM
+ (`build/reports/application.cdx.json`, the same SBOM embedded in the bootJar at
+ `META-INF/sbom/application.cdx.json`), indexes each component's licenses by
+ `group:name(:version)`, and emits the binary `LICENSE` = base Apache-2.0 + an appendix
+ of every shipped dependency and a link to its license. "Shipped" = the resolved
+ `productionRuntimeClasspath` (excludes test/compile-only and `developmentOnly` deps).
+2. **`GenerateBinaryNotice`.** Builds the binary `NOTICE` = base NOTICE + the
+ `META-INF/NOTICE` files lifted verbatim and de-duplicated from the bundled jars (the
+ Maven-Shade `ApacheNoticeResourceTransformer` approach), so ASF dependency notices are
+ carried and stay current with no hand-maintained snippets.
+3. **`metaInf` wiring.** The `bootJar` bundles the generated LICENSE/NOTICE; the plain
+ `jar`, sources, and javadoc jars keep the source-form base files.
+4. **Licenses are disclosed as-reported.** The appendix is a disclosure, not a license
+ policy. Licenses are listed exactly as the SBOM declares them — **no allow-list and no
+ corrections** — so a few imprecise-but-permissive upstream labels appear as-is
+ (`mcp-server-security` → `Apache-1.0`; ANTLR `ST4`/`antlr-runtime` →
+ `BSD-4-Clause`/`BSD licence`); the preamble notes this and links each license. apache/solr
+ itself keeps no allow-list (it uses a per-dependency `solr/licenses/` folder, which
+ JanHoy said not to replicate), so neither do we.
+5. **Completeness gate.** The only gate: `generateBinaryLicense` runs as part of
+ `check`/`build` and **fails if a shipped dependency is absent from the SBOM**, so a
+ dependency can never be silently omitted from the LICENSE. This is JanHoy's "check that
+ newly added deps are accounted for"; it makes no judgement about license acceptability.
+6. **Tests.** The two tasks are unit-tested with `ProjectBuilder`
+ (`buildSrc/src/test/kotlin/.../LicenseNoticeTasksTest.kt`): appendix listing, SBOM
+ name/URL handling, the completeness gate, and NOTICE de-duplication. `buildSrc`'s
+ `test` runs in `./gradlew build`.
+6. **Verify.** `./gradlew build`, then
+ `unzip -p build/libs/solr-mcp-.jar META-INF/LICENSE` / `... META-INF/NOTICE`
+ to confirm the appendix and lifted notices are present in the fat jar.
+
+### Out of scope (YAGNI)
+
+- No Solr-style per-dependency `licenses/` folder — JanHoy explicitly said the rigid
+ version is unnecessary.
+- No tgz packaging — the project does not ship one; "binary release" == the `bootJar`.
+- The source-form `LICENSE`/`NOTICE` are already correct and unchanged.
+
+### Files touched
+
+- `buildSrc/` — the `org.apache.solr.mcp.license-notice` convention plugin and the
+ `GenerateBinaryLicense` / `GenerateBinaryNotice` typed tasks (+ their unit tests).
+- `build.gradle.kts` — applies `id("org.apache.solr.mcp.license-notice")` (after the
+ Spring Boot + CycloneDX plugins).
+- `AGENTS.md` — "Release LICENSE / NOTICE" section.
+- Depends on PR #142 (CycloneDX SBOM) for the `cyclonedxBom` task and plugin.
+
+---
+
+## Deliverable 2 — Docs source in code repo, deployed to site (solr-mcp + solr-site)
+
+### Problem
+
+JanHoy wants the MCP docs to live in the **solr-mcp** repo (so every feature PR carries
+its documentation update) but still be **deployed to the Solr site**. The Solr ref guide
+does this by building the static site elsewhere and copying the output into a location
+mounted into the web server via `.htaccess`.
+
+### Constraint discovered
+
+solr-site is a **Pelican** site (`pelican content -o output`, published via ASF
+`.asf.yaml` — `main`/`production` protected branches, `asf-staging`). PR #175 splits
+cleanly into two layers:
+
+- **Content** (the docs *source*): `content/pages/mcp/*.md`,
+ `content/pages/mcp/clients/*.md`, `content/doap/solr-mcp.rdf` — plain markdown with
+ Pelican front-matter.
+- **Presentation** (the site's rendering layer): `themes/solr/templates/mcp/*.html`,
+ `themes/solr/static/css/mcp.css`, `pelicanconf.py`, shared header/index edits.
+
+The content reuses the solr-site theme. A fully standalone build inside solr-mcp would
+have to vendor that theme and drift from the rest of the site.
+
+### Approach — solr-site pulls content from solr-mcp at build time
+
+Keep one themed Pelican build in solr-site; make solr-mcp the source of truth for the
+**content** layer only.
+
+1. **solr-mcp** owns the markdown. Move the content layer into
+ `solr-mcp/docs/site/content/` (markdown + DOAP). Feature PRs edit docs here alongside
+ code. A `docs/site/README.md` explains that these files are assembled into the Solr
+ site at build time.
+2. **solr-site** keeps the presentation layer (templates, CSS, `pelicanconf.py`).
+3. **Assembly at build time.** solr-site's `build.sh` (and the CI build) fetches the
+ `docs/site/content/` tree from solr-mcp at a **pinned ref** (a release tag, falling
+ back to `main`) and copies it into `content/pages/mcp/` (and the DOAP into
+ `content/doap/`) before running Pelican. Implemented as a `fetch_mcp_docs` step:
+ shallow `git clone --depth 1 --branch [` of solr-mcp into a temp dir, `rsync`
+ the content into place. The pinned ref lives in one variable in `build.sh` /
+ `pelicanconf.py` so bumping the published docs version is a one-line change.
+4. **Remove** the moved markdown from solr-site so there is a single source of truth;
+ leave a short note in solr-site explaining where MCP content now comes from.
+
+This mirrors the ref-guide model (content built/owned elsewhere, assembled into the
+site) while keeping the shared theme and a single Pelican build.
+
+### Rejected alternative
+
+**solr-mcp pushes built static HTML** into a `/mcp/` subdir of solr-site's `production`
+branch via a release Action. Closest literal match to the `.htaccess`-mounted ref-guide
+output, but requires vendoring the Pelican theme in solr-mcp (drift) and a cross-repo
+push token. Rejected in favor of the pull model.
+
+### Files touched
+
+- **solr-mcp:** add `docs/site/content/**` (moved markdown + DOAP), `docs/site/README.md`.
+- **solr-site:** `build.sh` (+ CI workflow) gains a `fetch_mcp_docs` step; remove
+ `content/pages/mcp/**` and `content/doap/solr-mcp.rdf`; keep theme/templates/CSS/
+ `pelicanconf.py`; add a note documenting the source-of-truth.
+
+### Sequencing / review
+
+This spans two repos and changes how an in-review PR (#175) is structured, so the
+mechanism is proposed to JanHoy (reply on #175) and the cross-repo changes are staged on
+branches for review — nothing is pushed to the public PRs without maintainer sign-off.
]