wordpress-agent-kit 0.3.0 → 0.3.2

package/.github/skills/wp-abilities-verify/references/schema-lints.md

@@ -0,0 +1,118 @@
+# Schema Lints
+
+Static lints against an ability's `input_schema`. Schema hygiene is
+about *agent legibility*: orchestrating agents read the schema to
+figure out how to call the ability. A schema that's hard to parse,
+ambiguous, or misleading wastes turns even when the ability itself
+works.
+
+These lints are six small principles. Apply them by reading the
+schema, not by mechanically grepping — most plugins use enough
+formatting variety that grep recipes drift.
+
+## Lint 1 — `additionalProperties: false` for object schemas
+
+For top-level `'type' => 'object'` schemas, declare
+`'additionalProperties' => false` unless you deliberately accept
+extras. Without this, an agent passing a typo (`par_page` instead of
+`per_page`) gets accepted silently and falls through to the backing,
+which ignores the unknown key.
+
+- `additionalProperties: false` declared → OK.
+- `additionalProperties: true` declared → WARN, unless the schema is
+  for genuinely free-form metadata (payment custom fields, form
+  free-text); document the reason inline.
+- Not declared on an object schema → WARN.
+- Non-object root (string with enum, integer, etc.) → N/A. The lint
+  applies only to objects.
+
+## Lint 2 — every required field has a non-empty description
+
+For each entry in `required`, the matching `properties` entry must
+declare a non-empty `description`. Required fields are where agents
+most need guidance; an opaque required key forces the agent to guess
+from the field name alone. Empty / missing → FAIL.
+
+Optional-field descriptions are nice-to-have — absence is WARN.
+
+## Lint 3 — enums are non-empty
+
+`'enum' => []` accepts no values, rejecting every input. Almost always
+a bug. → FAIL.
+
+A single-value enum (`'enum' => [ 'pending' ]`) is legal but unusual;
+WARN and prompt for review — often a copy-paste that lost the other
+values.
+
+## Lint 4 — no `$ref`
+
+Agents read the schema via REST introspection. A `$ref` forces the
+agent to follow a reference to see the field shape — wastes a turn and
+often breaks because the referenced schema isn't in the same document.
+Inline the shape instead.
+
+Any `'$ref'` in the schema → FAIL.
+
+## Lint 5 — defaults are statically constant
+
+Each `'default'` value must evaluate to the same shape on every call:
+
+- Scalar literals — `true`, `false`, integer, float, quoted string,
+  `null` → OK.
+- Empty or all-literal arrays — `[]`, `array()`, `[ 'a', 'b' ]` → OK.
+- Literal cast to an empty object — `(object) array()`, `(object) []`
+  → OK. This is the recommended top-level default for zero-arg-allowed
+  abilities; see
+  `../../wp-abilities-api/references/input-schema-gotchas.md` §4.
+- `new stdClass()` with no arguments → OK.
+- A function call (`gmdate('c')`, `wp_generate_uuid4()`, `time()`),
+  variable reference, or other computed expression → FAIL.
+
+The principle: defaults that vary per call are both non-deterministic
+and surprising to agents that expect defaults to be static.
+
+## Lint 6 — `reference_ability: true` implies no required inputs
+
+If an audit doc is provided and an ability has
+`reference_ability: true`, its `input_schema.required` array must be
+empty or absent. The reference ability is the smallest, safest
+bootstrap call an implementer lands first; it must work with
+`execute([])`. Required inputs on the reference ability → FAIL.
+
+(No audit provided → this lint is skipped — no reference ability is
+declared.)
+
+## Cross-reference: gotchas 1-3 (callback hardening) and gotcha 4 (structural default)
+
+Static lints catch shape; the four runtime gotchas in
+`../../wp-abilities-api/references/input-schema-gotchas.md` split into
+two kinds.
+
+Gotchas 1-3 need defensive code in the execute callback —
+`array_key_exists` instead of `isset`-only for property defaults,
+pagination key translation, ID validation that accepts `"0"`. These
+are runtime behaviors the callback itself must handle; static schema
+lints can't enforce them.
+
+Gotcha 4 — the direct vs indirect invocation strictness — is what
+motivates the `(object) array()` top-level default that Lint 5
+explicitly accepts. This one IS structural and Lint 5 carries the
+enforcement.
+
+## Output format
+
+```markdown
+## Schema lints
+
+| Ability | Lint | Result | Detail |
+|---|---|---|---|
+| <ability> | additionalProperties (object schemas) | WARN | not declared on object schema |
+| <ability> | required-field descriptions | OK | 3/3 required fields documented |
+| <ability> | enum non-empty | OK | no enums |
+| <ability> | no $ref | OK | inline |
+| <ability> | static defaults | FAIL | `created_at` uses `gmdate('c')` |
+| <ability> | reference_ability implies no required | N/A | not reference ability |
+```
+
+A FAIL on any lint flips that ability to FAIL in the run summary.
+WARNs surface but don't block.

