feat: collect 'em low-hanging-fruits (#85)

fixes #65

### Profiles and help UX
- Added dedicated `c8 help profiles` output (including `profile` alias handling) in `src/commands/help.ts`.
- Expanded command-help discoverability in shell completion suggestions in `src/commands/completion.ts`.
- Updated profile/help documentation in `README.md` and `EXAMPLES.md`.
- Added/updated help test coverage in `tests/unit/help.test.ts`.

### Profile/auth fix
- Fixed cloud Modeler mapping so `audience` stays optional unless explicitly configured (instead of being forced) in `src/config.ts`.
- Added regression coverage in `tests/unit/config.test.ts`.

### Search behavior and test stability
- Improved process-definition search determinism (sorting by version/key) and strengthened case-insensitive behavior/pagination in `src/commands/search.ts`.
- Stabilized integration polling/filter behavior in `tests/integration/search.test.ts` to avoid eventual-consistency flakiness.

### Plugin management improvements
- Implemented source-aware plugin upgrade/downgrade behavior with clearer actionable hints in `src/commands/plugins.ts`.
- Enhanced plugin listing/version visibility and added lifecycle/version test coverage in:
  - `tests/integration/plugin-lifecycle.test.ts`
  - `tests/unit/plugins-version.test.ts`
- Added plugin-help documentation in `PLUGIN-HELP.md`.

Author: vobu

EXAMPLES.md

@@ -666,13 +666,38 @@ c8ctl supports two types of profiles:
 1. **c8ctl profiles**: Directly managed by c8ctl commands
 2. **Modeler profiles**: Automatically imported from Camunda Modeler (read-only)
 
+### Show Profile Help
+
+```bash
+# Show all profile-related commands and flags
+c8 help profiles
+```
+
 ### Add c8ctl Profile
 
+`c8 add profile <name>` usage rules:
+
+- **Always required**: profile `<name>`
+- **Required for OAuth-secured clusters**: `--clientId`, `--clientSecret`
+- **Optional with defaults**:
+  - `--baseUrl` (default: `http://localhost:8080/v2`)
+  - `--defaultTenantId` (runtime default tenant: `<default>`)
+- **Optional without c8ctl defaults**: `--audience`, `--oAuthUrl`
+
 ```bash
-# Add profile with basic auth (localhost)
+# Minimal local profile (uses default --baseUrl)
+c8 add profile local
+
+# Local profile with explicit URL
 c8 add profile local --baseUrl=http://localhost:8080
 
-# Add profile with OAuth
+# Minimal OAuth profile (required OAuth switches)
+c8 add profile prod \
+  --baseUrl=https://camunda.example.com \
+  --clientId=your-client-id \
+  --clientSecret=your-client-secret
+
+# OAuth profile with explicit audience/token endpoint
 c8 add profile prod \
   --baseUrl=https://camunda.example.com \
   --clientId=your-client-id \
@@ -812,14 +837,14 @@ c8 unload plugin my-custom-plugin
 ### List Plugins
 
 ```bash
-# Show all installed c8ctl plugins with sync status
+# Show all installed c8ctl plugins with version and sync status
 c8 list plugins
 
 # Example output:
-# Name              | Status      | Source                    | Installed At
-# ------------------+-------------+---------------------------+----------------------
-# my-custom-plugin  | ✓ Installed | my-custom-plugin          | 1/30/2026, 6:00:00 PM
-# local-dev-plugin  | ⚠ Not installed | file:///path/to/plugin | 1/30/2026, 5:00:00 PM
+# Name              | Version | Status          | Source                    | Installed At
+# ------------------+---------+-----------------+---------------------------+----------------------
+# my-custom-plugin  | 1.2.0   | ✓ Installed     | my-custom-plugin          | 1/30/2026, 6:00:00 PM
+# local-dev-plugin  | Unknown | ⚠ Not installed | file:///path/to/plugin    | 1/30/2026, 5:00:00 PM
 
 # If any plugins are out of sync, you'll see a hint to run sync
 ```
@@ -852,6 +877,33 @@ c8 sync plugins
 # ✓ All plugins synced successfully!
 ```
 
