Add --syntax help for humans and agents

README.md

@@ -4,8 +4,22 @@
 
 ![repocard](https://repocard.dannyben.com/svg/opcode.svg)
 
-Opcode lets you define a simple configuration file in any directory.
-This file includes shortcuts to other commands.
+Opcode lets you define a simple executable command catalog in any directory.
+It works as a lightweight makefile for humans, AI agents, and any workflow that
+benefits from short, memorable repo-local commands.
+
+Instead of repeatedly typing or pasting long commands, save them in `op.conf`
+and run them by name:
+
+```shell
+$ op check
+$ op test
+$ op deploy
+```
+
+Agents can also run a named command catalog like `agent check` or `agent test`,
+backed by `agent.op.conf`, without mixing generated helper commands into your
+main `op.conf`.
 
 ![Demo](/demo/cast.gif)
 
@@ -93,30 +107,23 @@ Usage:
   op -c, --config FILE CODE [ARGS]
     Use a specific config file
 
+  op --syntax
+    Show config file syntax
+
   op -h, --help
     Show this message
 
   op -v, --version
     Show version number
 ```
 
-## Config Selection
+Use `op --syntax` for a compact summary of the config file format.
 
-Use `-c, --config` or `OPCODE_CONFIG` to run commands from a specific config
-file:
+## Named Command Catalogs
 
-```shell
-$ op -c agent.op.conf check
-$ op --config agent.op.conf check
-$ OPCODE_CONFIG=agent.op.conf op check
-```
-
-The `-c, --config` flag must appear before the command code. Any `-c` that
-appears after the command code is passed through to the command as an argument.
-The flag has precedence over `OPCODE_CONFIG`.
-
-You can also create another local command namespace by symlinking `op` under a
-different name:
+Opcode can provide separate command namespaces by symlinking `op` under any
+other executable name. This is useful for AI agents, automation, or any workflow
+that should keep its commands separate from the main `op.conf`:
 
 ```shell
 $ cd /usr/local/bin  # or wherever op is installed
@@ -134,6 +141,13 @@ The `.op.conf` file is preferred when both files exist. A renamed executable
 does not fall back to `opcode` or `op.conf`; this keeps separately named
 catalogs from accidentally running commands from the main `op` namespace.
 
+This lets agents maintain reusable commands like `agent check`, `agent test`,
+or `agent fix-ci` while keeping the human-owned `op.conf` focused.
+
+Use `op --syntax` or `agent --syntax` for a compact summary of the config file
+format. Config files can also be selected explicitly with `--config` or
+`OPCODE_CONFIG`.
+
 ## Multiline Commands
 
 In order to specify multiple commands for a single code, provide the commands

doc/op.1

@@ -10,11 +10,15 @@
 .PD
 \f[B]op\f[R] OPTIONS
 .SH DESCRIPTION
-\f[B]opcode\f[R] lets you define a simple configuration file in any
-directory.
+\f[B]opcode\f[R] lets you define a simple executable command catalog in
+any directory.
 .PP
-This file includes command shortcuts (\f[I]opcodes\f[R]) that can be
-executed by running \f[B]op CODE\f[R].
+It works as a lightweight makefile for humans, AI agents, and any
+workflow that benefits from short, memorable repo\-local commands.
+.PP
+Agents can also run a named command catalog like \f[B]agent check\f[R]
+or \f[B]agent test\f[R], backed by \f[B]agent.op.conf\f[R], without
+mixing generated helper commands into the main \f[B]op.conf\f[R].
 .SH OPTIONS
 .SS ?, \-\-info, \-i
 Show all codes and their usage comments (#?)
@@ -30,6 +34,8 @@ Open the config file for editing
 Append a command to the config file
 .SS \-\-config, \-c FILE CODE [ARGS]
 Use a specific config file
+.SS \-\-syntax
+Show config file syntax
 .SS \-\-help, \-h
 Show help message
 .SS \-\-version, \-v
@@ -69,23 +75,11 @@ You can supply a commit message:
 .EX
 $ op commit \(dqmy commit message\(dq
 .EE
-.SS Config Selection
-Use \f[CR]\-c, \-\-config\f[R] or \f[CR]OPCODE_CONFIG\f[R] to run
-commands from a specific config file:
-.IP
-.EX
-$ op \-c agent.op.conf check
-$ op \-\-config agent.op.conf check
-$ OPCODE_CONFIG=agent.op.conf op check
-.EE
-.PP
-The \f[CR]\-c, \-\-config\f[R] flag must appear before the command code.
-Any \f[CR]\-c\f[R] that appears after the command code is passed through
-to the command as an argument.
-The flag has precedence over \f[CR]OPCODE_CONFIG\f[R].
-.PP
-You can also create another local command namespace by symlinking
-\f[CR]op\f[R] under a different name:
+.SS Named Command Catalogs
+Opcode can provide separate command namespaces by symlinking
+\f[B]op\f[R] under any other executable name.
+This is useful for AI agents, automation, or any workflow that should
+keep its commands separate from the main \f[B]op.conf\f[R]:
 .IP
 .EX
 $ cd /usr/local/bin  # or wherever op is installed
@@ -100,9 +94,18 @@ agent \-> agent.op.conf, agent.conf
 .EE
 .PP
 The \f[CR].op.conf\f[R] file is preferred when both files exist.
-A renamed executable does not fall back to \f[CR]opcode\f[R] or
-\f[CR]op.conf\f[R]; this keeps separately named catalogs from
-accidentally running commands from the main \f[CR]op\f[R] namespace.
+A renamed executable does not fall back to \f[B]opcode\f[R] or
+\f[B]op.conf\f[R]; this keeps separately named catalogs from
+accidentally running commands from the main \f[B]op\f[R] namespace.
+.PP
+This lets agents maintain reusable commands like \f[B]agent check\f[R],
+\f[B]agent test\f[R], or \f[B]agent fix\-ci\f[R] while keeping the
+human\-owned \f[B]op.conf\f[R] focused.
+.PP
+Use \f[B]op \-\-syntax\f[R] or \f[B]agent \-\-syntax\f[R] for a compact
+summary of the config file format.
+Config files can also be selected explicitly with \f[B]\-\-config\f[R]
+or \f[B]OPCODE_CONFIG\f[R].
 .SS Multiline Commands
 In order to specify multiple commands for a single code, provide the
 commands indented with one or more spaces immediately under the command

doc/op.md

@@ -16,10 +16,14 @@ SYNOPSIS
 DESCRIPTION
 ==================================================
 
-**opcode** lets you define a simple configuration file in any directory.
+**opcode** lets you define a simple executable command catalog in any directory.
 
-This file includes command shortcuts (*opcodes*) that can be executed by
-running **op CODE**.
+It works as a lightweight makefile for humans, AI agents, and any workflow that
+benefits from short, memorable repo-local commands.
+
+Agents can also run a named command catalog like **agent check** or
+**agent test**, backed by **agent.op.conf**, without mixing generated helper
+commands into the main **op.conf**.
 
 OPTIONS
 ==================================================
@@ -45,6 +49,9 @@ Append a command to the config file
 ## --config, -c FILE CODE [ARGS]
 Use a specific config file
 
+## --syntax
+Show config file syntax
+
 ## --help, -h
 Show help message
 
@@ -89,23 +96,11 @@ You can supply a commit message:
 $ op commit "my commit message"
 ```
 
-### Config Selection
+### Named Command Catalogs
 
-Use `-c, --config` or `OPCODE_CONFIG` to run commands from a specific config
-file:
-
-```shell
-$ op -c agent.op.conf check
-$ op --config agent.op.conf check
-$ OPCODE_CONFIG=agent.op.conf op check
-```
-
-The `-c, --config` flag must appear before the command code. Any `-c` that
-appears after the command code is passed through to the command as an argument.
-The flag has precedence over `OPCODE_CONFIG`.
-
-You can also create another local command namespace by symlinking `op` under a
-different name:
+Opcode can provide separate command namespaces by symlinking **op** under any
+other executable name. This is useful for AI agents, automation, or any workflow
+that should keep its commands separate from the main **op.conf**:
 
 ```shell
 $ cd /usr/local/bin  # or wherever op is installed
@@ -120,8 +115,15 @@ agent -> agent.op.conf, agent.conf
 ```
 
 The `.op.conf` file is preferred when both files exist. A renamed executable
-does not fall back to `opcode` or `op.conf`; this keeps separately named
-catalogs from accidentally running commands from the main `op` namespace.
+does not fall back to **opcode** or **op.conf**; this keeps separately named
+catalogs from accidentally running commands from the main **op** namespace.
+
+This lets agents maintain reusable commands like **agent check**, **agent test**,
+or **agent fix-ci** while keeping the human-owned **op.conf** focused.
+
+Use **op --syntax** or **agent --syntax** for a compact summary of the config
+file format. Config files can also be selected explicitly with **--config** or
+**OPCODE_CONFIG**.
 
 ### Multiline Commands
 

op

@@ -54,6 +54,11 @@ opcode_context() {
       printf "    Use a specific config file\n\n"
     fi
 
+    printf "  %s --syntax\n" "$PROGRAM_NAME"
+    if [[ $long_usage == 1 ]]; then
+      printf "    Show config file syntax\n\n"
+    fi
+
     printf "  %s -h, --help\n" "$PROGRAM_NAME"
     if [[ $long_usage == 1 ]]; then
       printf "    Show this message\n\n"
@@ -241,6 +246,57 @@ opcode_context() {
     cat "$CONFIG_FILE"
   }
 
+  show_syntax() {
+    cat <<EOF
+Opcode config syntax
+
+Each command is CODE: SCRIPT
+
+  test: npm test
+  check: shellcheck op setup
+
+Run with:
+
+  $PROGRAM_NAME test
+  $PROGRAM_NAME check
+
+Arguments passed after the code are available to the script as "\$@", "\$1", "\$2", ...
+
+  greet: echo "hello \$1"
+  commit: git commit -am "\$@"
+
+Multiline commands are indented below the code:
+
+  up:
+    docker compose build
+    docker compose up web
+
+Usage comments appear in \`$PROGRAM_NAME ?\`. Put them after their command.
+Repeat #? lines for multiline comments:
+
+  test: npm test
+  #? Run tests
+  #? Use before opening a pull request
+
+Headers appear in \`$PROGRAM_NAME ?\`:
+
+  ## Testing
+
+Private commands are hidden from \`$PROGRAM_NAME ?\` and \`$PROGRAM_NAME --list\`
+after a line containing:
+
+  private
+
+Command codes may contain letters, digits, underscores, dots, and dashes.
+
+Config files:
+
+  op uses: opcode, op.conf
+  renamed executable uses: <name>.op.conf, <name>.conf
+  explicit config: $PROGRAM_NAME -c FILE CODE
+EOF
+  }
+
   what_command() {
     local code="$1"
     local script
@@ -324,6 +380,7 @@ opcode_context() {
       -a | --add) add_command "${@:2}" ;;
       -h | --help) usage 'long' ;;
       -v | --version) echo "$VERSION" ;;
+      --syntax) show_syntax ;;
       --completion) send_completion ;;
       *) run_command "$@" ;;
     esac

test/approvals/op_syntax

@@ -0,0 +1,46 @@
+Opcode config syntax
+
+Each command is CODE: SCRIPT
+
+  test: npm test
+  check: shellcheck op setup
+
+Run with:
+
+  op test
+  op check
+
+Arguments passed after the code are available to the script as "$@", "$1", "$2", ...
+
+  greet: echo "hello $1"
+  commit: git commit -am "$@"
+
+Multiline commands are indented below the code:
+
+  up:
+    docker compose build
+    docker compose up web
+
+Usage comments appear in `op ?`. Put them after their command.
+Repeat #? lines for multiline comments:
+
+  test: npm test
+  #? Run tests
+  #? Use before opening a pull request
+
+Headers appear in `op ?`:
+
+  ## Testing
+
+Private commands are hidden from `op ?` and `op --list`
+after a line containing:
+
+  private
+
+Command codes may contain letters, digits, underscores, dots, and dashes.
+
+Config files:
+
+  op uses: opcode, op.conf
+  renamed executable uses: <name>.op.conf, <name>.conf
+  explicit config: op -c FILE CODE

test/fixtures/empty-dir/approvals/op

@@ -7,5 +7,6 @@ Usage:
   op -e, --edit
   op -a, --add CODE COMMAND...
   op -c, --config FILE CODE [ARGS]
+  op --syntax
   op -h, --help
   op -v, --version

test/fixtures/empty-dir/approvals/op_add

@@ -8,5 +8,6 @@ Usage:
   op -e, --edit
   op -a, --add CODE COMMAND...
   op -c, --config FILE CODE [ARGS]
+  op --syntax
   op -h, --help
   op -v, --version

test/fixtures/empty-dir/approvals/op_help

@@ -26,6 +26,9 @@ Usage:
   op -c, --config FILE CODE [ARGS]
     Use a specific config file
 
+  op --syntax
+    Show config file syntax
+
   op -h, --help
     Show this message
 

test/syntax_spec.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+source 'approvals.bash'
+
+describe "op --syntax"
+  approve "op --syntax"