package/.github/skills/wp-abilities-verify/references/static-enumeration.md

@@ -0,0 +1,126 @@
+# Static Enumeration
+
+Enumerate a plugin's abilities from source, with no running
+environment. Static enumeration is necessarily best-effort — PHP's
+dynamism (variable indirection, runtime-conditional registration)
+means a complete inventory only comes from a live `wp_get_abilities()`
+call. When static and runtime inventories diverge, trust runtime;
+static drives the diff so the reviewer knows where to look.
+
+## Typical registration shape
+
+```php
+wp_register_ability(
+    '<plugin-slug>/<ability-name>',
+    array(
+        'label'               => __( '...', '<text-domain>' ),
+        'description'         => __( '...', '<text-domain>' ),
+        'category'            => '<category-slug>',
+        'input_schema'        => array( /* ... */ ),
+        'execute_callback'    => array( self::class, 'execute_my_ability' ),
+        'permission_callback' => array( self::class, 'check_permission' ),
+        'meta'                => array(
+            'annotations' => array(
+                'readonly'    => true,
+                'destructive' => false,
+                'idempotent'  => true,
+            ),
+            'show_in_rest' => true,
+        ),
+    )
+);
+```
+
+## Step 1 — find every registration call
+
+```bash
+grep -rn --include='*.php' 'wp_register_ability\s*(' <plugin-root>/
+```
+
+Zero hits → return a clear "no abilities registered" report per
+SKILL.md "Failure modes." Don't fabricate an empty inventory.
+
+## Step 2 — extract each ability name
+
+The first argument is the ability name — usually a literal string.
+Real-world formatting splits the call across lines (the example
+above is itself multi-line), so single-line regexes miss common
+cases. Use a multi-line tool:
+
+```bash
+# ripgrep with --multiline + PCRE2 captures the name regardless of line break:
+rg --multiline --pcre2 --type=php -n \
+   "wp_register_ability\s*\(\s*['\"]([^'\"]+)['\"]" <plugin-root>/
+
+# Fallbacks: pcregrep -M, perl -0777.
+```
+
+If the first argument is a variable or constant
+(`wp_register_ability( $name, ... )`,
+`wp_register_ability( MyPlugin\NAME, ... )`), trace it: a recent
+assignment in the same function or a class constant usually resolves;
+a name computed in a loop won't, in which case flag the limitation and
+recommend runtime mode for authoritative enumeration.
+
+## Step 3 — extract the annotation block
+
+Annotations live at `meta.annotations.{readonly,destructive,idempotent}`.
+For each registration, read the array literal forward until the
+matching close. Common shapes:
+
+- Multi-line literal (most common).
+- Short-form one-liner.
+- Helper method (`'annotations' => self::annotations_for_read()`) —
+  resolve the helper if it returns a literal; otherwise mark
+  `<unresolved>` and run the adversarial check against the callback
+  alone.
+- Class constant (`'annotations' => self::READONLY_ANNOTATIONS`) —
+  resolve the constant.
+
+Record `ability_name → declared_annotations`.
+
+## Step 4 — follow `execute_callback` to its body
+
+`execute_callback` is one of:
+
+```php
+'execute_callback' => array( self::class, 'execute_get_things' ),
+'execute_callback' => array( My_Class::class, 'execute_get_things' ),
+'execute_callback' => array( $this, 'execute_get_things' ),
+'execute_callback' => 'my_plugin_execute_get_things',  // top-level function
+'execute_callback' => function ( $input ) { /* ... */ },  // closure
+```
+
+Resolve the reference to its source location: file + start line + end
+line. The annotation-correctness, schema-lint, and permission checks
+all operate on that byte range.
+
+## Limits of static enumeration
+
+Cases where the inventory is incomplete or ambiguous:
+
+- Variable-indirected names (`foreach` over a slug list).
+- Variable-indirected annotations (built from config).
+- Conditional registration (`if ( feature_enabled() )`).
+- Variable-indirected callbacks (`array( $this, $callback_name )`).
+
+Record each in the report's "Static enumeration limitations" section
+and recommend a runtime-mode rerun for the authoritative inventory.
+
+## Output format
+
+```markdown
+## Static inventory
+
+Found <N> ability registrations across <M> files:
+
+| Ability | Source file | Registration line | Callback file | Callback lines |
+|---|---|---|---|---|
+| myplugin/get-foo | src/Abilities.php | 42 | src/Abilities.php | 102-134 |
+| myplugin/submit-bar | src/Abilities.php | 68 | src/Services/Bar.php | 58-91 |
+
+### Limitations
+
+- <ability>: annotations built dynamically in `annotations_for_read()`;
+  recommend runtime mode for annotation cross-check.
+```

