From 5e19c2f799e671511704f455e9576f07a20642b7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 10 Jan 2026 11:18:01 +0000
Subject: [PATCH 1/2] Initial plan


From 0a2eae51952e0c6300d9de717048fbd1a3c50235 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 10 Jan 2026 11:29:29 +0000
Subject: [PATCH 2/2] Exclude command namespaces and missing commands from
 README generation

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
---
 features/scaffold-package-readme.feature | 43 ++++++++++++++++++++++++
 src/ScaffoldPackageCommand.php           | 19 ++++++++++-
 2 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/features/scaffold-package-readme.feature b/features/scaffold-package-readme.feature
index 4b64bab..2df7c25 100644
--- a/features/scaffold-package-readme.feature
+++ b/features/scaffold-package-readme.feature
@@ -386,3 +386,46 @@ Feature: Scaffold a README.md file for an existing package
       """
       **Alias:** `cpt`
       """
+
+  Scenario: README excludes command namespaces
+    Given an empty directory
+    And a foo/composer.json file:
+      """
+      {
+          "name": "wp-cli/namespace-test",
+          "description": "Test package for excluding command namespaces",
+          "license": "MIT",
+          "authors": [],
+          "minimum-stability": "dev",
+          "autoload": {
+              "files": [ "command.php" ]
+          },
+          "require": {
+              "wp-cli/wp-cli": "^2.12"
+          },
+          "require-dev": {
+              "wp-cli/wp-cli-tests": "^5.0.0"
+          },
+          "extra": {
+              "commands": [
+                "i18n",
+                "i18n make-pot"
+              ]
+          }
+      }
+      """
+
+    When I run `wp scaffold package-readme foo`
+    Then the foo/README.md file should exist
+    And the foo/README.md file should not contain:
+      """
+      ### wp i18n
+      """
+    And the foo/README.md file should not contain:
+      """
+      ### wp i18n make-pot
+      """
+    And the foo/README.md file should contain:
+      """
+      ## Using
+      """
diff --git a/src/ScaffoldPackageCommand.php b/src/ScaffoldPackageCommand.php
index 8f1f2a7..aa99edb 100644
--- a/src/ScaffoldPackageCommand.php
+++ b/src/ScaffoldPackageCommand.php
@@ -339,6 +339,22 @@ public function package_readme( $args, $assoc_args ) {
 				}
 				 */
 
+				// Skip commands that were not found or are namespaces with no meaningful content.
+				if ( false === $parent_command ) {
+					continue;
+				}
+
+				// Skip command namespaces (commands with subcommands but no meaningful content).
+				// This needs to be done before processing longdesc to accurately detect empty content.
+				$has_subcommands = ! empty( $parent_command['subcommands'] );
+				$shortdesc       = isset( $parent_command['description'] ) ? $parent_command['description'] : '';
+				$raw_longdesc    = isset( $parent_command['longdesc'] ) ? $parent_command['longdesc'] : '';
+				$is_namespace    = $has_subcommands && empty( trim( $shortdesc ) ) && empty( trim( $raw_longdesc ) );
+
+				if ( $is_namespace ) {
+					continue;
+				}
+
 				$longdesc = isset( $parent_command['longdesc'] ) ? $parent_command['longdesc'] : '';
 				$longdesc = (string) preg_replace( '/## GLOBAL PARAMETERS(.+)/s', '', $longdesc );
 				$longdesc = (string) preg_replace( '/##\s(.+)/', '**$1**', $longdesc );
@@ -346,9 +362,10 @@ public function package_readme( $args, $assoc_args ) {
 				// definition lists
 				$longdesc = preg_replace_callback( '/([^\n]+)\n: (.+?)(\n\n|$)/s', [ __CLASS__, 'rewrap_param_desc' ], $longdesc );
 
+				$shortdesc    = isset( $parent_command['description'] ) ? $parent_command['description'] : '';
 				$command_data = [
 					'name'      => "wp {$command}",
-					'shortdesc' => isset( $parent_command['description'] ) ? $parent_command['description'] : '',
+					'shortdesc' => $shortdesc,
 					'synopsis'  => "wp {$command}" . ( empty( $parent_command['subcommands'] ) ? ( isset( $parent_command['synopsis'] ) ? " {$parent_command['synopsis']}" : '' ) : '' ),
 					'longdesc'  => $longdesc,
 				];