@michaelhartmayer/agentctl 1.1.3 → 1.2.0

package/README.md

@@ -90,14 +90,31 @@ Teach your AI agent how to use `agentctl` by installing a skill file.
 agentctl ctl --install-skill cursor
 ```
 
-### Headless Execution
-Run agentic workflows directly from the CLI.
+### Provide the proper help copy
+When creating commands, make sure the `manifest.json` properly scopes its information:
+- `description`: A short summary of the command, displayed when viewing the list of available commands.
+- `help`: A longer set of instructions/usage string. For `group` types, this is displayed when calling the group without a subcommand. For `scaffold` types, this is currently for reference only; your command script must manually handle an `--help` flag for detailed usage.
+
+#### Scaffold Schema
+```json
+{
+  "name": "<command_folder_name>",
+  "description": "<insert command summary here>",
+  "help": "<insert longer usage/help instructions here>",
+  "type": "scaffold",
+  "run": "./command.cmd"
+}
+```
 
-```bash
-# Run a headless Gemini session in the current directory
-agentctl agent headless-gemini . "refactor the formatting in src/"
+#### Group Schema
+```json
+{
+  "name": "<group_folder_name>",
+  "description": "<insert group summary here>",
+  "help": "<insert longer group description/instructions here>",
+  "type": "group"
+}
 ```
-*(Requires `gemini-cli` installed and authenticated)*
 
 ---
 
@@ -105,17 +122,119 @@ agentctl agent headless-gemini . "refactor the formatting in src/"
 
 The `ctl` subcommand is the meta-layer for managing `agentctl` itself.
 
