diff --git a/README.md b/README.md
index fe3c96bdc..79dbfade8 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,67 @@
-Plexus Parent POM
-=================
+# Plexus Parent POM
-[](https://search.maven.org/artifact/org.codehaus.plexus/plexus)
+[](https://central.sonatype.com/artifact/org.codehaus.plexus/plexus)
+[](https://github.com/codehaus-plexus/plexus-pom/actions)
+[](https://www.apache.org/licenses/LICENSE-2.0)
-The current master is now at https://github.com/codehaus-plexus/plexus-pom
+The parent POM inherited by every project in the [Codehaus Plexus](https://github.com/codehaus-plexus)
+organisation. It pins plugin versions, the Java and Maven baselines, formatting, reporting and the release
+setup, so the individual projects carry almost no build configuration of their own.
+
+## Status
+
+Maintained. Released whenever plugin or dependency updates accumulate, roughly every couple of months.
+
+This is infrastructure for the Plexus projects rather than a general-purpose parent — it assumes Sonatype
+Central Portal publishing, GitHub Pages site hosting and the organisation's shared CI workflow. You are
+welcome to use it, but it is not designed to be neutral.
+
+## Using it
+
+```xml
+
+ org.codehaus.plexus
+ plexus
+ 25
+
+```
+
+Check the badge above for the current version.
+
+Projects must override `distributionManagement/site` to point at their own `gh-pages` branch; everything
+else is inherited.
+
+## What it configures
+
+- **Baselines** — Java 8 (`javaVersion`), Maven 3.6.3 minimum, UTF-8 sources
+- **Enforcer** — Maven and JDK minimums, plus a rule rejecting dependencies whose bytecode is newer than
+ your compiler target
+- **Formatting** — Spotless with palantir-java-format, sorted POMs, flexmark for Markdown. Applies locally,
+ checks in CI
+- **Reproducible builds** — `project.build.outputTimestamp` is set and the results are verified by
+ [Reproducible Central](https://github.com/jvm-repo-rebuild/reproducible-central)
+- **Reporting** — the `reporting` profile adds Javadoc, JXR, surefire, PMD/CPD and taglist
+- **Releasing** — the `plexus-release` profile adds GPG signing, sources and a source-release assembly, and
+ enables [Njord](https://maveniverse.eu/docs/njord/) to publish to Central
+
+The [project site](https://codehaus-plexus.github.io/plexus-pom/) explains each of these, and lists every
+[managed plugin version](https://codehaus-plexus.github.io/plexus-pom/plugin-management.html).
+
+## Requirements
+
+Java 8 or later to build a consuming project; Maven 3.6.3 or later (3.9.0 when releasing).
+
+## Documentation
+
+- [Project site](https://codehaus-plexus.github.io/plexus-pom/)
+- [Release notes](https://github.com/codehaus-plexus/plexus-pom/releases)
+- [Releasing and site publishing](https://github.com/codehaus-plexus/.github/blob/master/RELEASING.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/codehaus-plexus/.github/blob/master/CONTRIBUTING.md). Changes here
+affect every project in the organisation, so a version bump that looks routine can break a downstream build
+— please say in the PR description what you have checked.
+
+Please report security vulnerabilities privately — see
+[SECURITY.md](https://github.com/codehaus-plexus/.github/blob/master/SECURITY.md), not a public issue.
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index d40ba7c63..0e339ed1c 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -1,10 +1,113 @@
# Plexus Parent POM
-Plexus Parent POM defines common [plugins](./plugin-management.html), reporting and release configuration.
+The parent POM inherited by every project in the [Codehaus Plexus](https://codehaus-plexus.github.io/)
+organisation. It fixes plugin versions, the Java and Maven baselines, code formatting, reporting and the
+release setup, so the individual projects carry almost no build configuration of their own.
-## Preparing the environment for publishing vie the Central Portal
+```xml
+
+ org.codehaus.plexus
+ plexus
+
+
+```
+
+## What you get
+
+### Baselines
+
+| Setting | Value |
+|---|---|
+| Java (`javaVersion`) | 8 — sets `maven.compiler.source`, `target` and `release` |
+| Minimum Maven to build | 3.6.3 (3.9.0 when releasing) |
+| Source encoding | UTF-8 |
+| Annotation processing | off (`maven.compiler.proc=none`) — enable it deliberately if you need it |
+
+Override `javaVersion` in your own POM to raise the baseline; `plexus-sec-dispatcher` and `plexus-xml` 4.x
+set it to 17.
+
+### Enforced at build time
+
+`maven-enforcer-plugin` fails the build on a Maven version below the minimum, a JDK below the baseline,
+and — via `extra-enforcer-rules` — on any **dependency containing bytecode newer than your compiler
+target**. That last rule is the one that usually catches people: it means a dependency compiled for a
+later JDK than you target is an error, not a runtime surprise.
+
+### Formatting
+
+Spotless, applied at `process-sources`:
-Release manager should include the following sections in your personal `settings.xml`:
+- Java — [palantir-java-format](https://github.com/palantir/palantir-java-format), unused imports removed,
+ import order `javax, java, all else, static`
+- POMs — sorted with `sortPom`
+- Markdown — flexmark
+
+The action depends on where you are. Locally (`!env.CI`) the `format` profile sets `spotless.action=apply`,
+so a build **rewrites your sources**. In CI (`env.CI` set) the `format-check` profile sets it to `check`,
+so the build fails instead. If CI fails on formatting, run `mvn spotless:apply` and commit.
+
+> Note that Spotless formats `**/*.md`. Parent 26 onward excludes `**/src/site/markdown/**`, because
+> flexmark rewrites the fence closing a YAML front matter block and silently destroys a page's title and
+> author. **Parent 25 does not have that exclusion** — if you are on 25 and keep site sources in Markdown,
+> add the exclusion to your own POM.
+
+### Reproducible builds
+
+`project.build.outputTimestamp` is set, and every project here is verified by
+[Reproducible Central](https://github.com/jvm-repo-rebuild/reproducible-central). Keep it set, and bump it
+only as part of a release.
+
+### Reporting
+
+Project info reports are on by default. The `reporting` profile adds the rest — Javadoc, JXR, surefire,
+PMD/CPD and taglist:
+
+```
+mvn -Preporting site
+```
+
+Building a site **without** `-Preporting` gives you a site with no API documentation, so always pass it
+when publishing.
+
+### Publishing
+
+Snapshots and releases go to the Sonatype Central Portal. `distributionManagement` is inherited;
+`site` **must be overridden** in each project, and points at that project's own `gh-pages` branch:
+
+```xml
+
+
+ github:gh-pages
+ ${project.scm.developerConnection}
+
+
+```
+
+`maven-site-plugin` runs with `skipDeploy`, so sites are published by `maven-scm-publish-plugin` rather
+than `site:deploy`.
+
+## Releasing
+
+Full procedure, including site publishing, is in
+[RELEASING.md](https://github.com/codehaus-plexus/.github/blob/master/RELEASING.md). The short version:
+
+```
+mvn release:prepare
+mvn release:perform
+```
+
+`maven-release-plugin` is configured with `deploy` and
+`plexus-release`, so `release:perform` activates the `plexus-release`
+profile. That profile turns on GPG signing, attaches sources and a source-release assembly, and enables
+[Njord](https://maveniverse.eu/docs/njord/), which is registered as a build extension.
+
+Njord is configured with `autoPublish=true` and `publishingType=automatic`, so the deployment is published
+to Central **without a manual step in the Portal UI**. `njord.enabled` is `false` outside the release
+profile, so ordinary builds are unaffected.
+
+### Release manager setup
+
+A Central Portal token in your personal `settings.xml`:
```xml
sonatype-central-portal
- jqhacker
- SeCrEt
+
+
```
-Tokens can be obtained from https://central.sonatype.com/account
+Tokens come from . It is a generated token pair, not your account
+password.
+
+You also need a published GPG key, since releases are signed.
+
+## Reference
+- [Plugin versions managed here](./plugin-management.html)
+- [Dependency versions managed here](./dependency-management.html)
+- [Contributing](https://github.com/codehaus-plexus/.github/blob/master/CONTRIBUTING.md)
diff --git a/src/site/site.xml b/src/site/site.xml
index 59edeea41..4123fe09b 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -51,6 +51,7 @@