RandomCodeSpace · aksOps · May 23, 2026 · May 23, 2026 · May 23, 2026
diff --git a/.gitignore b/.gitignore
@@ -15,3 +15,6 @@ dependency-reduced-pom.xml
 # module. Not committed to keep the repo lean. The distribution build (dist
 # module) fetches its own copies through Maven and does not use this directory.
 daemon/plugins/*.jar
+
+# sonar-predictor scan output, written by `bin/sonar agent-scan`. Never commit.
+.sonar-predictor/
diff --git a/NOTICE b/NOTICE
@@ -0,0 +1,99 @@
+sonar-predictor
+Copyright 2025–2026 Amit Kumar and the sonar-predict contributors
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+================================================================================
+THIRD-PARTY COMPONENTS
+================================================================================
+
+`sonar-predictor` invokes third-party analyzers and libraries at runtime. The
+following components are NOT redistributed inside this repository (the
+installable plugin) — the launcher downloads them on first invocation from
+Maven Central. They are listed here for transparency about what your machine
+runs after you install this plugin.
+
+------------------------------------------------------------------------------
+SonarSource analysis engine
+------------------------------------------------------------------------------
+
+  org.sonarsource.sonarlint.core:sonarlint-analysis-engine
+  License: GNU Lesser General Public License v3.0 (LGPL-3.0)
+  Source : https://github.com/SonarSource/sonarlint-core
+
+  The embedded analysis runtime — the same engine that powers SonarLint in
+  IDEs. The CLI and daemon link to it as a normal library dependency, which
+  is the use LGPL-3.0 is specifically designed to allow under any combining
+  license (including Apache 2.0).
+
+------------------------------------------------------------------------------
+SonarSource language analyzers
+------------------------------------------------------------------------------
+
+  org.sonarsource.java     :sonar-java-plugin
+  org.sonarsource.python   :sonar-python-plugin
+  org.sonarsource.javascript:sonar-javascript-plugin
+  org.sonarsource.php      :sonar-php-plugin
+  org.sonarsource.kotlin   :sonar-kotlin-plugin
+  org.sonarsource.slang    :sonar-go-plugin
+  org.sonarsource.slang    :sonar-ruby-plugin
+  org.sonarsource.slang    :sonar-scala-plugin
+  org.sonarsource.html     :sonar-html-plugin
+  org.sonarsource.xml      :sonar-xml-plugin
+
+  License: SONAR Source-Available License v1.0 (SSALv1)
+  Text   : https://www.sonarsource.com/license/ssal/
+
+  These are the per-language rule packs the analysis engine loads at runtime.
+  SonarSource relicensed them from LGPL v3 to SSALv1 in 2024. SSALv1 is
+  "source-available": it permits free internal use and free local execution
+  (what this tool does), and restricts using the analyzers to operate a
+  competing "Service Offering". Read the full license text at the link above
+  before using `sonar-predictor` to build a hosted service offering.
+
+  No source code from these analyzers is included in this repository.
+  `sonar-predictor` invokes them only through the public SonarSource APIs
+  exposed by sonarlint-analysis-engine.
+
+------------------------------------------------------------------------------
+Build-time / direct-dependency Apache 2.0 components
+------------------------------------------------------------------------------
+
+  info.picocli:picocli                              (CLI framework)
+  com.fasterxml.jackson.core:jackson-*              (JSON serialization)
+  org.apache.maven.plugins:maven-* and the embedded
+  build-helper / central-publishing-maven-plugin    (build tooling)
+
+  All Apache License 2.0.
+
+------------------------------------------------------------------------------
+Runtime JRE auto-download (optional)
+------------------------------------------------------------------------------
+
+  When no Java 17+ runtime is found on the user's machine, the plugin's
+  bootstrap launcher fetches a JRE from the URL configured in
+  `plugin/skills/sonar-predictor/config.env`. The public default uses the
+  Adoptium Temurin API (https://api.adoptium.net), which serves Eclipse
+  Temurin OpenJDK builds under the GNU General Public License v2 with the
+  Classpath Exception (GPL-2.0 WITH Classpath-exception-2.0).
+
+  An air-gapped or corporate setup can replace this URL with a private JRE
+  mirror; the bootstrap does not require Adoptium specifically.
+
+================================================================================
+NOTES ON THE BUNDLED MAVEN CENTRAL ARTIFACT
+================================================================================
+
+The launcher currently downloads a single archive,
+`sonar-predictor-dist-<version>.zip`, from Maven Central. That archive (built
+and published by this project's release workflow) contains the SonarSource
+analyzer JARs alongside this project's own CLI and daemon jars, repackaged
+unmodified.
+
+A future release will change the launcher to fetch each analyzer JAR
+individually from Maven Central using its published coordinates, so that
+SonarSource's own Maven Central distribution is the sole redistribution
+channel and `sonar-predict-dist-*.zip` no longer carries third-party JARs.
+This eliminates any redistribution question about the SSALv1-licensed
+analyzers. The plugin's `config.env` already isolates the Maven repository
+URL, so this transition is transparent to corporate Maven proxy setups.
diff --git a/README.md b/README.md
@@ -45,17 +45,16 @@ It is **scan-only** — it reads your source and reports findings, and never mod
 
 ## Quick start
 
-Grab the self-contained bundle from the [latest release](https://github.com/RandomCodeSpace/sonar-predict/releases/latest) — it carries the CLI, the daemon and all 12 analyzers:
+`sonar-predictor` installs as a Claude Code / GitHub Copilot CLI plugin from this repo's built-in marketplace. The plugin is tiny (kilobytes); the analyzer bundle is fetched lazily from Maven Central on first scan and cached locally for every subsequent run.
 
-```sh
-curl -L -o sonar-predictor.zip \
-  https://github.com/RandomCodeSpace/sonar-predict/releases/download/v0.1.0/sonar-predict-skill-0.1.0.zip
-unzip sonar-predictor.zip -d sonar-predictor
-
-./sonar-predictor/bin/sonar check src/Main.java
+```
+/plugin marketplace add RandomCodeSpace/sonar-predict
+/plugin install sonar-predictor@sonar-predict
 ```
 
-The launcher auto-discovers a Java 17+ runtime and starts the daemon on first use — no configuration.
+The same two commands work on Claude Code and Copilot CLI — they share the `.claude-plugin` format. Two named scanner subagents come with the plugin: `sonar-scanner-claude` (model: haiku) and `sonar-scanner-copilot` (model: gpt-5-mini); selection is by agent name.
+
+Prefer the raw CLI? Grab the skill bundle directly from the [latest release](https://github.com/RandomCodeSpace/sonar-predict/releases/latest) and run `./bin/sonar` from the unpacked directory. The first invocation auto-discovers Java 17+ (or downloads one if none is found); every subsequent call is offline.
 
 ## Usage
 
@@ -77,18 +76,26 @@ sonar --format json check --diff
 sonar --coverage target/site/jacoco/jacoco.xml --coverage-min 80 analyze .
 ```
 
-## Use it as an AI-agent skill
+## Corporate / air-gapped setup
+
+The plugin's launcher reads a single configuration file at `plugin/skills/sonar-predictor/config.env`. Edit it (or set the same-named environment variable, which takes precedence) to point at a corporate Maven proxy, a private JRE mirror, or a vendored bundle version — no code changes.
 
-`sonar-predictor` is packaged as a [Claude Code](https://claude.com/claude-code) skill — an
-agent discovers it and runs it as a quality gate automatically. Install the bundle into your
-skills directory:
+| Key | What it controls |
+|-----|------------------|
+| `SONAR_MAVEN_REPO_URL` | Where the analyzer bundle is downloaded from. Default: Maven Central. |
+| `SONAR_BUNDLE_VERSION` | Bundle version pin. Bump in lockstep with each plugin release. |
+| `SONAR_MIN_JAVA_VERSION` | Minimum Java major version required. Default: `17`. |
+| `SONAR_JRE_URL_TEMPLATE` | JRE source for auto-download (when none is on the system). Tokens `{os}` `{arch}` `{version}` are substituted at runtime. Default: Adoptium Temurin API. |
+| `SONAR_JRE_VERSION` | JRE version to fetch. Default: `17`. |
+| `SONAR_DISABLE_JRE_AUTODOWNLOAD` | Set to `1` to refuse the JRE auto-download (corp-policy escape hatch). |
+
+For a fully pre-staged install — no network at all on the developer machine — extract a skill bundle by hand into a known location and point the launcher at it:
 
 ```sh
-unzip sonar-predict-skill-0.1.0.zip -d ~/.claude/skills/
+export SONAR_PREDICTOR_HOME=/opt/sonar-predictor
 ```
 
-The bundled `SKILL.md` tells the agent when to run it and how to read its output; the CLI's
-own `--help` is the single source of truth for commands.
+The forking workflow: clone this repo, edit `plugin/skills/sonar-predictor/config.env`, push to your fork, `/plugin marketplace add <your-org>/sonar-predict`. One file.
 
 ## How it works
 
@@ -134,6 +141,15 @@ smells, vulnerabilities and security hotspots — and imports coverage. It is a
 first-pass, **not** a replacement for release-time gates: the SonarQube server's deep
 cross-file taint analysis, Fortify, and dependency/CVE scanning remain their own tools.
 
-## License
+## License & third-party components
+
+This project (the CLI, daemon, protocol, dist module, plugin scaffolding) is licensed under the [Apache License 2.0](LICENSE).
+
+The SonarSource analyzers and engine that `sonar-predictor` invokes at runtime are **third-party components with their own licenses**, listed in [NOTICE](NOTICE). Headline points:
+
+- **`sonarlint-analysis-engine`** (the embedded analysis runtime, by SonarSource) — **LGPL v3**.
+- **SonarSource language analyzers** (`sonar-java`, `sonar-python`, `sonar-javascript`, `sonar-php`, `sonar-kotlin`, `sonar-go`, `sonar-ruby`, `sonar-scala`, `sonar-html`, `sonar-xml`) — **SONAR Source-Available License v1.0 (SSALv1)** since SonarSource's 2024 license change. Source-available, free for internal use, with restrictions on operating a competing "Service Offering".
+
+The plugin **does not redistribute** these JARs — its launcher fetches them from Maven Central on first invocation (the same channel SonarSource themselves publish to). Editing `SONAR_MAVEN_REPO_URL` to a corporate mirror that proxies Maven Central is equivalent. None of this project's source code is derived from SonarSource code.
 
-[Apache License 2.0](LICENSE).
+For a deeper inventory and the legal text of each license, see [NOTICE](NOTICE). If your environment's policy needs the analyzer JARs to come from somewhere other than Maven Central, the corporate / air-gapped setup above is your knob.
diff --git a/dist/README.md b/dist/README.md
@@ -1,71 +1,61 @@
 # sonar-predictor :: dist
 
-The distribution module. It builds **sonar-predictor** as a self-contained
-Claude Code agent skill — a directory an AI agent can use with zero setup.
+The distribution module. It assembles the **skill bundle** that `sonar-predictor`'s plugin launcher downloads at first run.
 
-## Build
-
-From the repository root:
+## What this module builds
 
 ```sh
 mvn package
 ```
 
-This produces, under `dist/target/`:
+produces, under `dist/target/`:
 
 - `skill/sonar-predictor/` — the exploded skill bundle:
-  - `SKILL.md` — the agent-facing skill definition (the only file loaded into context)
+  - `SKILL.md` — the agent-facing skill definition
   - `bin/sonar`, `bin/sonar.bat` — launchers that auto-discover a Java 17+ runtime
-  - `lib/` — the CLI and daemon fat jars
+  - `lib/` — the CLI and daemon shaded fat jars
   - `plugins/` — the 10 SonarSource analyzer plugins
-- `sonar-predict-skill-<version>.zip` — the same tree zipped, for non-skill use
-  (manual install, or transfer to an air-gapped host)
+- `sonar-predict-skill-<version>.zip` — the same tree zipped, attached to the GitHub Release and **published to Maven Central as `io.github.randomcodespace.sonarpredict:sonar-predictor-dist:<version>:zip`**. The plugin's bootstrap launcher pulls this artifact (from Maven Central, or a corporate proxy of it) on first invocation.
 
-The analyzer plugins are fetched through Maven, so any mirror, Nexus, or
-corporate proxy configured in your `settings.xml` is honored — there are no
-hardcoded download URLs.
+The analyzer plugins are resolved through Maven, so any mirror, Nexus, or corporate proxy configured in your `settings.xml` is honored — there are no hardcoded download URLs in the build.
 
-## Install as a Claude Code skill
+## How users install `sonar-predictor`
 
-```sh
-cp -r dist/target/skill/sonar-predictor ~/.claude/skills/
+End users do not interact with this module directly. They install the plugin from the in-repo `/plugin/` directory through their AI tool's marketplace:
+
+```
+/plugin marketplace add RandomCodeSpace/sonar-predict
+/plugin install sonar-predictor@sonar-predict
 ```
 
-The skill is then available to agents in any project.
+The plugin's launcher (`/plugin/skills/sonar-predictor/bin/sonar`) downloads the bundle this module builds from Maven Central, verifies its SHA-1, caches it under `~/.cache/sonar-predictor/<version>/`, and execs the cached `bin/sonar` on every subsequent call.
 
-## Prerequisites
+For raw / non-plugin use (manual or air-gapped install), the same skill bundle zip is attached to each GitHub Release.
 
-The skill runs on a system Java; nothing is downloaded at runtime.
+## Prerequisites at runtime
 
 **Required:**
-- **Java 17+** (JDK or JRE) — the CLI and daemon are JVM processes. `bin/sonar` auto-discovers it (`JAVA_HOME` → `PATH` → common install locations); one must exist somewhere on the machine.
+- **Java 17+** (JDK or JRE) — the CLI and daemon are JVM processes. `bin/sonar` auto-discovers it (`JAVA_HOME` → `PATH` → common install locations); the plugin's bootstrap also auto-downloads one from `SONAR_JRE_URL_TEMPLATE` (defaulting to Adoptium Temurin) if none is found.
 - **Linux or macOS** — the daemon uses Unix domain sockets. Windows is not yet supported (the TCP-socket fallback is a TODO).
 - A writable temp directory and ~1 GB free RAM (the daemon embeds the analysis engine; idle ~150–350 MB, up to ~1 GB during JS/TS analysis).
 - ~165 MB disk for the bundle.
 
 **For specific features:**
-- **`git`** on `PATH` — required for `sonar check --diff` (the primary agent workflow). `sonar check <files>` and `sonar analyze <dir>` work without it.
-- **Node.js 18.17+** on `PATH` — required for JavaScript/TypeScript/CSS analysis. Without it those 3 languages are skipped (the other 9 still analyze).
+- **`git`** on `PATH` — required for `sonar check --diff` (the primary agent workflow).
+- **Node.js 18.17+** on `PATH` — required for JavaScript/TypeScript/CSS analysis. Without it those 3 languages are skipped.
 
-**Not required:** no network at runtime (fully offline after install), no per-language SDK or compiler, no Maven (build-time only).
-
-If no Java 17+ is found, the `bin/sonar` launcher exits with a clear message.
+**Not required after first invocation:** no network, no per-language SDK or compiler, no Maven.
 
 ## Releasing
 
-A release is cut by pushing a version tag. The
-`.github/workflows/publish.yml` GitHub Actions pipeline then:
+A release is cut by pushing a version tag. The `.github/workflows/publish.yml` GitHub Actions pipeline then:
 
-1. derives the release version from the tag (`v0.1.0` → `0.1.0`) and strips
-   `-SNAPSHOT` — Maven Central rejects snapshot versions,
-2. builds, tests, GPG-signs and deploys the library modules
-   `protocol`, `daemon` and `cli` to Maven Central via the Sonatype
-   Central Portal (this `dist` module sets `maven.deploy.skip=true`, so it
-   is built but never staged to Central),
-3. creates a GitHub Release carrying two bundles:
-   - **`sonar-predict-<version>-src.zip`** — the whole repository as a
-     `git archive` of `HEAD`,
-   - **`sonar-predict-skill-<version>.zip`** — the assembled skill bundle.
+1. derives the release version from the tag (`v0.1.0` → `0.1.0`) and strips `-SNAPSHOT`,
+2. builds, tests, GPG-signs and deploys the library modules `protocol`, `daemon` and `cli` to Maven Central via the Sonatype Central Portal,
+3. publishes this `dist` module's skill bundle zip to Maven Central as `sonar-predictor-dist:<version>:zip` (this is the artifact the plugin's bootstrap downloads),
+4. creates a GitHub Release carrying two bundles:
+   - `sonar-predict-<version>-src.zip` — the whole repository as a `git archive` of `HEAD`,
+   - `sonar-predict-skill-<version>.zip` — the assembled skill bundle.
 
 To cut release `X.Y.Z`:
 
@@ -74,13 +64,11 @@ git tag vX.Y.Z
 git push origin vX.Y.Z
 ```
 
-The workflow can also be run manually from the **Actions** tab
-(`workflow_dispatch`), supplying the version explicitly.
+When the release is cut, bump the plugin launcher's pinned bundle version in `plugin/skills/sonar-predictor/config.env` (`SONAR_BUNDLE_VERSION`) in the same commit, so a freshly installed plugin downloads the bundle that matches it.
 
-### Required repository secrets
+The workflow can also be run manually from the **Actions** tab (`workflow_dispatch`), supplying the version explicitly.
 
-The pipeline needs these secrets on the `RandomCodeSpace/sonar-predict`
-repository (Settings → Secrets and variables → Actions):
+### Required repository secrets
 
 | Secret | Purpose |
 |--------|---------|
@@ -89,6 +77,4 @@ repository (Settings → Secrets and variables → Actions):
 | `MAVEN_GPG_PRIVATE_KEY` | ASCII-armored GPG private key used to sign artifacts |
 | `MAVEN_GPG_PASSPHRASE` | Passphrase for that GPG key (omit if the key has none) |
 
-`GITHUB_TOKEN` is provided automatically and needs no setup. The
-`io.github.randomcodespace` namespace must also be registered and verified
-on the Sonatype Central Portal.
+`GITHUB_TOKEN` is provided automatically. The `io.github.randomcodespace` namespace must be registered and verified on the Sonatype Central Portal.