-| Command | Description |
-|---|---|
-| `scaffold <path>` | Create a new script-based command |
-| `alias <path> <target>` | Create a command that runs another command |
-| `group <path>` | Create a new namespace |
-| `rm <path>` | Remove a command or group |
-| `mv <src> <dest>` | and/or rename a command |
-| `list` | Show all commands (local + global) |
-| `inspect <path>` | JSON dump of command manifest |
-| `global <path>` | Promote local command to global |
-| `local <path>` | Pull global command to local |
+### `agentctl ctl scaffold <path>`
+Create a new script-based command. This generates a folder containing a `manifest.json` and a starter script (`command.cmd`/`command.sh`) for your logic.
+- **Why it's great:** Automates the boilerplate of creating a new CLI tool.
+- **When to use it:** When you have a complex script or an arbitrary executable (Node, Python, Go) you want to expose easily via the CLI.
+```bash
+agentctl ctl scaffold build:front
+agentctl ctl scaffold "build server" # Creates group 'build' and subcommand 'server'
+```
+
+### `agentctl ctl group <path>`
+Create a new namespace to organize subcommands. 
+- **Why it's great:** Keeps your CLI clean by grouping related tools without forcing you to write a parent CLI router.
+- **When to use it:** When you have a collection of similar commands (e.g., `db migrate`, `db reset`) and want an organized help menu grouping them under `db`.
+```bash
+agentctl ctl group data # Creates 'data' group
+agentctl ctl group "cloud aws" # Creates nested 'cloud/aws' groups
+```
+
+### `agentctl ctl alias <path> <target>`
+Create a command that simply runs an existing binary, string, or target.
+- **Why it's great:** Replaces bash aliases with structured, documentable commands that work locally or globally across environments and OSes.
+- **When to use it:** When you have a long, frequently used string (`docker compose run --rm node npm install`) and want a short name (`agentctl npm install`) without needing a whole generated shell script.
+```bash
+agentctl ctl alias "tools gh" gh
+agentctl ctl alias list-files "ls -la"
+```
+
+### `agentctl ctl rm [options] <path>`
+Permanently remove a command or entire group from your workspace.
+- **Why it's great:** Quickly clean up old tooling right from the CLI without needing to manually delete `.agentctl` directories.
+- **When to use it:** When retiring a script or cleaning up an obsolete group.
+
+**Options:**
+- `-g, --global`: Remove from global scope instead of local
+
+```bash
+agentctl ctl rm build:front # Removes local 'build front' command
+agentctl ctl rm mytool --global # Removes global 'mytool' command
+```
+
+### `agentctl ctl mv [options] <src> <dest>`
+Rename a command or move it to a new group/namespace.
+- **Why it's great:** Refactor your CLI commands like you'd refactor code, moving logic around namespaces without breaking the underlying executed scripts.
+- **When to use it:** When restructuring your toolbelt from a flat list to a nested categorization.
+
+**Options:**
+- `-g, --global`: Operate in global scope
+
+```bash
+agentctl ctl mv mytool my-new-tool
+agentctl ctl mv "tools ping" "network ping"
+agentctl ctl mv "tools ping" "network ping" --global # Moves in global scope
+```
+
+### `agentctl ctl list [options]`
+List all currently available commands across both your local and global scopes.
+- **Why it's great:** Generates an easy-to-read JSON summary of everything your agent can do.
+- **When to use it:** When programming an agent or exploring what tooling is available in a scoped project.
+
+```bash
+agentctl ctl list
+```
+
+### `agentctl ctl inspect [options] <path>`
+Dump the resolved manifest and location of a given command path.
+- **Why it's great:** Eliminates the "where did this command come from?" problem when debugging complex workspaces.
+- **When to use it:** When you have local/global conflicts or want to quickly see the JSON source manifest for a command.
+```bash
+agentctl ctl inspect dev:start
+```
+
+### `agentctl ctl global [options] <path>`
+Promote a local command or group to your globally available toolbelt.
+- **Why it's great:** Eject highly useful, generic project abstractions directly into your personal universal toolbelt.
+- **When to use it:** You wrote a script specific to a project and realized "I want this CLI tool in every repo I touch."
+
+**Options:**
+- `-c, --copy`: Copy the command (keep local version, default)
+- `-m, --move`: Move the command (delete local after copying)
+
+```bash
+agentctl ctl global "dev toolkit" # Copies the command to global scope
+agentctl ctl global "dev toolkit" --move # Moves it instead of copy
+```
+
+### `agentctl ctl local [options] <path>`
+Bring a global command down into the current local project environment.
+- **Why it's great:** Promotes collaboration seamlessly. You can take your personal script, localize it, and commit it to git for your entire team.
+- **When to use it:** You have a generic tool that is suddenly very relevant to a specific repository, and you want CI or your coworkers to access it.
+
+**Options:**
+- `-c, --copy`: Copy the command (keep global version, default)
+- `-m, --move`: Move the command (delete global after pulling)
+
+```bash
+agentctl ctl local "my global-tool"
+agentctl ctl local "my global-tool" --move
+```
+
+### `agentctl ctl install [options] <repo-url> [path...]`
+Install commands or groups directly from a remote Git repository's `.agentctl` folder into your local or global scope.
+- **Why it's great:** Provides dependency-free tool sharing! Distribute entire suites of scripts/commands without using a package manager.
+- **When to use it:** When you want to pull down shared utility commands that your team maintains in a central repository, or distribute your own tools to others.
+
+**Options:**
+- `-g, --global`: Install globally instead of locally
+- `--allow-collisions`: Allow overwriting existing commands or merging into groups
+
+```bash
+agentctl ctl install https://github.com/my-org/tools
+agentctl ctl install https://github.com/my-org/tools --global
+agentctl ctl install https://github.com/my-org/tools deploy --allow-collisions
+```
 
 ---
 

package/dist/ctl.js

@@ -181,7 +181,8 @@ async function install(repoUrl, pathArgs, options = {}) {
         pathParts: pathArgs,
         global: !!options.global,
         allowCollisions: !!options.allowCollisions,
-        localRoot: ctx.localRoot,
+        localRoot: ctx.localRoot || ctx.cwd,
+        isNewLocalRoot: !options.global && !ctx.localRoot,
         globalRoot: ctx.globalRoot,
         osTmpdir: os_1.default.tmpdir()
     };