+### Downgrade Plugin
+
+```bash
+# Downgrade a plugin by version
+c8 downgrade plugin my-custom-plugin 1.0.0
+
+# Downgrade is source-aware:
+# - npm source: installs my-custom-plugin@1.0.0
+# - git/URL source: installs <source>#1.0.0
+# - file:// source: version downgrade is not supported
+```
+
+### Upgrade Plugin
+
+```bash
+# Upgrade a plugin to latest
+c8 upgrade plugin my-custom-plugin
+
+# Upgrade a plugin to a specific version
+c8 upgrade plugin my-custom-plugin 1.2.3
+
+# Versioned upgrade is source-aware:
+# - npm source: installs my-custom-plugin@1.2.3
+# - git/URL source: installs <source>#1.2.3
+# - file:// source: version upgrade is not supported
+```
+
 **Plugin Development:**
 
 Plugins must be regular Node.js modules with a `c8ctl-plugin.js` or `c8ctl-plugin.ts` file in the root directory. The plugin file must export a `commands` object. The `c8ctl` runtime object provides environment information:

PLUGIN-HELP.md

@@ -151,6 +151,22 @@ Plugin Commands:
   status                  Check cluster status
 ```
 
+### Source-Aware Upgrade and Downgrade
+
+Plugin version changes (`upgrade` / `downgrade`) use the registry `source` value and therefore behave differently based on source type:
+
+- **npm package source**
+  - `c8ctl upgrade plugin <name> <version>` installs `<name>@<version>`
+  - `c8ctl downgrade plugin <name> <version>` installs `<name>@<version>`
+- **URL/git source**
+  - `c8ctl upgrade plugin <name> <version>` installs `<source>#<version>`
+  - `c8ctl downgrade plugin <name> <version>` installs `<source>#<version>`
+- **file source (`file://`)**
+  - Version-based upgrade/downgrade is not supported
+  - Use `c8ctl load plugin --from <file-url>` after checking out the desired local plugin version
+
+For `c8ctl upgrade plugin <name>` without a version, c8ctl reinstalls the registered source as-is
+
 ## Implementation Details
 
 ### Plugin Loader

README.md

@@ -87,6 +87,8 @@ c8ctl help fail       # Shows fail command with all flags
 c8ctl help activate   # Shows activate command with all flags
 c8ctl help publish    # Shows publish command with all flags
 c8ctl help correlate  # Shows correlate command with all flags
+c8ctl help profiles   # Shows profile management help
+c8ctl help plugin     # Shows plugin management help
 
 # Show version
 c8ctl --version
@@ -237,6 +239,12 @@ c8ctl supports two types of profiles:
 1. **c8ctl profiles**: Managed directly by c8ctl
 2. **Camunda Modeler profiles**: Automatically imported from Camunda Modeler (with `modeler:` prefix)
 
+For profile-related commands and flags, run:
+
+```bash
+c8ctl help profiles
+```
+
 ```bash
 # Add a c8ctl profile
 c8 add profile prod --baseUrl=https://camunda.example.com --clientId=xxx --clientSecret=yyy
@@ -246,7 +254,7 @@ c8 list profiles
 
 # Set active profile (works with both types)
 c8 use profile prod
-c8 use profile modeler:Local Dev
+c8 use profile "modeler:Local Dev"
 
 # Remove c8ctl profile (modeler profiles are read-only)
 c8 remove profile prod
@@ -349,7 +357,7 @@ c8ctl downgrade plugin <package-name> 1.0.0
 # Unload a plugin
 c8ctl unload plugin <package-name>
 
-# List installed plugins (shows sync status)
+# List installed plugins (shows version and sync status)
 c8ctl list plugins
 
 # Synchronize plugins from registry
@@ -369,11 +377,20 @@ c8ctl help
 - The registry serves as the source of truth for installed plugins
 - Default plugins are bundled with c8ctl and loaded automatically
 - **Plugin commands cannot override built-in commands** - built-in commands always take precedence
-- `c8ctl list plugins` shows sync status:
+- `c8ctl list plugins` shows plugin versions and sync status:
   - `✓ Installed` - Plugin is in registry and installed
   - `⚠ Not installed` - Plugin is in registry but not in global directory (run `sync`)
   - `⚠ Not in registry` - Plugin is installed but not tracked in registry
 - `c8ctl sync plugins` synchronizes plugins from the registry, rebuilding or reinstalling as needed
+- `c8ctl upgrade plugin <name> [version]` respects the plugin source from the registry:
+  - without `version`: reinstalls the registered source as-is
+  - npm package source with `version`: installs `<name>@<version>`
+  - URL/git source with `version`: installs `<source>#<version>`
+  - file source (`file://`) with `version`: version upgrade is not supported; use `load plugin --from` with the desired local plugin checkout
+- `c8ctl downgrade plugin <name> <version>` respects the plugin source from the registry:
+  - npm package source: installs `<name>@<version>`
+  - URL/git source: installs `<source>#<version>`
+  - file source (`file://`): version downgrade is not supported; use `load plugin --from` with the desired local plugin checkout
 
 **Plugin Development:**
 - Use `c8ctl init plugin <name>` to scaffold a new plugin with TypeScript template

