madt_init is undiscoverable: no `init` help topic, only mentioned in passing under madt_remote_add #371

New issue

Closed

opened 2026-08-05 02:55:53 +00:00 by hexajon · 0 comments

hexajon commented

2026-08-05 02:55:53 +00:00

(Migrated from codeberg.org)

Bootstrapping a new repo from an existing directory of files (no git history yet) should be a one- or two-lookup answer. Instead, finding that madt_init is the primitive takes far more help queries than it should - half a dozen in my case.

The discoverability gaps:

help(topic="init") returns "Unknown topic". init is the obvious first guess, and it is not a topic.
help(topic="repos") documents repos action=create, which creates a remote repo but does not push an existing local directory, and nothing there points to madt_init.
help(topic="cli-setup"), the natural place to look for setup/bootstrap, lists api_call / auth_login / auth_use_ssh / auth_whoami / enable / help / open, but not madt_init.
madt_init only surfaces incidentally, inside madt_remote_add's description ("For bootstrapping a brand-new project from scratch - a directory with no commits - use madt_init instead"), reachable only via the cli-git topic.

Net: the one tool that answers "turn this directory of files into a new repo and push it" is the hardest one to find.

Suggested fixes:

Add an init help topic documenting madt_init end to end, and list it among the topics (an alias like bootstrap / new-repo would help the search).
Cross-reference madt_init from the repos (create action) and cli-git / cli-setup topics.
List madt_init in the cli-setup tool group, since that is where someone looks for "how do I initialize/bootstrap a repo".

Bootstrapping a new repo from an existing directory of files (no git history yet) should be a one- or two-lookup answer. Instead, finding that `madt_init` is the primitive takes far more help queries than it should - half a dozen in my case. The discoverability gaps: - `help(topic="init")` returns "Unknown topic". `init` is the obvious first guess, and it is not a topic. - `help(topic="repos")` documents `repos action=create`, which creates a remote repo but does not push an existing local directory, and nothing there points to `madt_init`. - `help(topic="cli-setup")`, the natural place to look for setup/bootstrap, lists api_call / auth_login / auth_use_ssh / auth_whoami / enable / help / open, but not `madt_init`. - `madt_init` only surfaces incidentally, inside `madt_remote_add`'s description ("For bootstrapping a brand-new project from scratch - a directory with no commits - use madt_init instead"), reachable only via the `cli-git` topic. Net: the one tool that answers "turn this directory of files into a new repo and push it" is the hardest one to find. Suggested fixes: - Add an `init` help topic documenting `madt_init` end to end, and list it among the topics (an alias like `bootstrap` / `new-repo` would help the search). - Cross-reference `madt_init` from the `repos` (create action) and `cli-git` / `cli-setup` topics. - List `madt_init` in the `cli-setup` tool group, since that is where someone looks for "how do I initialize/bootstrap a repo".