docs: clarify auto-discovery behavior and fix user guide accuracy (#2036)

* docs: clarify auto-discovery, remove stale guidance, fix examples

- Explain where automatic discovery works and where it does not
- Document single-quote literal matching for workflow regexps input
- Position manual PRs as a fallback, not a preferred workflow
- Remove outdated frontend plugin / Scalprum configuration section
- Rewrite integrity-check and compatibility-check explanations
- Replace fixed monthly/quarterly cadence with signal-based updates
- Clarify plugin removal must delete the entire workspace folder
- Fix Backstage Compatibility wiki link
- Document commit SHA usage for multi-plugin workspaces in source.json
- Ground major-version update guidance in practical workflow
- Fix patch example rationales (Yarn Berry globs, dynamic plugin imports)
- Update plugins-regexps references to workspace-discovery-include/exclude

Jira: RHIDP-12661
Made-with: Cursor

* docs: remove scalprum-config.json remnant and fix cadence label

- Remove last scalprum-config.json reference from overlay example in 02-export-tools.md
- Update Responsibilities Overview table to say "When compatibility signals appear" instead of "Monthly/Quarterly"

Made-with: Cursor

* docs: include workspace e2e validation in owner testing steps

Expand plugin owner test guidance to include workspace e2e validation (when available) and link to the getting-started testing workflow section.

Made-with: Cursor

Author: polasudo

user-guide/01-getting-started.md

@@ -32,7 +32,8 @@ The `rhdh-plugin-export-overlays` repository serves as a **metadata and automati
 ```
 rhdh-plugin-export-overlays/
 ├── versions.json              # Target versions (Backstage, Node, CLI)
-├── plugins-regexps            # Auto-discovery scope patterns
+├── workspace-discovery-include # Auto-discovery scope patterns
+├── workspace-discovery-exclude # Workspaces excluded from auto-discovery
 ├── workspaces/                # One folder per source workspace
 │   └── [workspace-name]/
 │       ├── source.json        # Source repository reference
@@ -43,9 +44,7 @@ rhdh-plugin-export-overlays/
 │       │   └── *.patch
 │       ├── plugins/           # Plugin-specific overrides (optional)
 │       │   └── [plugin-name]/
-│       │       ├── overlay/
-│       │       ├── app-config.dynamic.yaml
-│       │       └── scalprum-config.json
+│       │       └── overlay/
 │       └── smoke-tests/       # Smoke test configuration (optional)
 │           ├── test.env
 │           └── app-config.test.yaml
@@ -144,20 +143,60 @@ spec:
    - [`@roadiehq/`](https://github.com/RoadieHQ/roadie-backstage-plugins) – Roadie Backstage Plugins
 2. Plugin is compatible with the target Backstage version
 
+### How Automatic Discovery Works
+
+The overlay repository runs an automated workflow (`update-plugins-repo-refs.yaml`) twice daily. It scans npm registries for new releases of packages matching the scope patterns defined in the `workspace-discovery-include` file:
+
+- `@backstage-community/`
+- `@red-hat-developer-hub/`
+- `@roadiehq/`
+
+When a new release is found, the workflow creates or updates a PR with the necessary `source.json`, `plugins-list.yaml`, and `metadata/*.yaml` changes.
+
+#### Where automatic discovery works
+
+Automatic discovery works for plugins published under the scopes listed above. If a new package version is published to npm under one of those scopes, the workflow will detect it and propose an update.
+
+#### Where automatic discovery does not work
+
+- **Plugins outside the supported scopes** (e.g., `@pagerduty/`, `@dynatrace/`, or any other third-party namespace) are not scanned. These must be added manually.
+- **Workspaces listed in `workspace-discovery-exclude`** are skipped entirely by the scheduled run.
+- **Unpublished or pre-release versions** that are not yet on npm will not be discovered.
+- **New workspaces** are only proposed when the scheduled workflow has the `allow-workspace-addition` flag enabled; otherwise only existing workspaces receive updates.
+
 ### Option 1: Automatic Discovery (Preferred)
 
-Plugins under supported scopes are auto-discovered daily. If your plugin was recently published, wait for the automation to create a PR.
+If your plugin is published under a supported scope, wait for the daily automation to create a PR. No action is needed on your part.
 
 ### Option 2: Trigger Workflow Manually
 
+You can trigger the discovery workflow on demand. The `regexps` input accepts either a regular expression or a literal package name.
+
+**Wrapping a value in single quotes** tells the workflow to treat it as an exact (literal) package name rather than a regular expression. This is the recommended approach when you want to target a specific plugin package directly, because it avoids accidentally matching other packages with similar names.
+
 ```bash
-# Requires write access to the repository
+# Target a single package by exact name (recommended — note the single quotes)
 gh workflow run update-plugins-repo-refs.yaml \
-  -f regexps="@backstage-community/plugin-your-plugin" \
+  -f regexps="'@backstage-community/plugin-your-plugin'" \
+  -f single-branch="main"
+
+# Target multiple packages matching a regex pattern (no quotes)
+gh workflow run update-plugins-repo-refs.yaml \
+  -f regexps="@backstage-community/plugin-catalog-backend-module-.*" \
+  -f single-branch="main"
+```
+
+You can also scope the run to a specific workspace:
+
+```bash
+gh workflow run update-plugins-repo-refs.yaml \
+  -f workspace-path="workspaces/your-workspace" \
   -f single-branch="main"
 ```
 
-### Option 3: Manual PR
+### Option 3: Manual PR (Fallback)
+
+Manual PRs should be reserved for situations where automatic discovery does not apply — for example, plugins outside the supported scopes or workspaces that require nonstandard setup. Prefer Options 1 or 2 whenever possible.
 
 1. **Create workspace folder:**
 

user-guide/02-export-tools.md

@@ -134,53 +134,6 @@ When working with Pull Requests, use these comment commands:
 
 ---
 
-## Frontend Plugin Configuration
-
-Frontend plugins often require additional configuration files.
-
-### app-config.dynamic.yaml
-
-Defines route bindings, dynamic routes, and mount points:
-
-```yaml
-backstage.plugin-techdocs:
-  routeBindings:
-    targets:
-      - importName: techdocsPlugin
-    bindings:
-      - bindTarget: catalogPlugin.externalRoutes
-        bindMap:
-          viewTechDoc: techdocsPlugin.routes.docRoot
-  dynamicRoutes:
-    - path: /docs
-      importName: TechDocsIndexPage
-      menuItem:
-        icon: docs
-        text: Docs
-  mountPoints:
-    - mountPoint: entity.page.docs/cards
-      importName: EntityTechdocsContent
-```
-
-**Location:** `workspaces/[workspace]/plugins/[plugin-name]/app-config.dynamic.yaml`
-
-### scalprum-config.json
-
-Defines the Scalprum module configuration:
-
-```json
-{
-  "name": "backstage.plugin-api-docs-module-protoc-gen-doc",
-  "exposedModules": {
-    "PluginRoot": "./src/api.ts"
-  }
-}
-```
-
-**Location:** `workspaces/[workspace]/plugins/[plugin-name]/scalprum-config.json`
-
----
-
 ## Overlays vs Patches
 
 | Feature | Overlay | Patch |
@@ -200,11 +153,10 @@ Defines the Scalprum module configuration:
 
 ```
 workspaces/backstage/plugins/api-docs-module-protoc-gen-doc/
-├── overlay/
-│   ├── package.json
-│   └── src/
-│       └── api.ts
-└── scalprum-config.json
+└── overlay/
+    ├── package.json
+    └── src/
+        └── api.ts
 ```
 
 ### When to Use Patches
@@ -234,14 +186,14 @@ See [06 - Patch Management](./06-patch-management.md) for details.
 
 ### Integrity Check Failures
 
-**Symptom:** `Integrity check failed for package X`
+**Symptom:** Workflow logs show an integrity mismatch for a package.
 
-**Cause:** The `package.json` in the source repo doesn't match the overlay's expectations.
+**Cause:** The export process verifies that the `package.json` fields in the checked-out source match the metadata declared in the overlay (e.g., package name, version). A mismatch usually means `source.json:repo-ref` points to a different version than what `metadata/*.yaml:spec.version` declares.
 
 **Solution:**
-1. Verify `source.json` points to the correct `repo-ref`
-2. Check if the source `package.json` was modified
-3. If intentional, consider using `--no-integrity-check` (document why)
+1. Verify `source.json:repo-ref` points to the correct tag or commit
+2. Confirm that `spec.version` and `spec.packageName` in your metadata files match the source `package.json` at that ref
+3. If the mismatch is intentional (e.g., a patch changes the version), document the reason in the PR
 
 ### Missing Dependencies
 

user-guide/03-plugin-owner-responsibilities.md

@@ -19,7 +19,7 @@ You are a plugin owner if you:
 | Area | Frequency | Criticality |
 |------|-----------|-------------|
 | Metadata synchronization | Every release | 🔴 High |
-| Backstage version updates | Monthly/Quarterly | 🔴 High |
+| Backstage version updates | When compatibility signals appear | 🔴 High |
 | Patch maintenance | As needed | 🟡 Medium |
 | Test validation | Every PR | 🔴 High |
 | Deprecation communication | As needed | 🟡 Medium |
@@ -52,24 +52,26 @@ See [04 - Metadata Synchronization](./04-metadata-synchronization.md) for detail
 
 ---
 
-### 2. Update Backstage Versions Regularly
+### 2. Keep Backstage Versions Compatible
 
-The target platform tracks Backstage releases. Your plugin must remain compatible.
+The target platform tracks Backstage releases. Your plugin must remain compatible with the version declared in `versions.json`.
 
-**Minimum cadence:**
+Rather than following a fixed calendar cadence, watch for concrete signals that an update is needed:
 
-| Update Type | Frequency | Action Required |
-|-------------|-----------|-----------------|
-| Target version | Monthly | Verify compatibility with new Backstage release |
-| Minimum version | Quarterly | Update `supportedVersions` in metadata |
-| Major version | As released | Full compatibility testing |
+- The [Backstage Compatibility Report](https://github.com/redhat-developer/rhdh-plugin-export-overlays/wiki/Backstage-Compatibility-Report) shows your workspace as incompatible
+- A new platform release branch is being created and your plugin blocks it
+- Automated discovery PRs fail the compatibility check for your workspace
+- Upstream has released a version built against the current target Backstage version
 
-**Process:**
+**When any of these signals appear:**
 
 1. Check the target Backstage version in `versions.json`
-2. Verify your plugin works with that version
-3. Update `repo-backstage-version` in `source.json`
+2. Find a plugin release compatible with that version
+3. Update `repo-ref` and `repo-backstage-version` in `source.json`
 4. Update `supportedVersions` in metadata files
+5. Test with `/publish` and `/smoketest`, and run workspace E2E validation when available for that workspace
+
+See [01 - Getting Started: Testing Your Plugin](./01-getting-started.md#testing-your-plugin) for test workflow details.
 
 See [05 - Version Updates](./05-version-updates.md) for detailed procedures.
 
@@ -119,22 +121,23 @@ Notify downstream users when:
 
 ---
 
-## Monthly Maintenance Checklist
+## Maintenance Checklist
 
-Use this checklist each month:
+Use this checklist when updating your plugin (triggered by a compatibility signal, a new upstream release, or a platform version bump):
 
 ```markdown
-## Monthly Plugin Maintenance - [Plugin Name] - [Month/Year]
+## Plugin Maintenance - [Plugin Name] - [Date]
 
 ### Version Check
-- [ ] Verified plugin compatibility with current target Backstage version
-- [ ] Updated `source.json:repo-backstage-version` if needed
-- [ ] Updated `metadata/*.yaml:spec.backstage.supportedVersions` if needed
+- [ ] Checked target Backstage version in versions.json
+- [ ] Found a plugin release compatible with the target version
+- [ ] Updated `source.json:repo-ref` and `repo-backstage-version`
+- [ ] Updated `metadata/*.yaml:spec.version` and `spec.backstage.supportedVersions`
 
 ### Metadata Check
-- [ ] Verified `spec.version` matches source `package.json:version`
 - [ ] Verified `spec.packageName` matches source `package.json:name`
 - [ ] Reviewed and updated `appConfigExamples` if configuration changed
+- [ ] Updated metadata links (source, issues, docs) if needed
 
 ### Patch Check
 - [ ] Verified all patches apply cleanly to current source
@@ -150,37 +153,6 @@ Use this checklist each month:
 
 ---
 
-## Quarterly Maintenance Checklist
-
-Use this checklist each quarter:
-
-```markdown
-## Quarterly Plugin Maintenance - [Plugin Name] - [Quarter/Year]
-
-### Compatibility Review
-- [ ] Reviewed Backstage changelog for breaking changes
-- [ ] Tested plugin with minimum supported platform version
-- [ ] Tested plugin with current platform version
-- [ ] Updated `supportedVersions` range
-
-### Dependency Audit
-- [ ] Reviewed embedded packages (--embed-package)
-- [ ] Checked for security advisories in dependencies
-- [ ] Updated suppressed native packages if needed
-
-### Documentation Review
-- [ ] Updated metadata links (source, issues, docs)
-- [ ] Reviewed and updated description/title
-- [ ] Checked `appConfigExamples` accuracy
-
-### Cleanup
-- [ ] Removed obsolete patches
-- [ ] Removed obsolete overlay files
-- [ ] Archived any deprecated plugin variants
-```
-
----
-
 ## Handling Plugin Deprecation
 
 When deprecating a plugin:
@@ -193,24 +165,21 @@ spec:
   # Add deprecation notice
 ```
 
-### 2. Comment Out in plugins-list.yaml
-
-```yaml
-# plugins/my-deprecated-plugin: ==> Deprecated: Use new-plugin instead
-```
-
-### 3. Communicate to Users
+### 2. Communicate to Users
 
 - Open an issue documenting the deprecation
 - Provide migration path to replacement plugin
 - Set a timeline for removal (typically 2 release cycles)
 
-### 4. Remove After Grace Period
+### 3. Remove After Grace Period
+
+When the grace period ends, remove the workspace entirely:
 
-- Delete metadata files
-- Remove from `plugins-list.yaml`
+- Delete the workspace folder (including `source.json`, `plugins-list.yaml`, metadata files, and any patches)
 - Document removal in release notes
 
+> **Important:** Simply commenting out entries in `plugins-list.yaml` or removing metadata files while keeping the workspace folder is not sufficient. If the workspace folder and `source.json` remain, automatic discovery will detect the plugin again and propose re-adding it. To permanently remove a plugin, delete the entire workspace directory.
+
 ---
 
 ## Getting Help
@@ -219,7 +188,7 @@ spec:
 |-------|-------------|
 | Build failures | Check workflow logs, open issue |
 | Patch conflicts | See [06 - Patch Management](./06-patch-management.md) |
-| Compatibility questions | Check [Backstage Compatibility wiki](https://github.com/redhat-developer/rhdh-plugin-export-overlays/wiki) |
+| Compatibility questions | Check the [Backstage Compatibility Report](https://github.com/redhat-developer/rhdh-plugin-export-overlays/wiki/Backstage-Compatibility-Report) |
 | Process questions | Open a discussion or issue |
 
 ---