feat(cli): add shorthand error helpers, usage polling on bare box, and comprehensive help manuals

bin/box-work.py

@@ -783,8 +783,113 @@ def cmd_chats(args):
         print(f"[{c_cyan(ag)} : {c_dim(tname)}] {c_dim(ts)} {c_bold(author)}:\n{text}\n" + c_dim("-" * 60))
     print()
 
+WORK_COMMAND_EXAMPLES = {
+    "box work": [
+        "box work                                # View fleet workspace dashboard & signals",
+        "box work check [agent]                  # Audit pre-flight health gates",
+        "box work heal <agent>                   # Automated remediation & chat nudge",
+        "box work start \"<title>\" --to <agent>   # Start & dispatch new build ticket",
+        "box work assign <issue#> --to <agent>   # Assign existing ticket",
+        "box work merge <pr#>                    # Verify tests and merge PR to master",
+        "box work chats --agent <name>           # View live multi-agent chat feed",
+    ],
+    "box work start": [
+        "box work start \"Fix SSH perms\" --to 646",
+        "box work start \"Build integration tests\" --to pip --goal \"Run pytest on endpoints\"",
+        "box work start \"Emergency rebuild\" --to dev --force",
+    ],
+    "box work check": [
+        "box work check                          # Check all agents",
+        "box work check 646                      # Check specific agent",
+    ],
+    "box work heal": [
+        "box work heal dev                       # Heal dev agent (token, perms, tunnel nudge)",
+        "box work heal 646",
+    ],
+    "box work assign": [
+        "box work assign 218 --to 646",
+    ],
+    "box work merge": [
+        "box work merge 217                      # Test and merge PR 217 into master",
+    ],
+    "box work chats": [
+        "box work chats                          # Last 10 chat messages across fleet",
+        "box work chats --agent opm --limit 5",
+    ],
+}
+
+def format_work_error_shorthand(parser, message):
+    lines = []
+    lines.append(f"\n{c_bold(c_red('❌ CLI ERROR:'))} {c_bold(message)}\n")
+    lines.append(c_bold(c_yellow("💡 SHORTHAND USAGE HELPER:")))
+    lines.append(f"  Command: {c_bold(parser.prog)}")
+
+    sub_action = next((a for a in parser._actions if isinstance(a, argparse._SubParsersAction)), None)
+    if sub_action:
+        lines.append(f"\n{c_bold('  Available Subcommands:')}")
+        for name, subp in sub_action.choices.items():
+            h = subp.description or getattr(subp, "help", "") or ""
+            if not h and getattr(sub_action, "_choices_actions", None):
+                for ca in sub_action._choices_actions:
+                    if ca.dest == name:
+                        h = ca.help or ""
+                        break
+            lines.append(f"    • {c_bold(f'{name:<12}')} {c_dim(h)}")
+
+    positionals = [a for a in parser._actions if not a.option_strings and a.dest != 'help' and not isinstance(a, argparse._SubParsersAction)]
+    required_options = [a for a in parser._actions if a.option_strings and a.required and a.dest != 'help']
+    optional_options = [a for a in parser._actions if a.option_strings and not a.required and a.dest != 'help']
+
+    if positionals or required_options:
+        lines.append(f"\n{c_bold('  Required Parameters / Arguments:')}")
+        for a in positionals:
+            lines.append(f"    • {c_bold(f'{a.dest:<14}')} {a.help or '(positional)'}")
+        for a in required_options:
+            opts = "/".join(a.option_strings)
+            lines.append(f"    • {c_bold(f'{opts:<14}')} {a.help or '(required flag)'}")
+
+    if optional_options:
+        lines.append(f"\n{c_bold('  Optional Flags:')}")
+        for a in optional_options:
+            opts = "/".join(a.option_strings)
+            lines.append(f"    • {c_cyan(f'{opts:<14}')} {c_dim(a.help or '')}")
+
+    prog_key = parser.prog.strip()
+    examples = WORK_COMMAND_EXAMPLES.get(prog_key) or WORK_COMMAND_EXAMPLES.get("box work")
+    if examples:
+        lines.append(f"\n{c_bold('  Quick Examples:')}")
+        for ex in examples:
+            lines.append(f"    {c_green(ex)}")
+
+    lines.append(f"\n  📖 {c_dim('For complete manual:')} {c_bold(f'{parser.prog} --help')} {c_dim('(or')} {c_bold(f'box help {parser.prog.split()[-1]}')}{c_dim(')')}\n")
+    return "\n".join(lines)
+
+class WorkArgumentParser(argparse.ArgumentParser):
+    def error(self, message):
+        print(format_work_error_shorthand(self, message), file=sys.stderr)
+        sys.exit(2)
+
+    def format_help(self):
+        base_help = super().format_help()
+        prog_key = self.prog.strip()
+        examples = WORK_COMMAND_EXAMPLES.get(prog_key) or WORK_COMMAND_EXAMPLES.get("box work")
+        extra = []
+        if examples:
+            extra.append(c_bold("\nSHORTHAND EXAMPLES:"))
+            for ex in examples:
+                extra.append(f"  {c_green(ex)}")
+        extra.append(c_bold("\nOPERATIONAL GUIDELINES:"))
+        extra.append(f"  • {c_cyan('Shorthand parameter reference:')} run {c_bold('box')} alone")
+        extra.append(f"  • {c_cyan('Comprehensive manual:')} run {c_bold('box help work')}")
+        extra.append(f"  • {c_cyan('JSON output:')} append {c_bold('--json')} to any query command\n")
+        return base_help + "\n".join(extra)
+
 def main():
