docs: generate an HTTP API listing for the hub and the node control API

docs/MESHBAY_HTTP_API.md lists every route of the hub (by domain, with the
authentication each requires) and of the node's loopback control API. It is
written by docs/generate_http_api.py from the routes and their docstrings;
test_http_api_doc.py fails when the file drifts from the code or when a
route has no docstring, so a new route must say what it does.

79 routes had no docstring and get a one-line description; a few whose first
line did not describe the route get a summary line.

The login page's developer docs gain an API link next to Design and
Protocol, in every language. README, MESHBAY_DESIGN.md (§0.1, §6.7, §7) and
CLAUDE.md point to the listing; README also points to examples/.

The examples scripts with a shebang become executable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 7 insertions, 0 deletions

diff --git a/packages/meshbay-hub/src/meshbay_hub/api/admin.py b/packages/meshbay-hub/src/meshbay_hub/api/admin.py
index dbda197..1cb8bf9 100644
--- a/packages/meshbay-hub/src/meshbay_hub/api/admin.py
+++ b/packages/meshbay-hub/src/meshbay_hub/api/admin.py
@@ -213,6 +213,7 @@ async def admin_stats(
     current_user: User = Depends(require_moderator),
     db: AsyncSession = Depends(get_db),
 ):
+    """Account, group and node counts."""
     # Deleted accounts are tombstoned rather than dropped, so that the
     # connection log stays readable. They are not users any more and must not be
     # counted as any: a hub whose user count only ever rises is measuring its
@@ -244,6 +245,7 @@ async def admin_list_users(
     offset: int = 0,
     limit: int = Query(default=50, le=200),
 ):
+    """Search and list accounts."""
     query = (select(User).where(User.status != "deleted")
              .order_by(User.created_at.desc()))
     if q:
@@ -279,6 +281,7 @@ async def admin_get_user(
     current_user: User = Depends(require_moderator),
     db: AsyncSession = Depends(get_db),
 ):
+    """One account, with its group count."""
     user = await db.get(User, user_id)
     if not user:
         raise HTTPException(status_code=404, detail="User not found")
@@ -310,6 +313,7 @@ async def admin_patch_user(
     current_user: User = Depends(require_moderator),
     db: AsyncSession = Depends(get_db),
 ):
+    """Change an account's status, or its role (admin only)."""
     user = await db.get(User, user_id)
     if not user:
         raise HTTPException(status_code=404, detail="User not found")
@@ -473,6 +477,7 @@ async def admin_list_groups(
     offset: int = 0,
     limit: int = Query(default=50, le=200),
 ):
+    """List groups with their member counts."""
     query = (
         select(
             Group,
@@ -524,6 +529,7 @@ async def admin_patch_group(
     current_user: User = Depends(require_moderator),
     db: AsyncSession = Depends(get_db),
 ):
+    """Change a group's status."""
     group = await db.get(Group, group_id)
     if not group:
         raise HTTPException(status_code=404, detail="Group not found")
@@ -624,6 +630,7 @@ async def admin_list_logs(
     offset: int = 0,
     limit: int = Query(default=50, le=200),
 ):
+    """The connection log, filtered by account and event."""
     query = (
         select(IPLog, User.username)
         .outerjoin(User, IPLog.user_id == User.id)