Split per-command docs out of the README into /docs

AGENTS.md

@@ -150,6 +150,8 @@ import featureName from '../commands/feature-name.js';
 prettyCLI.command(featureName);
 ```
 
+**Docs** - Document the command in `docs/<group>.md` (a `## <command-id>` section with usage examples and an "Available options" list matching `setup()`), and add a row to the command index table in `README.md` linking to that section.
+
 ## Key Libraries
 
 - `@tryghost/admin-api` - Ghost Admin API client
@@ -218,4 +220,5 @@ Tests are in `test/` directory. Mock the Ghost API client for unit tests.
 - `Tools:` - File utilities (zip, json splitting)
 - `Content:` - Post/page API operations
 - `Members:` - Member API operations
+- `Staff:` - Staff user API operations
 - `Beta:` - Experimental features

commands/comment-notifications.js

@@ -53,7 +53,9 @@ export const run = async (argv) => {
         ui.log.error(
             'No action specified. Please provide at least one of: --backup, --restore, or --value',
         );
-        ui.log.info('See the README for usage examples, or run with --help for available options.');
+        ui.log.info(
+            'Run `gctools comment-notifications --help` for usage examples and available options.',
+        );
         return;
     }
 

commands/content-stats.js

@@ -10,7 +10,7 @@ const group = 'Content:';
 const flags = 'content-stats <apiURL> <adminAPIKey>';
 
 // Description for the top level command
-const desc = 'See stats on how mich content your Ghost site has';
+const desc = 'See stats on how much content your Ghost site has';
 
 // Descriptions for the individual params
 const paramsDesc = ['URL to your Ghost API', 'Admin API key'];

commands/page-to-post.js

@@ -4,7 +4,7 @@ import pageToPost from '../tasks/page-to-post.js';
 // Internal ID in case we need one.
 const id = 'page-to-post';
 
-const group = 'Members:';
+const group = 'Content:';
 
 // The command to run and any params
 const flags = 'page-to-post <apiURL> <adminAPIKey>';

docs/beta.md

@@ -0,0 +1,26 @@
+# Beta commands
+
+Experimental features that may change or be promoted to another group.
+Expect rough edges and check the output carefully.
+
+> `gctools <command> --help` is always authoritative for the current flags and defaults.
+
+## json-clean
+
+Clean a JSON file so it only contains content. Optionally connect to a target Ghost site to automatically match and update user IDs, slugs, names, and emails by comparing against existing Ghost users (matched by email address). Users not found in Ghost can still be updated manually via interactive prompts.
+
+```sh
+# See all available options
+gctools json-clean --help
+
+# Clean a JSON file to only contain content
+gctools json-clean /path/to/file.json
+
+# Clean a JSON file and auto-update users from a Ghost site
+gctools json-clean /path/to/file.json --ghostApiUrl https://example.ghost.io --ghostAdminKey 1234:abcd
+```
+
+**Available options:**
+- `--ghostApiUrl`: Ghost site URL to fetch existing users (e.g. https://example.ghost.io)
+- `--ghostAdminKey`: Ghost Admin API key to authenticate with Ghost (format: id:secret)
+- `-V --verbose` (default: true): Show verbose output