@@ -238,9 +239,11 @@ async function list(options = {}) {
                 else if (manifest.type)
                     type = manifest.type;
             }
-            const item = { path: cmdPath, type, scope, description: manifest?.description || '' };
             if (!commands.has(cmdPath)) {
-                commands.set(cmdPath, item);
+                if (manifest) {
+                    const item = { path: cmdPath, type, scope, description: manifest.description || '' };
+                    commands.set(cmdPath, item);
+                }
                 const effectiveManifest = manifest || { name: file, type: 'group' };
                 if (!(0, manifest_1.isCappedManifest)(effectiveManifest))
                     await walk(filePath, cmdPathParts, scope);

package/dist/index.js

@@ -15,13 +15,47 @@ const path_1 = __importDefault(require("path"));
 const pkgPath = path_1.default.join(__dirname, '../package.json');
 const pkg = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf8'));
 const program = new commander_1.Command();
+program.addHelpCommand(false);
 program
     .name('agentctl')
     .description('Agent Controller CLI - Unified control plane for humans and agents')
     .version(pkg.version);
 // --- Subcommand: ctl ---
 const ctl = program.command('ctl')
-    .description('Agent Controller Management - Create, organize, and manage commands');
+    .description('Agent Controller Management - Create, organize, and manage commands')
+    .addHelpCommand(false)
+    .configureHelp({ visibleCommands: () => [] })
+    .action((opts, command) => {
+    command.help();
+})
+    .addHelpText('after', `
+${chalk_1.default.bold('Agentctl Paradigm:')}
+  Agentctl acts as a unified control plane allowing both Humans and AI Agents
+  to create, discover, and execute local shell commands. By running \`agentctl ctl scaffold <name>\`
+  you create a directory in the \`.agentctl\` folder containing a \`manifest.json\` 
+  and a run script. This dynamically creates a new \`agentctl <name>\` command that
+  is easily callable by agents and globally executable on your machine.
+
+Commands:
+
+  ${chalk_1.default.bold('Creation')}
+    scaffold [path...]                          create a new command
+    alias [args...]                             create a shell alias
+    group [path...]                             create a namespace group
+
+  ${chalk_1.default.bold('Organize & Scope')}
+    rm [options] [path...]                      delete a command
+    mv [options] [src] [dest]                   rename/move a command
+    global [options] [path...]                  make a command global
+    local [options] [path...]                   make a command local
+
+  ${chalk_1.default.bold('Information')}
+    list                                        list all commands
+    inspect [path...]                           inspect command details
+
+  ${chalk_1.default.bold('Integration')}
+    install [options] [repoUrl] [pathParts...]  install remote command group
+`);
 const withErrorHandling = (fn) => {
     return async (...args) => {
         try {
@@ -38,6 +72,7 @@ const withErrorHandling = (fn) => {
         }
     };
 };
+const normalizePath = (parts) => parts.flatMap(p => p.split(/[\s/\\:]+/).filter(Boolean));
 ctl.command('scaffold')
     .description('Scaffold a new command directory with a manifest and starter script.')
     .argument('[path...]', 'Hierarchical path for the new command (e.g., "dev start" or "utils/cleanup")')
@@ -45,20 +80,34 @@ ctl.command('scaffold')
     .addHelpText('after', `
 Additional Info:
   This command creates a folder in your local .agentctl directory.
-  Inside, it generates:
-    - manifest.json: Metadata about the command.
-    - command.sh/cmd: A starter script for your logic.
+  Inside this newly created folder, it generates:
+    - manifest.json: Metadata config to edit for your command.
+    - command.sh/cmd: A starter script to edit for your actual logic.
+    
+  Manifest Schema (manifest.json) to edit:
+  {
+    "name": "<command_folder_name>",
+    "description": "<insert command summary here>",
+    "help": "<insert longer usage/help instructions here>",
+    "type": "scaffold", // do not change!
+    "run": "./command.cmd" // points to the script to execute
+  }
+  
+  Note: 
+  - The "description" is displayed when you view this command in a list.
+  - Commands must provide their own help implementation (e.g. by handling --help inside your script).
 
 Examples:
-  $ agentctl ctl scaffold build front
-  $ agentctl ctl scaffold utils/backup
+  $ agentctl ctl scaffold build:front
+  $ agentctl ctl scaffold "build front" # Creates group 'build' and subcommand 'front'
 `)
     .action(withErrorHandling(async (pathParts, opts, command) => {
-    if (!pathParts || pathParts.length === 0) {
+    const normalized = normalizePath(pathParts);
+    if (normalized.length === 0) {
         command.help();
         return;
     }
-    await (0, ctl_1.scaffold)(pathParts);
+    await (0, ctl_1.scaffold)(normalized);
 }));
 ctl.command('alias')
     .description('Create a command that executes a raw shell string.')
@@ -75,7 +124,11 @@ Examples:
         return;
     }
     const target = args.pop();
-    const name = args;
+    const name = normalizePath(args);
+    if (name.length === 0) {
+        command.help();
+        return;
+    }
     await (0, ctl_1.alias)(name, target);
 }));
 ctl.command('group')