src/commands/completion.ts

@@ -46,7 +46,7 @@ _c8ctl_completions() {
   local use_resources="profile tenant"
   local output_resources="json text"
   local completion_resources="bash zsh fish"
-  local help_resources="list get create complete await search deploy run watch cancel resolve fail activate publish correlate upgrade downgrade init"
+  local help_resources="list get create complete await search deploy run watch cancel resolve fail activate publish correlate upgrade downgrade init profiles profile plugin plugins"
 
   # Global flags
   local flags="--help --version --profile --from --all --bpmnProcessId --id --processInstanceKey --processDefinitionKey --parentProcessInstanceKey --variables --state --assignee --type --correlationKey --timeToLive --maxJobsToActivate --timeout --worker --retries --errorMessage --baseUrl --clientId --clientSecret --audience --oAuthUrl --defaultTenantId --awaitCompletion --fetchVariables --requestTimeout --name --key --elementId --errorType --value --scopeKey --fullValue --userTask --ut --processDefinition --pd --iname --iid --iassignee --ierrorMessage --itype --ivalue"
@@ -458,6 +458,10 @@ _c8ctl() {
             'upgrade:Show upgrade command help'
             'downgrade:Show downgrade command help'
             'init:Show init command help'
+            'profiles:Show profile management help'
+            'profile:Alias for profile management help'
+            'plugin:Show plugin management help'
+            'plugins:Alias for plugin management help'
           )
           _describe 'resource' resources
           ;;
@@ -867,6 +871,14 @@ complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'downgrade' -d 'Show
 complete -c c8 -n '__fish_seen_subcommand_from help' -a 'downgrade' -d 'Show downgrade command help'
 complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'init' -d 'Show init command help'
 complete -c c8 -n '__fish_seen_subcommand_from help' -a 'init' -d 'Show init command help'
+complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'profiles' -d 'Show profile management help'
+complete -c c8 -n '__fish_seen_subcommand_from help' -a 'profiles' -d 'Show profile management help'
+complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'profile' -d 'Alias for profile management help'
+complete -c c8 -n '__fish_seen_subcommand_from help' -a 'profile' -d 'Alias for profile management help'
+complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'plugin' -d 'Show plugin management help'
+complete -c c8 -n '__fish_seen_subcommand_from help' -a 'plugin' -d 'Show plugin management help'
+complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'plugins' -d 'Alias for plugin management help'
+complete -c c8 -n '__fish_seen_subcommand_from help' -a 'plugins' -d 'Alias for plugin management help'
 `;
 }
 

src/commands/help.ts

@@ -70,7 +70,7 @@ Commands:
   load      plugin <name>    Load a c8ctl plugin from npm registry
   load      plugin --from    Load a c8ctl plugin from URL (file://, https://, git://)
   unload    plugin <name>    Unload a c8ctl plugin (npm uninstall wrapper)
-  upgrade   plugin <name> [version]  Upgrade a plugin to latest or specific version
+  upgrade   plugin <name> [version]  Upgrade a plugin (respects source type)
   downgrade plugin <name> <version>  Downgrade a plugin to a specific version
   sync      plugin           Synchronize plugins from registry (rebuild/reinstall)
   init      plugin [name]    Create a new plugin from TypeScript template
@@ -167,6 +167,7 @@ Examples:
   c8ctl load plugin my-plugin        Load plugin from npm registry
   c8ctl load plugin --from file:///path/to/plugin  Load plugin from file URL
   c8ctl upgrade plugin my-plugin     Upgrade plugin to latest version
+  c8ctl upgrade plugin my-plugin 1.2.3  Upgrade plugin to a specific version (source-aware)
   c8ctl sync plugin                  Synchronize plugins
   c8ctl completion bash              Generate bash completion script
 
@@ -187,6 +188,9 @@ For detailed help on specific commands with all available flags:
   c8ctl help activate                Show activate command with all flags
   c8ctl help publish                 Show publish command with all flags
   c8ctl help correlate               Show correlate command with all flags
+  c8ctl help profiles                Show profile management help
+  c8ctl help plugin                  Show plugin management help
+  c8ctl help plugins                 Alias for plugin management help
 `.trim());
 }
 
