From b640d13799c3dc98e08b9c9d53b745c4d0d76a3a Mon Sep 17 00:00:00 2001
From: Agando <roduccomm@gmail.com>
Date: Thu, 22 Oct 2026 01:46:42 +0200
Subject: docs(newos4): clear the help.html command backlog, and make it
 detectable

help.html had not been touched since 2026-08-02. Auditing the page against the
code found 74 commands the runtime registers but the docs never mentioned, and
4 rows documenting commands that no longer exist.

Documented (by section): terminal 11 (dashboard --watch/--stop, usage, ps, top,
df, free, history, run, sysmsg, view_module), a2a 6, AI 14 (webxai/webx/wx,
context*/smart-ask, commit-*, ai-model/ai-ignore), vaultmind 4, debug 2, filesystem 2,
sessions 1, memory-graph 3, modules 4, neural-vfs 1, agents 3, web 1, voice 3,
config 3, extras 8 (kanban, three, course, gzip, wget, gui-*), vault 2 (encrypt/decrypt),
skills 5, webdav 1, plus an alias row for h/s/ll.

Removed ghost rows: commands, check, sandbox-kill, webdav-explorer -- none are
registered anywhere in modules/; the sandbox prose no longer promises sandbox-kill.

New check: scripts/newos4-maintain.py check_help_coverage() derives the command
list from terminal.js (_baseWhitelist, internals, cmd === dispatch) plus every
commands['...'] registration in modules/ and compares it with help.html, so the
next gap shows up in the daily maintenance run instead of rotting for 11 weeks.

Verified: html.parser 0 errors (before the fix my own insertion broke the page --
a signature containing <script> opened a script element), 355/355 commands
documented, maintenance OK, 449 command rows in the DOM, 360/390 px 4/4 OK,
perms fixed (atlas.json, course.js were 664).
---
 scripts/newos4-maintain.py | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

(limited to 'scripts/newos4-maintain.py')

diff --git a/scripts/newos4-maintain.py b/scripts/newos4-maintain.py
index 10ac62b..dd6c898 100644
--- a/scripts/newos4-maintain.py
+++ b/scripts/newos4-maintain.py
@@ -100,6 +100,34 @@ def check_course():
     r = run([sys.executable, 'scripts/course-validate.py'], cwd=ROOT)
     add('PASS' if r.returncode == 0 else 'FAIL', 'course ' + ('valid' if r.returncode == 0 else 'INVALID: ' + r.stdout[-160:]))
 
+def check_help_coverage():
+    """Every command the code registers must appear in help.html (2026-10-22).
+
+    help.html had a 74-command backlog because nothing compared the two. This
+    check makes the gap visible on every maintenance run.
+    """
+    cmds, term = set(), open(os.path.join(ROOT, 'modules/core/terminal.js'), encoding='utf-8').read()
+    for m in re.finditer(r'this\._baseWhitelist = \[(.*?)\];', term, re.S):
+        cmds.update(re.findall(r"'([^']+)'", m.group(1)))
+    for m in re.finditer(r'const internals = \[(.*?)\];', term, re.S):
+        cmds.update(re.findall(r"'([^']+)'", m.group(1)))
+    cmds.update(re.findall(r"cmd === ['\"]([a-z0-9_-]+)['\"]", term))
+    for p in glob.glob(os.path.join(ROOT, 'modules/**/*.js'), recursive=True):
+        if 'bundle' in p or '/test/' in p or '.bkp' in p:
+            continue
+        src = open(p, encoding='utf-8', errors='ignore').read()
+        cmds.update(re.findall(r"commands\[['\"]([a-z0-9_-]+)['\"]\]\s*=", src))
+    doc = open(os.path.join(ROOT, 'help.html'), encoding='utf-8').read()
+    documented = set()
+    for tok in re.findall(r'<code>([^<]+)</code>', doc):
+        first = tok.replace('&lt;', ' ').replace('&gt;', ' ').split()
+        if first and re.fullmatch(r'[a-z][a-z0-9_-]{0,40}', first[0].lstrip('./')):
+            documented.add(first[0].lstrip('./'))
+    missing = sorted(cmds - documented)
+    add('PASS' if not missing else 'WARN',
+        f'help coverage {len(cmds) - len(missing)}/{len(cmds)} commands'
+        + ('' if not missing else f' — undocumented: {", ".join(missing[:8])}'))
+
 def check_links():
     if not DEEP: return
     broken = []
@@ -115,7 +143,7 @@ def check_links():
 
 def main():
     os.chdir(ROOT)
-    check_versions(); check_bundles(); check_syntax(); check_perms(); check_index(); check_data(); check_live(); check_atlas(); check_course(); check_links()
+    check_versions(); check_bundles(); check_syntax(); check_perms(); check_index(); check_data(); check_live(); check_atlas(); check_course(); check_help_coverage(); check_links()
     fails = [m for l, m in issues if l == 'FAIL']
     print('newOS4 maintenance — ' + datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%MZ') + (' [fix]' if FIX else '') + (' [deep]' if DEEP else ''))
     for l, m in issues: print(f'{l}: {m}')
-- 
cgit v1.2.3