Make plugin documentation release-ready

Author: Tsvetan Stoychev

CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to Basicrum
+
+Thank you for improving Basicrum. Contributions should preserve the plugin's privacy-first defaults, WordPress compatibility boundaries, and installable ZIP quality.
+
+## Before starting
+
+- Search existing issues and pull requests before opening a duplicate.
+- Use a public issue for ordinary defects and proposals.
+- Follow [SECURITY.md](SECURITY.md) for suspected vulnerabilities.
+- Keep changes focused and explain any administrator-visible behavior change.
+
+## Local setup
+
+Docker, Docker Compose, and Make are required.
+
+```bash
+cp .env.example .env
+make up
+```
+
+The development site is available at <http://localhost:9080/> with `admin` / `basicrum-dev-password`. Run `make help` to list the available checks and test environments.
+
+## Source and conventions
+
+The installable plugin is [`plugins/basicrum/`](plugins/basicrum/). Repository root files provide development, browser-test, Docker, CI, and release tooling.
+
+Follow the permanent conventions in [AGENTS.md](AGENTS.md), including WordPress Coding Standards, PHP 7.4 compatibility, ASCII hyphens, synchronized version metadata, privacy-safe consent behavior, and immutable GitHub Actions pins.
+
+When changing user-facing text, regenerate WordPress translation catalogs. When changing settings, keep defaults, rendering, validation, runtime behavior, tests, and documentation synchronized.
+
+## Verification
+
+Run the checks proportionate to the change. At minimum, PHP changes normally require:
+
+```bash
+make lint-php
+make lint
+make analyse
+make unit
+make conventions
+```
+
+Run `make js-test` for browser or consent behavior. Run `make integration-setup` before the first `make integration` invocation for WordPress integration changes, and use `make woocommerce-e2e` for WooCommerce page types. Changes that affect packaged files or dependencies must also pass:
+
+```bash
+make package
+make package-verify
+make package-smoke
+```
+
+The complete release gate is listed in [AGENTS.md](AGENTS.md).
+
+## Pull requests
+
+- Describe the problem, the chosen behavior, and the verification performed.
+- Add or update tests for behavior changes and regressions.
+- Do not include generated release ZIPs, local configuration, dependencies, or ignored reference material.
+- Do not advance release or compatibility metadata without the corresponding release checks.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tsvetan Stoychev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported versions
+
+Before the first public release, security fixes are made on the `main` branch. After publication, only the latest released Basicrum plugin version will receive security fixes unless a release notice states otherwise.
+
+## Reporting a vulnerability
+
+Do not report a suspected vulnerability in a public GitHub issue. Contact the maintainer privately through the [Basicrum contact form](https://www.basicrum.com/contact/) and identify the report as a security issue.
+
+Include, where possible:
+
+- the affected plugin version and WordPress/PHP versions;
+- the vulnerable component and required configuration;
+- reproducible steps or a minimal proof of concept;
+- the expected and observed security impact; and
+- any suggested remediation or disclosure constraints.
+
+Avoid accessing data that does not belong to you, degrading a live service, or testing against production systems without permission. Please allow time for the report to be reproduced and addressed before public disclosure.
+
+General support questions and non-sensitive defects may use the repository's [public issue tracker](https://github.com/basicrum/wp-plugin/issues).

SECURITY.md

@@ -0,0 +1,11 @@
+# Acknowledgments
+
+## WooCommerce page-type ideas
+
+The Basicrum WooCommerce `p_type` taxonomy and its specificity order were informed by these public references:
+
+- [WooCommerce Conditional Tags](https://developer.woocommerce.com/docs/theming/theme-development/conditional-tags)
+- [WooCommerce core conditional functions](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/wc-conditional-functions.php)
+- [GTM4WP WooCommerce integration](https://github.com/duracelltomi/gtm4wp/blob/master/integration/woocommerce.php)
+
+These projects inspired the page-type ideas only. Basicrum has its own implementation and did not copy source code from them.

docs/acknowledgments.md

@@ -8,13 +8,14 @@ tab under **Consent Tool Connection** in the revealed **Manual Connection
 Setup** panel.
 
 Automatic handling gives WP Consent API priority. Without it, Basicrum selects
-a direct Borlabs Cookie 3.2+ or connected modern CookieYes 3.x adapter only when
-exactly one is detected. No provider or multiple direct providers leave the
-consent loader blocked. Do not also paste an adapter manually while automatic
-handling is active. The automatic status panel shows the selection evidence and
-next action. Its copyable diagnostics omit the Beacon URL and Brum Site ID.
-Detection does not prove that the consent popup publishes the required
-decision, so test both allow and deny in a private window.
+a direct Borlabs Cookie or CookieYes adapter only when exactly one corresponding
+plugin marker is detected. No provider or multiple direct providers leave the
+consent loader blocked. The selected adapter still fails closed until its
+required browser API reports a decision. Do not also paste an adapter manually
+while automatic handling is active. The automatic status panel shows the
+selection evidence and next action. Its copyable diagnostics omit the Beacon URL
+and Brum Site ID. Detection does not prove that the consent popup publishes the
+required decision, so test both allow and deny in a private window.
 
 In manual mode, load the Basicrum consent loader before the selected adapter.
 Load one adapter as unblocked site code on every frontend page. The external

examples/integrations/README.md

@@ -1,117 +1,19 @@
-=== Plugin Name ===
-Plugin Name:       Basicrum WordPress Plugin
-Plugin URI:        https://www.basicrum.com/
-Description:       Open source Real User Monitoring for WordPress.
-Version:           0.0.8
-Author:            Tsvetan Stoychev
-Author URI:        https://www.basicrum.com/contact/
-License:           MIT
-License URI:       https://opensource.org/licenses/MIT
-Text Domain:       basicrum
-Domain Path:       /languages
- 
+# Basicrum Plugin Source
 
-Here is a short description of the plugin.  This should be no more than 150 characters.  No markup here.
+This directory contains the installable Basicrum WordPress plugin. Runtime PHP, JavaScript, CSS, images, translations, and production Composer dependencies in the release ZIP all come from this boundary.
 
-== Description ==
+## Entry points
 
-This is the long description.  No limit, and you can use Markdown (as well as in the following sections).
+- `basicrum.php` contains the WordPress plugin header and bootstrap.
+- `src/Plugin.php` registers plugin services.
+- `src/Assets.php` controls frontend monitoring injection.
+- `src/Admin/Settings/` contains settings rendering and validation.
+- `readme.txt` is the canonical WordPress.org user documentation and changelog.
+- `THIRD-PARTY-NOTICES.md` records bundled software with separate licenses.
+- `.distignore` defines development files excluded from releases.
 
-For backwards compatibility, if this section is missing, the full length of the short description will be used, and
-Markdown parsed.
+## Development
 
-A few notes about the sections above:
+Run development and test commands from the repository root. The root [README](../../README.md) contains the quick start, and [AGENTS.md](../../AGENTS.md) lists the complete required checks and repository conventions.
 
-*   "Contributors" is a comma separated list of wp.org/wp-plugins.org usernames
-*   "Tags" is a comma separated list of tags that apply to the plugin
-*   "Requires at least" is the lowest version that the plugin will work on
-*   "Tested up to" is the highest version that you've *successfully used to test the plugin*. Note that it might work on
-higher versions... this is just the highest one you've verified.
-*   Stable tag should indicate the Subversion "tag" of the latest stable version, or "trunk," if you use `/trunk/` for
-stable.
-
-    Note that the `readme.txt` of the stable tag is the one that is considered the defining one for the plugin, so
-if the `/trunk/readme.txt` file says that the stable tag is `4.3`, then it is `/tags/4.3/readme.txt` that'll be used
-for displaying information about the plugin.  In this situation, the only thing considered from the trunk `readme.txt`
-is the stable tag pointer.  Thus, if you develop in trunk, you can update the trunk `readme.txt` to reflect changes in
-your in-development version, without having that information incorrectly disclosed about the current stable version
-that lacks those changes -- as long as the trunk's `readme.txt` points to the correct stable tag.
-
-    If no stable tag is provided, it is assumed that trunk is stable, but you should specify "trunk" if that's where
-you put the stable version, in order to eliminate any doubt.
-
-== Installation ==
-
-This section describes how to install the plugin and get it working.
-
-e.g.
-
-1. Upload `plugin-name.php` to the `/wp-content/plugins/` directory
-1. Activate the plugin through the 'Plugins' menu in WordPress
-1. Place `<?php do_action('plugin_name_hook'); ?>` in your templates
-
-== Frequently Asked Questions ==
-
-= A question that someone might have =
-
-An answer to that question.
-
-= What about foo bar? =
-
-Answer to foo bar dilemma.
-
-== Screenshots ==
-
-1. This screen shot description corresponds to screenshot-1.(png|jpg|jpeg|gif). Note that the screenshot is taken from
-the /assets directory or the directory that contains the stable readme.txt (tags or trunk). Screenshots in the /assets
-directory take precedence. For example, `/assets/screenshot-1.png` would win over `/tags/4.3/screenshot-1.png`
-(or jpg, jpeg, gif).
-2. This is the second screen shot
-
-== Changelog ==
-
-= 1.0 =
-* A change since the previous version.
-* Another change.
-
-= 0.5 =
-* List versions from most recent at top to oldest at bottom.
-
-== Upgrade Notice ==
-
-= 1.0 =
-Upgrade notices describe the reason a user should upgrade.  No more than 300 characters.
-
-= 0.5 =
-This version fixes a security related bug.  Upgrade immediately.
-
-== Arbitrary section ==
-
-You may provide arbitrary sections, in the same format as the ones above.  This may be of use for extremely complicated
-plugins where more information needs to be conveyed that doesn't fit into the categories of "description" or
-"installation."  Arbitrary sections will be shown below the built-in sections outlined above.
-
-== A brief Markdown Example ==
-
-Ordered list:
-
-1. Some feature
-1. Another feature
-1. Something else about the plugin
-
-Unordered list:
-
-* something
-* something else
-* third thing
-
-Here's a link to [WordPress](http://wordpress.org/ "Your favorite software") and one to [Markdown's Syntax Documentation][markdown syntax].
-Titles are optional, naturally.
-
-[markdown syntax]: http://daringfireball.net/projects/markdown/syntax
-            "Markdown is what the parser uses to process much of the readme file"
-
-Markdown uses email style notation for blockquotes and I've been told:
-> Asterisks for *emphasis*. Double it up  for **strong**.
-
-`<?php code(); // goes in backticks ?>`
+Do not distribute a ZIP made directly from this directory. Run `make package` from the repository root so Composer production dependencies are rebuilt and the resulting archive is verified.

plugins/basicrum/README.md

@@ -0,0 +1,12 @@
+# Third-Party Notices
+
+Basicrum-owned code is licensed under the MIT License in `LICENSE.md`. The plugin also distributes the following third-party software under its own license.
+
+## Boomerang 1.815.60
+
+- Project: [Akamai Boomerang](https://github.com/akamai/boomerang)
+- Bundled file: `assets/js/boomr/boomerang-1.815.60.cutting-edge.min.js`
+- License: BSD License
+- License text: `assets/js/boomr/LICENSE.txt`
+
+The Boomerang copyright notice and license remain applicable to the bundled Boomerang file. Basicrum does not relicense that file under the Basicrum MIT License.

plugins/basicrum/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,37 @@
+Software Copyright License Agreement (BSD License)
+
+Copyright (c) 2011, Yahoo! Inc.
+Copyright (c) 2011-2012, Log-Normal, Inc.
+Copyright (c) 2012-2017, SOASTA, Inc.
+Copyright (c) 2017-2023, Akamai Technologies, Inc.
+All rights reserved.
+
+Redistribution and use of this software in source and binary forms,
+with or without modification, are permitted provided that the following
+conditions are met:
+
+* Redistributions of source code must retain the above
+  copyright notice, this list of conditions and the
+  following disclaimer.
+
+* Redistributions in binary form must reproduce the above
+  copyright notice, this list of conditions and the
+  following disclaimer in the documentation and/or other
+  materials provided with the distribution.
+
+* Neither the name of Yahoo! Inc. nor the names of its
+  contributors may be used to endorse or promote products
+  derived from this software without specific prior
+  written permission of Yahoo! Inc.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.