From 28f5a108d81483dd4e155a5c97ec84c25637a526 Mon Sep 17 00:00:00 2001
From: John Alanbrook <john@pockle.world>
Date: Wed, 18 Feb 2026 12:00:46 -0600
Subject: [PATCH] improved help

---
 bench.ce    |   2 +
 dump_ir.ce  |   2 +
 fold.ce     |   2 +
 help.ce     | 150 ++++++++++++++++++++++++++++++++++++----------------
 parse.ce    |   2 +
 qbe.ce      |   2 +
 qopconv.ce  |   2 +
 test.ce     |   2 +
 tokenize.ce |   2 +
 upgrade.ce  |   2 +
 version.ce  |   2 +
 why.ce      |   2 +
 12 files changed, 125 insertions(+), 47 deletions(-)

diff --git a/bench.ce b/bench.ce
index 464193b5..beae45f4 100644
--- a/bench.ce
+++ b/bench.ce
@@ -1,3 +1,5 @@
+// cell bench - Run benchmarks with statistical analysis
+
 var shop = use('internal/shop')
 var pkg = use('package')
 var fd = use('fd')
diff --git a/dump_ir.ce b/dump_ir.ce
index c54ee2bb..de7a537d 100644
--- a/dump_ir.ce
+++ b/dump_ir.ce
@@ -1,3 +1,5 @@
+// cell dump_ir - Dump intermediate representation for a source file
+
 var shop = use('internal/shop')
 var json = use('json')
 
diff --git a/fold.ce b/fold.ce
index 5839883c..d1bd5cf5 100644
--- a/fold.ce
+++ b/fold.ce
@@ -1,3 +1,5 @@
+// cell fold - Run constant folding on a source file
+
 var json = use("json")
 var shop = use("internal/shop")
 var filename = args[0]
diff --git a/help.ce b/help.ce
index f950c6ea..89cff72c 100644
--- a/help.ce
+++ b/help.ce
@@ -1,11 +1,28 @@
 // cell help - Display help information for cell commands
 
 var fd = use('fd')
+var package = use('package')
+var shop = use('internal/shop')
 
 var command = length(args) > 0 ? args[0] : null
+var core_dir = shop.get_package_dir('core')
 var man_file = null
 var stat = null
 var content = null