-    parser = argparse.ArgumentParser(
+    if len(sys.argv) > 1 and "help" in sys.argv[1:]:
+        idx = sys.argv.index("help")
+        sys.argv[idx] = "--help"
+
+    parser = WorkArgumentParser(
         prog="box work",
         description="Fleet Workspace, Work Scope, and Task Orchestration Engine."
     )

tests/test_box_work.py

@@ -58,5 +58,63 @@ class TestBoxWork(unittest.TestCase):
         self.assertFalse(res["ready"])
         self.assertEqual(res["overall"], "FAIL")
 
+    def test_cli_alone_prints_usage_reference(self):
+        import subprocess
+        proc = subprocess.run([sys.executable, str(REPO_ROOT / "bin" / "super-cli.py")], capture_output=True, text=True)
+        self.assertEqual(proc.returncode, 0)
+        self.assertIn("BOX ORCHESTRATOR: INPUT PARAMETERS & USAGE REFERENCE", proc.stdout)
+        self.assertIn("PRIMARY DOMAINS & INPUT PARAMETERS:", proc.stdout)
+        self.assertIn("box work", proc.stdout)
+        self.assertIn("box tasks", proc.stdout)
+        self.assertIn("box fleet", proc.stdout)
+
+    def test_cli_help_prints_master_manual(self):
+        import subprocess
+        proc = subprocess.run([sys.executable, str(REPO_ROOT / "bin" / "super-cli.py"), "help"], capture_output=True, text=True)
+        self.assertEqual(proc.returncode, 0)
+        self.assertIn("BOX ORCHESTRATOR COMPREHENSIVE CLI & RUNTIME MANUAL", proc.stdout)
+        self.assertIn("DOMAINS & ACTION SPECIFICATIONS:", proc.stdout)
+
+    def test_cli_domain_help_prints_subcommands_and_examples(self):
+        import subprocess
+        proc = subprocess.run([sys.executable, str(REPO_ROOT / "bin" / "super-cli.py"), "work", "help"], capture_output=True, text=True)
+        self.assertEqual(proc.returncode, 0)
+        self.assertIn("SHORTHAND EXAMPLES:", proc.stdout)
+        self.assertIn("OPERATIONAL GUIDELINES:", proc.stdout)
+        self.assertIn("box work start", proc.stdout)
+
+    def test_cli_missing_args_prints_error_and_shorthand_helper(self):
+        import subprocess
+        proc = subprocess.run([sys.executable, str(REPO_ROOT / "bin" / "super-cli.py"), "work", "start"], capture_output=True, text=True)
+        self.assertEqual(proc.returncode, 2)
+        err = proc.stderr
+        self.assertIn("CLI ERROR:", err)
+        self.assertIn("SHORTHAND USAGE HELPER:", err)
+        self.assertIn("title", err)
+        self.assertIn("--to", err)
+        self.assertIn("Quick Examples:", err)
+
+    def test_cli_invalid_subcommand_prints_shorthand_helper(self):
+        import subprocess
+        proc = subprocess.run([sys.executable, str(REPO_ROOT / "bin" / "super-cli.py"), "work", "invalid_action_xyz"], capture_output=True, text=True)
+        self.assertEqual(proc.returncode, 2)
+        err = proc.stderr
+        self.assertIn("CLI ERROR:", err)
+        self.assertIn("SHORTHAND USAGE HELPER:", err)
+        self.assertIn("Available Subcommands:", err)
+        self.assertIn("status", err)
+        self.assertIn("start", err)
+
+    def test_cli_invalid_domain_prints_shorthand_helper(self):
+        import subprocess
+        proc = subprocess.run([sys.executable, str(REPO_ROOT / "bin" / "super-cli.py"), "invalid_domain_xyz"], capture_output=True, text=True)
+        self.assertEqual(proc.returncode, 2)
+        err = proc.stderr
+        self.assertIn("CLI ERROR:", err)
+        self.assertIn("SHORTHAND USAGE HELPER:", err)
+        self.assertIn("Primary Domains & Commands:", err)
+        self.assertIn("work", err)
+        self.assertIn("fleet", err)
+
 if __name__ == "__main__":
     unittest.main()