@@ -219,7 +223,7 @@ export function showVerbResources(verb: string): void {
     use: 'profile, tenant',
     output: 'json, text',
     completion: 'bash, zsh, fish',
-    help: 'list, get, create, complete, await, search, deploy, run, watch, cancel, resolve, fail, activate, publish, correlate, upgrade, downgrade, init',
+    help: 'list, get, create, complete, await, search, deploy, run, watch, cancel, resolve, fail, activate, publish, correlate, upgrade, downgrade, init, profiles, profile, plugin, plugins',
   };
 
   const available = resources[verb];
@@ -273,7 +277,7 @@ Resources and their available flags:
     (Modeler profiles are shown with 'modeler:' prefix)
 
   plugins
-    Shows installed plugins with sync status
+    Shows installed plugins with version and sync status
 
 Examples:
   c8ctl list pi --state=ACTIVE
@@ -813,6 +817,110 @@ Examples:
 `.trim());
 }
 
+/**
+ * Show detailed help for profile management
+ */
+export function showProfilesHelp(): void {
+  console.log(`
+c8ctl profiles - Profile management
+
+Usage: c8ctl <command> profile[s] [args] [flags]
+
+Profile commands:
+
+  list profiles
+    List all profiles (c8ctl + Camunda Modeler profiles).
+    Modeler profiles are shown with "modeler:" prefix.
+
+  add profile <name> [flags]
+    Add a c8ctl-managed profile.
+
+  remove profile <name>
+  rm profile <name>
+    Remove a c8ctl-managed profile.
+
+  use profile <name>
+    Set active profile for the current session.
+
+Flags for add profile:
+  Required for all add profile calls:
+    (none)
+
+  Required for OAuth-secured clusters:
+    --clientId <id>          OAuth client ID
+    --clientSecret <secret>  OAuth client secret
+
+  Optional (with defaults):
+    --baseUrl <url>          Cluster base URL (default: http://localhost:8080/v2)
+    --defaultTenantId <id>   Default tenant ID (default at runtime: <default>)
+
+  Optional (no c8ctl default):
+    --audience <audience>    OAuth audience
+    --oAuthUrl <url>         OAuth token endpoint
+
+Examples:
+  c8ctl list profiles
+  c8ctl add profile local --baseUrl=http://localhost:8080
+  c8ctl add profile prod --baseUrl=https://camunda.example.com --clientId=xxx --clientSecret=yyy
+  c8ctl use profile prod
+  c8ctl use profile "modeler:Local Dev"
+  c8ctl remove profile local
+`.trim());
+}
+
+/**
+ * Show detailed help for plugin management
+ */
+export function showPluginHelp(): void {
+  console.log(`
+c8ctl plugin - Plugin management
+
+Usage: c8ctl <command> plugin [args] [flags]
+
+Plugin commands:
+
+  load plugin <name>
+    Load a plugin from npm registry.
+
+  load plugin --from <url>
+    Load a plugin from URL source (file://, https://, git://, github:).
+
+  unload plugin <name>
+    Unload and unregister a plugin.
+
+  list plugins
+    List installed plugins with version and sync status.
+
+  sync plugins
+    Rebuild/reinstall plugins from registry.
+
+  upgrade plugin <name> [version]
+    Upgrade plugin source.
+    - without version: reinstalls registered source as-is
+    - npm source with version: installs <name>@<version>
+    - URL/git source with version: installs <source>#<version>
+    - file:// source with version: not supported, use load plugin --from
+
+  downgrade plugin <name> <version>
+    Downgrade plugin source.
+    - npm source: installs <name>@<version>
+    - URL/git source: installs <source>#<version>
+    - file:// source: not supported, use load plugin --from
+
+  init plugin [name]
+    Create a new plugin scaffold from template.
+
+Examples:
+  c8ctl load plugin my-plugin
+  c8ctl load plugin --from file:///path/to/plugin
+  c8ctl list plugins
+  c8ctl upgrade plugin my-plugin
+  c8ctl upgrade plugin my-plugin 1.2.3
+  c8ctl downgrade plugin my-plugin 1.0.0
+  c8ctl init plugin my-plugin
+`.trim());
+}
+
 /**
  * Show detailed help for specific commands
  */
@@ -867,6 +975,14 @@ export function showCommandHelp(command: string): void {
     case 'correlate':
       showCorrelateHelp();
       break;
+    case 'profiles':
+    case 'profile':
+      showProfilesHelp();
+      break;
+    case 'plugin':
+    case 'plugins':
+      showPluginHelp();
+      break;
     default:
       console.log(`\nNo detailed help available for: ${command}`);
       console.log('Run "c8ctl help" for general usage information.');