Some specific issues:

• adding new stuff breaks if you call too early, such as from a gadget that's loaded before wikiEditor is (Roan says it needs to buffer up calls before it's fully init'ed; can work around by binding wikiEditor-toolbar-buildSection-main on wpTextbox1)
• no clean way to modify existing things
• lacks clear canonical documentation on data formats (such as what are available types, whether an icon must be specified, etc)

I swear I put content in this bug, it got lost somehow.

Brion's summed it up pretty well. The main issue with timing is that it currently matters whether you call the [addTo|removeFrom]Toolbar() functions before or after the toolbar has been built, and that's bad.

mhershberger wrote:

Unassigning default assignments. http://article.gmane.org/gmane.science.linguistics.wikipedia.technical/54734

beau wrote:

I am rising importance of this bug, since it is now almost impossible to add a toolbar button in a sane way with async script loading.

In T30563#324066, @Catrope wrote:

Brion's summed it up pretty well. The main issue with timing is that it currently matters whether you call the
[addTo|removeFrom]Toolbar() functions before or after the toolbar has been built, and that's bad.

Things today are not much different -- the folks who are not adding to the 'Christmas tree of toolbars' as the pre-ordained sections go by & get built, but ''patiently'' wait until its done 'doing its thang' -- only to begin pruning soon afterwards -- are still frustrated like this.

And I've always wondered what they mean on wiedi's extension: page, under the == Modifying things == section in...

We don't really have a nice API to modify things, unfortunately. The best we have is a hook to change the configuration of a section just before it's being built:

$( '#wpTextbox1' ).on( 'wikiEditor-toolbar-doneInitialSections', function () {
    // Do something
} );

... and goes on to give an example of Adding to existing sets or section groups; nothing about preventing or bypassing any unwanted bits & pieces prior to their inclusion for at least the rest of your session.

I get the distinct impression that same hook provides a way to [de]select unwanted base modules and the like from ever loading again unless the User: alters it back that way again.

Any basis in reality for something like that being possible but just went undocumented or something?

We need simply a hook event. The trigger "wikiEditor-toolbar-doneInitialSections" is not suitable (which leads to such fixes rEVED889358f24c20dd326be341f170479334c136021a) also mentioned in T23692#260234 by @Mattflaschen-WMF

As different browsers are loading scripts more and more (randomly) synchronically, the afterward customization of the toolbar is only luck or needs an extensive hackish code. Which are my personal experiences with different scripts. As @He7d3r asked @Krinkle to this issue on https://www.mediawiki.org/wiki/Extension_talk:WikiEditor/Toolbar_customization#Custom_buttons_don't_always_show_up_in_the_editor_window
I used awhile an intern hook (now removed: 'resourceloader.loadEnd') which worked perfectly. So please create a new one.

The only sure workaround seems to try load twice (at the very end per window.onload), as shown in https://commons.wikimedia.org/wiki/MediaWiki:Edittools.js

Wikieditor now provides a decent(ish) API for adding new groups, sections, and buttons; which is documented(ish) with examples at mw:WikiEditor/Toolbar_customization. It also provides the mw.hook() event wikiEditor.toolbarReady and wikiEditor-toolbar-doneInitialSections (documented on the same page). The API for removing things and modifying things is certainly not great, but it exists and is documented (ditto).

A better and richer API would be better of course, but maybe this particular task could be closed as "Resolved" now? @Catrope ?