@@ -86,17 +139,33 @@ ctl.command('group')
 Additional Info:
   Groups allow you to categorize commands. Running a group command without
   subcommands will list all direct subcommands within that group.
+  
+  This command creates a folder in your local .agentctl directory.
+  Inside this newly created folder, it generates a manifest.json.
+  
+  Group Schema (manifest.json) to edit:
+  {
+    "name": "<group_folder_name>",
+    "description": "<insert group summary here>",
+    "help": "<insert longer group description/instructions here>",
+    "type": "group" // do not change!
+  }
+  
+  Note: 
+  - The "description" is displayed when you view this group in a list.
+  - The "help" is displayed when you call this group without a subcommand.
 
 Examples:
   $ agentctl ctl group dev
-  $ agentctl ctl group data/pipelines
+  $ agentctl ctl group "data pipelines" # Creates group 'data' and subgroup 'pipelines'
 `)
     .action(withErrorHandling(async (parts, opts, command) => {
-    if (!parts || parts.length === 0) {
+    const normalized = normalizePath(parts);
+    if (normalized.length === 0) {
         command.help();
         return;
     }
-    await (0, ctl_1.group)(parts);
+    await (0, ctl_1.group)(normalized);
 }));
 ctl.command('rm')
     .description('Permanently remove a command or group.')
@@ -105,15 +174,16 @@ ctl.command('rm')
     .summary('delete a command')
     .addHelpText('after', `
 Examples:
-  $ agentctl ctl rm dev start
-  $ agentctl ctl rm utils --global
-`)
+        $ agentctl ctl rm dev start
+  $ agentctl ctl rm utils--global
+        `)
     .action(withErrorHandling(async (parts, opts, command) => {
-    if (!parts || parts.length === 0) {
+    const normalized = normalizePath(parts);
+    if (normalized.length === 0) {
         command.help();
         return;
     }
-    await (0, ctl_1.rm)(parts, { global: opts.global });
+    await (0, ctl_1.rm)(normalized, { global: opts.global });
 }));
 ctl.command('mv')
     .description('Move or rename a command/group within its current scope.')
@@ -123,26 +193,28 @@ ctl.command('mv')
     .summary('rename/move a command')
     .addHelpText('after', `
 Examples:
-  $ agentctl ctl mv "dev start" "dev begin"
-  $ agentctl ctl mv utils scripts --global
-`)
+        $ agentctl ctl mv "dev start" "dev begin"
+  $ agentctl ctl mv utils scripts--global
+        `)
     .action(withErrorHandling(async (src, dest, opts, command) => {
-    if (!src || !dest) {
+    const normalizedSrc = normalizePath(src ? [src] : []);
+    const normalizedDest = normalizePath(dest ? [dest] : []);
+    if (normalizedSrc.length === 0 || normalizedDest.length === 0) {
         command.help();
         return;
     }
-    await (0, ctl_1.mv)(src.split(' '), dest.split(' '), { global: opts.global });
+    await (0, ctl_1.mv)(normalizedSrc, normalizedDest, { global: opts.global });
 }));
 ctl.command('list')
     .description('List all available commands across local and global scopes.')
     .summary('list all commands')
     .addHelpText('after', `
 Output Columns:
-  TYPE      - scaffold, alias, or group
-  SCOPE     - local (project-specific) or global (user-wide)
-  COMMAND   - The path used to invoke the command
+        TYPE - scaffold, alias, or group
+  SCOPE - local(project - specific) or global(user - wide)
+  COMMAND - The path used to invoke the command
   DESCRIPTION - Brief text from the command's manifest
-`)
+        `)
     .action(withErrorHandling(async () => {
     const items = await (0, ctl_1.list)();
     console.log(chalk_1.default.bold('TYPE      SCOPE     COMMAND             DESCRIPTION'));
@@ -158,14 +230,15 @@ ctl.command('inspect')
     .summary('inspect command details')
     .addHelpText('after', `
 Examples:
-  $ agentctl ctl inspect dev start
-`)
+        $ agentctl ctl inspect dev start
+        `)
     .action(withErrorHandling(async (parts, opts, command) => {
-    if (!parts || parts.length === 0) {
+    const normalized = normalizePath(parts);
+    if (normalized.length === 0) {
         command.help();
         return;
     }
-    const info = await (0, ctl_1.inspect)(parts);
+    const info = await (0, ctl_1.inspect)(normalized);
     if (info) {
         console.log(JSON.stringify(info, null, 2));
     }
@@ -182,18 +255,19 @@ ctl.command('global')
     .summary('make a command global')
     .addHelpText('after', `
 Additional Info:
-  Global commands are stored in your home directory and are available in any project.
+        Global commands are stored in your home directory and are available in any project.
 
-Examples:
-  $ agentctl ctl global utils/cleanup
-  $ agentctl ctl global dev/deploy --move
-`)
+        Examples:
+        $ agentctl ctl global utils / cleanup
+  $ agentctl ctl global dev / deploy--move
+        `)
     .action(withErrorHandling(async (parts, opts, command) => {
-    if (!parts || parts.length === 0) {
+    const normalized = normalizePath(parts);
+    if (normalized.length === 0) {
         command.help();
         return;
     }
-    await (0, ctl_1.pushGlobal)(parts, { move: opts.move, copy: opts.copy || !opts.move });
+    await (0, ctl_1.pushGlobal)(normalized, { move: opts.move, copy: opts.copy || !opts.move });
 }));
 ctl.command('local')
     .description('Pull a global command into the current local project.')
@@ -203,38 +277,16 @@ ctl.command('local')
     .summary('make a command local')
     .addHelpText('after', `
 Examples:
-  $ agentctl ctl local utils/shared
-  $ agentctl ctl local snippets/js --move
-`)
+        $ agentctl ctl local utils / shared
+  $ agentctl ctl local snippets / js--move
+        `)
     .action(withErrorHandling(async (parts, opts, command) => {
-    if (!parts || parts.length === 0) {
+    const normalized = normalizePath(parts);
+    if (normalized.length === 0) {
         command.help();
         return;
     }
-    await (0, ctl_1.pullLocal)(parts, { move: opts.move, copy: opts.copy || !opts.move });
-}));
-ctl.command('install-skill')
-    .description('Configure a supported AI agent (like Cursor or Gemini) to natively use Agentctl.')
-    .argument('[agent]', 'Agent name (cursor, antigravity, agentsmd, gemini)')
-    .option('-g, --global', 'Install globally for the agent (if supported)')
-    .summary('configure AI agent integration')
-    .addHelpText('after', `
-Supported Agents:
-  - cursor      (Installs to .cursor/skills)
-  - antigravity (Installs to .agent/skills or ~/.gemini/antigravity)
-  - agentsmd    (Installs to .agents/skills)
-  - gemini      (Installs to .gemini/skills or ~/.gemini/skills)
-
-Examples:
-  $ agentctl ctl install-skill cursor
-  $ agentctl ctl install-skill antigravity --global
-`)
-    .action(withErrorHandling(async (agent, opts, command) => {
-    if (!agent) {
-        command.help();
-        return;
-    }
-    await (0, ctl_1.installSkill)(agent, { global: opts.global });
+    await (0, ctl_1.pullLocal)(normalized, { move: opts.move, copy: opts.copy || !opts.move });
 }));
 ctl.command('install')
     .description('Install a command group from a remote Git repository.')
@@ -245,19 +297,20 @@ ctl.command('install')
     .summary('install remote command group')
     .addHelpText('after', `
 Additional Info:
-  Fetches the .agentctl folder from the remote repository and installs it into
+        Fetches the.agentctl folder from the remote repository and installs it into
   your local or global agentctl environment.
 
-Examples:
-  $ agentctl ctl install https://github.com/org/repo-tools
-  $ agentctl ctl install https://github.com/org/deploy-scripts deploy --global
-`)
+        Examples:
+        $ agentctl ctl install https://github.com/org/repo-tools
+        $ agentctl ctl install https://github.com/org/deploy-scripts deploy --global
+        `)
     .action(withErrorHandling(async (repoUrl, pathParts, opts, command) => {
     if (!repoUrl) {
         command.help();
         return;
     }
-    await (0, ctl_1.install)(repoUrl, pathParts, { global: opts.global, allowCollisions: opts.allowCollisions });
+    const normalized = normalizePath(pathParts || []);
+    await (0, ctl_1.install)(repoUrl, normalized, { global: opts.global, allowCollisions: opts.allowCollisions });
 }));
 // --- Dynamic Command Logic ---
 async function handleDynamicCommand(args) {
@@ -283,7 +336,7 @@ async function handleDynamicCommand(args) {
                         return e;
                     if (e.message.startsWith('  '))
                         return e;
-                    if (e.message === 'No description')
+                    if (e.message === 'Command group containing subcommands')
                         return { ...e, message: chalk_1.default.dim(e.message) };
                 }
                 return e;
@@ -309,7 +362,8 @@ async function handleDynamicCommand(args) {
             const lines = [''];
             lines.push(chalk_1.default.bold('User Commands:'));
             for (const cmd of topLevel) {
-                lines.push(`  ${chalk_1.default.yellow(cmd.path.padEnd(27))}${cmd.description}`);
+                const desc = cmd.description || 'Command group containing subcommands';
+                lines.push(`  ${chalk_1.default.yellow(cmd.path.padEnd(27))}${desc}`);
             }
             lines.push('');
             program.addHelpText('after', lines.join('\n'));

package/dist/logic/ctl.js

@@ -31,7 +31,8 @@ exports.Logic = {
         const effects = [{ type: 'mkdir', path: targetDir }];
         const manifest = {
             name,
-            description: '',
+            description: '<insert summary>',
+            help: '<insert usage/help instructions>',
             type,
         };
         if (type === 'scaffold') {

package/dist/logic/index.js

@@ -11,6 +11,15 @@ exports.AppLogic = {
             return [{ type: 'log', message: `Command '${args.join(' ')}' not found. Run 'agentctl list' to see available commands.` }];
         }
         const { manifest, args: remainingArgs, scope, manifestPath, cmdPath } = result;
+        const effects = [];
+        const allowedKeys = new Set(['name', 'description', 'help', 'type', 'run', 'flags']);
+        const unsupportedKeys = Object.keys(manifest).filter(k => !allowedKeys.has(k));
+        if (unsupportedKeys.length > 0) {
+            effects.push({
+                type: 'log',
+                message: `[WARNING] The manifest at ${manifestPath} contains unsupported keys: ${unsupportedKeys.join(', ')}. Agentctl will ignore them.`
+            });
+        }
         if (manifest.run) {
             const cmdDir = path_1.default.dirname(manifestPath);
             let runCmd = manifest.run;
@@ -19,33 +28,38 @@ exports.AppLogic = {
             }
             runCmd = runCmd.replace(/{{DIR}}/g, cmdDir);
             const fullCommand = `${runCmd} ${remainingArgs.join(' ')}`;
-            return [
-                { type: 'log', message: `[${scope}] Running: ${fullCommand}` },
-                {
-                    type: 'spawn',
-                    command: fullCommand,
-                    options: {
-                        cwd: process.cwd(),
-                        shell: true,
-                        stdio: 'inherit',
-                        env: { ...process.env, AGENTCTL_SCOPE: scope }
-                    },
-                    onExit: (code) => {
-                        process.exit(code || 0);
-                    }
+            effects.push({ type: 'log', message: `[${scope}] Running: ${fullCommand}` }, {
+                type: 'spawn',
+                command: fullCommand,
+                options: {
+                    cwd: process.cwd(),
+                    shell: true,
+                    stdio: 'inherit',
+                    env: { ...process.env, AGENTCTL_SCOPE: scope }
+                },
+                onExit: (code) => {
+                    process.exit(code || 0);
                 }
-            ];
+            });
+            return effects;
         }
         else {
-            return exports.AppLogic.planGroupList(manifest, cmdPath, []); // Shell will call this again with actual children
+            return [...effects, ...exports.AppLogic.planGroupList(manifest, cmdPath, [], manifestPath)];
         }
     },
-    planGroupList(manifest, cmdPath, allCommands) {
-        const effects = [
-            { type: 'log', message: manifest.name },
-            { type: 'log', message: manifest.description || 'No description' },
-            { type: 'log', message: '\nSubcommands:' }
-        ];
+    planGroupList(manifest, cmdPath, allCommands, manifestPath) {
+        const effects = [];
+        if (manifestPath) {
+            const allowedKeys = new Set(['name', 'description', 'help', 'type', 'run', 'flags']);
+            const unsupportedKeys = Object.keys(manifest).filter(k => !allowedKeys.has(k));
+            if (unsupportedKeys.length > 0) {
+                effects.push({
+                    type: 'log',
+                    message: `[WARNING] The manifest at ${manifestPath} contains unsupported keys: ${unsupportedKeys.join(', ')}. Agentctl will ignore them.`
+                });
+            }
+        }
+        effects.push({ type: 'log', message: manifest.name }, { type: 'log', message: manifest.help || manifest.description || 'Command group containing subcommands' }, { type: 'log', message: '\nSubcommands:' });
         const prefix = cmdPath + ' ';
         const depth = cmdPath.split(' ').length;
         const children = allCommands.filter(c => c.path.startsWith(prefix) && c.path !== cmdPath);
@@ -56,7 +70,8 @@ exports.AppLogic = {
         else {
             for (const child of direct) {
                 const name = child.path.split(' ').pop();
-                effects.push({ type: 'log', message: `  ${name}\t${child.description}` });
+                const desc = child.description || 'Command group containing subcommands';
+                effects.push({ type: 'log', message: `  ${name}\t${desc}` });
             }
         }
         return effects;

package/dist/logic/install.js

@@ -43,6 +43,9 @@ function planInstallCopy(ctx, deps) {
     }
     // Ensure target path exists
     effects.push({ type: 'mkdir', path: targetDir });
+    if (!ctx.global && ctx.isNewLocalRoot) {
+        effects.push({ type: 'log', message: `Initialized new .agentctl folder at ${agentctlDir}` });
+    }
     // Copy contents
     effects.push({
         type: 'copy',

package/package.json

@@ -4,7 +4,7 @@
     "access": "public"
   },
   "description": "Agent Controller - A unified interface for humans and AI agents",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "main": "dist/index.js",
   "bin": {
     "agentctl": "./dist/index.js"