+var lines = null
+var line = null
+var block = null
+var ce_path = null
+var i = 0
+var programs = null
+var top_level = []
+var descriptions = []
+var max_len = 0
+var first_line = null
+var desc = null
+var sep = null
+var padding = null
+var j = 0
 
 // Display specific command help
 if (command) {
@@ -15,56 +32,95 @@ if (command) {
     content = text(fd.slurp(man_file))
     log.console(content)
   } else {
-    log.error("No help available for command: " + command)
-    log.console("Run 'cell help' to see available commands.")
+    ce_path = core_dir + '/' + command + '.ce'
+    stat = fd.stat(ce_path)
+    if (stat && stat.isFile) {
+      content = text(fd.slurp(ce_path))
+      lines = array(content, '\n')
+      block = ""
+      for (i = 0; i < length(lines); i++) {
+        line = lines[i]
+        if (starts_with(line, '// ')) {
+          block = block + text(line, 3, length(line)) + '\n'
+        } else if (line == '//') {
+          block = block + '\n'
+        } else if (starts_with(line, '//')) {
+          block = block + text(line, 2, length(line)) + '\n'
+        } else {
+          i = length(lines)
+        }
+      }
+      if (length(block) > 0) {
+        log.console(trim(block))
+      } else {
+        log.error("No help available for command: " + command)
+        log.console("Run 'cell help' to see available commands.")
+      }
+    } else {
+      log.error("No help available for command: " + command)
+      log.console("Run 'cell help' to see available commands.")
+    }
+  }
+} else {
+// Display general help — dynamic listing
+programs = sort(package.list_programs('core'))
+for (i = 0; i < length(programs); i++) {
+  if (search(programs[i], '/') == null) {
+    top_level[] = programs[i]
   }
-  $stop()
 }
 
-// Display general help
-man_file = 'scripts/man/cell.man'
-stat = fd.stat(man_file)
-if (stat && stat.isFile) {
-  content = text(fd.slurp(man_file))
-  log.console(content)
-} else {
-  // Fallback if man file doesn't exist
-  log.console("cell - The Cell package manager")
-  log.console("")
-  log.console("Usage: cell <command> [arguments]")
-  log.console("")
-  log.console("Package Management:")
-  log.console("  install <locator>   Install a package and its dependencies")
-  log.console("  update [locator]    Update packages from remote sources")
-  log.console("  remove <locator>    Remove a package from the shop")
-  log.console("  add <locator>       Add a dependency to current package")
-  log.console("")
-  log.console("Building:")
-  log.console("  build [locator]     Build dynamic libraries for packages")
-  log.console("  clean [scope]       Remove build artifacts")
-  log.console("")
-  log.console("Linking (Local Development):")
-  log.console("  link <origin> <target>  Link a package to a local path")
-  log.console("  unlink <origin>         Remove a package link")
-  log.console("  clone <origin> <path>   Clone and link a package locally")
-  log.console("")
-  log.console("Information:")
-  log.console("  list [scope]        List packages and dependencies")
-  log.console("  ls [locator]        List modules and actors in a package")
-  log.console("  why <locator>       Show reverse dependencies")
-  log.console("  search <query>      Search for packages, modules, or actors")
-  log.console("")
-  log.console("Diagnostics:")
-  log.console("  resolve [locator]   Print fully resolved dependency closure")
-  log.console("  graph [locator]     Emit dependency graph (tree, dot, json)")
-  log.console("  verify [scope]      Verify integrity and consistency")
-  log.console("  audit [locator]     Test-compile all scripts in package(s)")
-  log.console("")
-  log.console("Other:")
-  log.console("  help [command]      Show help for a command")
-  log.console("  version             Show cell version")
-  log.console("")
-  log.console("Run 'cell <command> --help' for more information on a command.")
+for (i = 0; i < length(top_level); i++) {
+  ce_path = core_dir + '/' + top_level[i] + '.ce'
+  desc = ""
+  stat = fd.stat(ce_path)
+  if (stat && stat.isFile) {
+    content = text(fd.slurp(ce_path))
+    lines = array(content, '\n')
+    first_line = length(lines) > 0 ? lines[0] : ""
+    if (starts_with(first_line, '//')) {
+      if (starts_with(first_line, '// ')) {
+        first_line = text(first_line, 3, length(first_line))
+      } else {
+        first_line = text(first_line, 2, length(first_line))
+      }
+      sep = search(first_line, ' - ')
+      if (sep != null) {
+        desc = text(first_line, sep + 3, length(first_line))
+      } else {
+        sep = search(first_line, ' — ')
+        if (sep != null) {
+          desc = text(first_line, sep + 3, length(first_line))
+        } else {
+          desc = first_line
+        }
+      }
+    }
+  }
+  descriptions[] = desc
+  if (length(top_level[i]) > max_len) {
+    max_len = length(top_level[i])
+  }
+}
+
+log.console("cell - the cell package manager")
+log.console("")
+log.console("usage: cell <command> [arguments]")
+log.console("")
+log.console("available commands:")
+for (i = 0; i < length(top_level); i++) {
+  padding = ""
+  for (j = 0; j < max_len - length(top_level[i]); j++) {
+    padding = padding + " "
+  }
+  if (length(descriptions[i]) > 0) {
+    log.console("  " + top_level[i] + padding + "   " + descriptions[i])
+  } else {
+    log.console("  " + top_level[i])
+  }
+}
+log.console("")
+log.console("Run 'cell help <command>' for more information.")
 }
 
 $stop()
diff --git a/parse.ce b/parse.ce
index 242b7b2c..cb29c4d2 100644
--- a/parse.ce
+++ b/parse.ce
@@ -1,3 +1,5 @@
+// cell parse - Parse a source file and output AST as JSON
+
 var json = use("json")
 var shop = use("internal/shop")
 var filename = args[0]
diff --git a/qbe.ce b/qbe.ce
index 4e3d08cd..5521a1b6 100644
--- a/qbe.ce
+++ b/qbe.ce
@@ -1,3 +1,5 @@
+// cell qbe - Compile a source file to QBE intermediate language
+
 var fd = use("fd")
 var json = use("json")
 var tokenize = use("tokenize")
diff --git a/qopconv.ce b/qopconv.ce
index 9a3a010d..151fcf18 100644
--- a/qopconv.ce
+++ b/qopconv.ce
@@ -1,3 +1,5 @@
+// cell qopconv - Convert QOP archive formats
+
 var fd = use('fd')
 var qop = use('qop')
 
diff --git a/test.ce b/test.ce
index 613776db..16112456 100644
--- a/test.ce
+++ b/test.ce
@@ -1,3 +1,5 @@
+// cell test - Run tests for packages
+
 var shop = use('internal/shop')
 var pkg = use('package')
 var fd = use('fd')
diff --git a/tokenize.ce b/tokenize.ce
index 8ac001e4..875e5e5b 100644
--- a/tokenize.ce
+++ b/tokenize.ce
@@ -1,3 +1,5 @@
+// cell tokenize - Tokenize a source file and output token stream
+
 var json = use("json")
 var shop = use("internal/shop")
 var filename = args[0]
diff --git a/upgrade.ce b/upgrade.ce
index 48bdf98d..c0dad379 100644
--- a/upgrade.ce
+++ b/upgrade.ce
@@ -1,3 +1,5 @@
+// cell upgrade - Upgrade the cell installation
+
 var shop = use('internal/shop')
 var fd = use('fd')
 
diff --git a/version.ce b/version.ce
index 4aa40cdc..579a10fa 100644
--- a/version.ce
+++ b/version.ce
@@ -1,2 +1,4 @@
+// cell version - Show cell version
+
 log.console("0.1.0")
 $stop()
\ No newline at end of file
diff --git a/why.ce b/why.ce
index a16b169f..c84032f9 100644
--- a/why.ce
+++ b/why.ce
@@ -1,3 +1,5 @@
+// cell why - Show reverse dependencies for a package
+
 var shop = use('internal/shop')
 var pkg = use('package')