package/.github/skills/wp-plugin-directory-guidelines/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: wp-plugin-directory-guidelines
+description: "Use when reviewing WordPress plugins for GPL compliance, checking license headers or compatibility, evaluating upsell/freemium/trialware patterns, validating plugin naming or trademark rules, checking plugin slugs, understanding why a plugin was rejected from WordPress.org, or answering any question about the 18 WordPress.org Plugin Directory guidelines — even if the user doesn't mention 'guidelines' explicitly."
+license: GPL-2.0-or-later
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+)."
+---
+
+## Overview
+
+Authoritative reference for the 18 WordPress.org Plugin Directory guidelines. Covers GPL licensing, plugin naming/trademark rules, trialware restrictions, and all other submission requirements.
+
+## When to use
+
+Use this skill when you need to:
+- Review a WordPress plugin for compliance with the WordPress.org Plugin Directory guidelines
+- Check GPL license compatibility for a plugin or its bundled libraries
+- Verify license headers in plugin files
+- Identify common guideline violations before submission
+- Answer questions about what is or is not allowed on WordPress.org
+- Evaluate premium/upsell flows, license checks, or freemium positioning
+- Review "teaser" or "preview" UI for trialware violations
+
+## Inputs required
+
+- Plugin source code (or specific files to review)
+- Optional: plugin readme and plugin header metadata for naming and license checks
+
+## Procedure
+
+1. Check the plugin's license header against the **Valid License Headers** section below.
+2. Walk through the **18 Guidelines** checklist, paying special attention to Guidelines 1, 4, 5, 7, 8, and 17.
+3. Confirm trialware/freemium compliance using the checklist in [guideline-review-checklist.md](references/guideline-review-checklist.md) (Guideline 5 section).
+4. For bundled third-party code, verify license compatibility against **GPL-Compatible Licenses (Quick)** below.
+5. Flag matches from **Common GPL Violations (Quick)** below.
+6. For edge cases, consult the detailed references and the [GNU GPL FAQ](https://www.gnu.org/licenses/gpl-faq.html).
+
+## 18-Guideline Review Checklist
+
+Use the detailed, per-guideline checklist in [guideline-review-checklist.md](references/guideline-review-checklist.md). Load this reference file only when a full guideline audit is requested.
+
+## GPL Compliance (Guideline 1 in Detail)
+
+Use [gpl-compliance.md](references/gpl-compliance.md) for full license tables, compatibility nuances, and examples. Keep this inline section as a quick decision aid.
+
+### Verification (Licensing)
+
+- Every licensing-related issue must cite **Guideline 1** and include the file path and exact license string.
+- Confirm compatibility claims against **GPL-Compatible Licenses (Quick)** and escalate ambiguous licenses.
+
+### Failure modes (Licensing)
+
+- If a license is not clearly GPL-compatible, do not guess. Check the [GNU license list](https://www.gnu.org/licenses/license-list.html).
+- For dual-license packages, verify both licenses and redistribution terms.
+
+### Quick Reference: WordPress GPL Requirements
+
+- WordPress is **GPLv2 or later**.
+- Plugins distributed on WordPress.org must be 100% GPL-compatible (code and assets).
+- Include a valid `License:` header and `License URI:` in the main plugin file.
+- Do not add restrictions that conflict with GPL freedoms.
+
+### Valid License Headers
+
+## GPL Versions Summary
+
+| Version | Year | Key Addition |
+|---------|------|--------------|
+| GPLv1 | 1989 | Base copyleft: share-alike for modifications |
+| GPLv2 | 1991 | "Liberty or death" clause (Section 7), clearer distribution terms |
+| GPLv3 | 2007 | Anti-tivoization, explicit patent grants, compatibility provisions |
+
+WordPress uses **GPLv2 or later**, meaning plugins can use GPLv2, GPLv3, or "GPLv2 or later".
+
+For full license texts, see:
+- [GNU General Public License v1](https://www.gnu.org/licenses/gpl-1.0.html)
+- [GNU General Public License v2](https://www.gnu.org/licenses/gpl-2.0.html)
+- [GNU General Public License v3](https://www.gnu.org/licenses/gpl-3.0.html)
+
+## License Compliance Checklist
+
+When reviewing a plugin, verify:
+
+- [ ] Main plugin file has a valid `License:` header (e.g., `GPL-2.0-or-later`, `GPL-2.0+`, `GPLv2 or later`)
+- [ ] Main plugin file has a `License URI:` header pointing to the GPL text
+- [ ] If bundled libraries exist, each has a GPL-compatible license
+- [ ] No "split licensing" (e.g., code GPL but premium features proprietary)
+- [ ] No additional restrictions beyond what GPL allows
+- [ ] No clauses restricting commercial use, modification, or redistribution
+- [ ] No obfuscated code (violates the spirit of source code availability)
+
+## Valid License Headers for WordPress Plugins
+
+```
+License: GPL-2.0-or-later
+License URI: https://www.gnu.org/licenses/gpl-2.0.html
+```
+
+```text
+License: GPL-3.0-or-later
+License URI: https://www.gnu.org/licenses/gpl-3.0.html
+```
+
+```text
+License: GPLv2 or later
+License URI: https://www.gnu.org/licenses/gpl-2.0.html
+```
+
+### GPL-Compatible Licenses (Quick)
+
+- Safe defaults: GPL-2.0-or-later, GPL-3.0-or-later.
+- Commonly accepted permissive families: MIT/Expat, BSD, ISC, zlib, Boost.
+- Conditional compatibility requires care: Apache-2.0 and MPL-2.0 (verify usage context).
+- For full accepted and rejected identifiers, use [gpl-compliance.md](references/gpl-compliance.md).
+
+### Common GPL Violations (Quick)
+
+- Split licensing that restricts distributed code.
+- Obfuscated or non-corresponding source distribution.
+- Restrictive clauses (non-commercial, no-resale, forced backlink).
+- Bundling GPL-incompatible libraries or assets.
+
+## Plugin Naming Rules (Guideline 17)
+
+Use [naming-rules.md](references/naming-rules.md) for full trademark lists, slug blocks, and naming examples. Keep this inline checklist for quick screening.
+
+### Naming Checklist (Quick)
+
+- Name is not a placeholder and has at least 5 alphanumeric characters.
+- Header name and readme name match.
+- Name is specific and function-related; avoid keyword stuffing.
+- Trademark/project names appear only after connectors like `for`, `with`, `using`, `and`.
+- No banned/discouraged terms or trademark portmanteaus.
+- Slug is lowercase, hyphenated, <= 50 chars, and avoids blocked terms.

package/.github/skills/wp-plugin-directory-guidelines/references/gpl-compliance.md

@@ -0,0 +1,217 @@
+## GPL Compliance (Guideline 1 in Detail)
+
+### Verification (Licensing)
+
+- Every licensing-related issue must cite **Guideline 1** and include the specific file/license value found.
+- License compatibility claims must match the GPL-Compatible Licenses table or the [GNU GPL-Compatible License List](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses).
+- Use local `references/` files when present; otherwise use authoritative external URLs.
+
+### Failure modes (Licensing)
+
+- If a license is not listed in the compatibility tables, do not guess; check the [GNU license list](https://www.gnu.org/licenses/license-list.html) or escalate.
+- If a plugin uses a dual-license model, verify both licenses independently.
+
+
+### Quick Reference: WordPress GPL Requirements
+
+WordPress is licensed under **GPLv2 or later**. All plugins distributed via WordPress.org must be:
+
+1. **100% GPL-compatible** (code, images, CSS, and all assets)
+2. Include a **license declaration** in the main plugin file header
+3. Include the **full license text** or a URI reference to it
+4. **Not restrict freedoms** granted by the GPL
+
+## GPL Versions Summary
+
+| Version | Year | Key Addition |
+|---------|------|--------------|
+| GPLv1 | 1989 | Base copyleft: share-alike for modifications |
+| GPLv2 | 1991 | Patent clause (Section 7), clearer distribution terms |
+| GPLv3 | 2007 | Anti-tivoization, explicit patent grants, compatibility provisions |
+
+WordPress uses **GPLv2 or later**, meaning plugins can use GPLv2, GPLv3, or "GPLv2 or later".
+
+For full license texts, see:
+- [GNU General Public License v1](https://www.gnu.org/licenses/gpl-1.0.html)
+- [GNU General Public License v2](https://www.gnu.org/licenses/gpl-2.0.html)
+- [GNU General Public License v3](https://www.gnu.org/licenses/gpl-3.0.html)
+
+## License Compliance Checklist
+
+When reviewing a plugin, verify:
+
+- [ ] Main plugin file has a valid `License:` header (e.g., `GPL-2.0-or-later`, `GPL-2.0+`, `GPLv2 or later`)
+- [ ] Main plugin file has a `License URI:` header pointing to the GPL text
+- [ ] If bundled libraries exist, each has a GPL-compatible license
+- [ ] No "split licensing" (e.g., code GPL but premium features proprietary)
+- [ ] No additional restrictions beyond what GPL allows
+- [ ] No clauses restricting commercial use, modification, or redistribution
+- [ ] No obfuscated code (violates the spirit of source code availability)
+
+## Valid License Headers for WordPress Plugins
+
+```
+License: GPL-2.0-or-later
+License URI: https://www.gnu.org/licenses/gpl-2.0.html
+```
+
+```
+License: GPL-3.0-or-later
+License URI: https://www.gnu.org/licenses/gpl-3.0.html
+```
+
+```
+License: GPLv2 or later
+License URI: https://www.gnu.org/licenses/gpl-2.0.html
+```
+
+## Accepted Licenses by the WordPress.org Plugin Directory
+
+Source: [Plugin Check - License_Utils trait](https://github.com/WordPress/plugin-check/blob/trunk/includes/Traits/License_Utils.php)
+
+The Plugin Directory accepts licenses matching these identifiers (after normalization). The validation uses `is_license_gpl_compatible()` with the pattern:
+
+```
+GPL|GNU|LGPL|MIT|FreeBSD|New BSD|BSD-3-Clause|BSD 3 Clause|OpenLDAP|Expat|Apache2|MPL20|ISC|CC0|Unlicense|WTFPL|Artistic|Boost|NCSA|ZLib|X11
+```
+
+### GPL Family (recommended)
+
+| Accepted Values | SPDX Identifier | License URI |
+|-----------------|-----------------|-------------|
+| `GPL-2.0-or-later`, `GPLv2 or later`, `GPL-2.0+` | GPL-2.0-or-later | https://www.gnu.org/licenses/gpl-2.0.html |
+| `GPL-2.0-only`, `GPLv2` | GPL-2.0-only | https://www.gnu.org/licenses/gpl-2.0.html |
+| `GPL-3.0-or-later`, `GPLv3 or later`, `GPL-3.0+` | GPL-3.0-or-later | https://www.gnu.org/licenses/gpl-3.0.html |
+| `GPL-3.0-only`, `GPLv3` | GPL-3.0-only | https://www.gnu.org/licenses/gpl-3.0.html |
+| `GNU General Public License` (any version text) | — | — |
+| `LGPL-2.1`, `LGPLv2.1` | LGPL-2.1-or-later | https://www.gnu.org/licenses/lgpl-2.1.html |
+| `LGPL-3.0`, `LGPLv3` | LGPL-3.0-or-later | https://www.gnu.org/licenses/lgpl-3.0.html |
+
+### Other GPL-Compatible Licenses Accepted
+
+| Identifier | License Name | Notes |
+|------------|-------------|-------|
+| `MIT` | MIT License | Permissive, compatible with GPLv2 and GPLv3 |
+| `Expat` | Expat License | Functionally equivalent to MIT |
+| `X11` | X11 License | Permissive; similar to Expat but with extra X Consortium clause |
+| `FreeBSD` | BSD 2-Clause (FreeBSD) | Permissive, compatible with GPLv2 and GPLv3 |
+| `New BSD`, `BSD-3-Clause`, `BSD 3 Clause` | BSD 3-Clause | Permissive, compatible with GPLv2 and GPLv3 |
+| `Apache2`, `Apache-2.0` | Apache License 2.0 | Compatible with GPLv3 only (NOT GPLv2) |
+| `MPL20`, `MPL-2.0` | Mozilla Public License 2.0 | Compatible via Section 3.3 |
+| `ISC` | ISC License | Permissive, compatible with GPLv2 and GPLv3 |
+| `OpenLDAP` | OpenLDAP Public License v2.7 | Permissive; older v2.3 is NOT compatible |
+| `CC0` | Creative Commons Zero | Public domain dedication |
+| `Unlicense` | The Unlicense | Public domain dedication |
+| `WTFPL` | Do What The F*** You Want To Public License | Permissive, accepted in full text form too |
+| `Artistic` | Artistic License 2.0 | Compatible via relicensing option in §4(c)(ii); Artistic 1.0 is NOT compatible |
+| `Boost` | Boost Software License 1.0 | Lax permissive, compatible with GPLv2 and GPLv3 |
+| `NCSA` | NCSA/University of Illinois Open Source License | Based on Expat + modified BSD; compatible with GPLv2 and GPLv3 |
+| `ZLib` | zlib License | Permissive, compatible with GPLv2 and GPLv3 |
+
+### Licenses NOT Accepted
+
+Any license not matching the identifiers above will be rejected. Common rejections include:
+
+- **Proprietary / All Rights Reserved**
+- **Creative Commons BY-NC** (NonCommercial restriction)
+- **Creative Commons BY-ND** (NoDerivatives restriction)
+- **Creative Commons BY-SA** (v3.0 and earlier; v4.0 is one-way compatible with GPLv3 but not in the Plugin Check regex)
+- **JSON License** ("shall be used for Good, not Evil")
+- **SSPL** (Server Side Public License)
+- **BSL** (Business Source License)
+- **Commons Clause**
+- **Elastic License**
+- **Original BSD (4-clause)** — advertising clause incompatible with GPL
+- **MPL-1.0** — only MPL 2.0 is GPL-compatible
+- **EPL** (Eclipse Public License) — weak copyleft, incompatible with GPL
+- **EUPL** (European Union Public License) — copyleft incompatible with GPL without multi-step relicensing
+- **Artistic License 1.0** — vague wording makes it incompatible; use 2.0 instead
+- **OpenLDAP v2.3** (old) — incompatible; v2.7 is accepted
+
+## Common GPL Violations in Plugin Review
+
+### 1. Split Licensing
+Plugin claims GPL but restricts premium features:
+- "Free version is GPL, premium is proprietary" - **VIOLATION**
+- All code distributed must be GPL-compatible
+
+### 2. Obfuscated Code
+- Minified JavaScript is acceptable IF source is provided
+- PHP obfuscation (ionCube, Zend Guard, etc.) - **VIOLATION** (prevents exercise of GPL freedoms)
+- Encoded/encrypted PHP - **VIOLATION**
+
+### 3. Missing License Information
+- No license header in main file
+- No license file in the package
+- Bundled libraries without license documentation
+
+### 4. Restrictive Clauses
+- "You may not sell this plugin" - **VIOLATION** (GPL allows commercial redistribution)
+- "You may not remove author credits" - Acceptable under GPLv3 Section 7(b), but not as blanket restriction
+- "For personal use only" - **VIOLATION**
+- "You must link back to our site" - **VIOLATION** (additional restriction)
+
+### 5. Incompatible Library Inclusion
+- Including code under GPL-incompatible licenses
+- Using assets (images, fonts, CSS) under restrictive licenses
+
+## Key GPL Concepts for Reviewers
+
+### Distribution vs. Private Use
+- GPL obligations activate upon **distribution** (conveying to others)
+- Private modifications do NOT trigger GPL requirements
+- Publishing on WordPress.org IS distribution
+
+### Derivative Works
+- A WordPress plugin that uses WordPress APIs is generally considered a derivative work
+- Plugins that merely aggregate with WordPress may have different considerations
+- When in doubt, the safe approach is GPL-compatible licensing
+
+### Source Code Requirement
+- GPL requires access to "complete corresponding source code"
+- For WordPress plugins: all PHP, JS source files, build scripts
+- Minified files must have corresponding source available
+
+### The "Or Later" Clause
+- "GPLv2 or later" allows users to choose GPLv2 OR any later version
+- "GPLv2 only" means strictly GPLv2 (less flexible but valid)
+- WordPress itself uses "GPLv2 or later"
+
+## Violation Reporting Workflow
+
+When a GPL violation is identified:
+
+1. **Document the violation** precisely:
+   - Product name and version
+   - Distributor information
+   - Specific license terms violated
+   - Evidence (screenshots, code snippets)
+
+2. **Contact the copyright holder** first
+3. **Report to FSF** if the code is FSF-copyrighted: license-violation@gnu.org
+4. **For WordPress.org plugins**: flag through the plugin review process
+
+## Frequently Asked Questions
+
+For comprehensive GPL FAQ answers, see the [GNU GPL FAQ](https://www.gnu.org/licenses/gpl-faq.html).
+
+Common questions during plugin review:
+
+**Can a plugin charge money and still be GPL?**
+Yes. GPL allows charging for distribution. The requirement is that recipients get GPL freedoms (use, modify, redistribute).
+
+**Does a plugin need to include the full GPL text?**
+GPLv2 Section 1 and GPLv3 Section 4 require giving recipients a copy of the license. A URI reference in the header plus including a LICENSE file is standard practice.
+
+**Can a plugin restrict who uses it?**
+No. GPL explicitly prohibits additional restrictions on recipients. "For personal use only" or "non-commercial" clauses are incompatible.
+
+**Is minified JS without source a violation?**
+If the plugin only distributes minified JS without any way to obtain the source, this conflicts with GPL's source code requirements. The source should be available (in the package or via a repository).
+
+**Can a plugin use CC-BY-SA images?**
+CC-BY-SA 4.0 is one-way compatible with GPLv3 (CC-BY-SA material can be included in GPLv3 works). CC-BY-SA 3.0 is NOT compatible.
+
+**What about fonts bundled in plugins?**
+Fonts must be under GPL-compatible licenses. Common acceptable font licenses: OFL (SIL Open Font License), Apache 2.0 (with GPLv3), MIT, GPL with font exception.
+