[geoffreycastillo]

Follow-up to mrpg/uproot#285. This documents buddy_sender and the whole of TEMPLATE_DEFAULTS.

Deploy this only after the next uproot release. buddy_sender is not in 0.11.0, so the example in admin.md stops the server on that version with Invalid TEMPLATE_DEFAULTS.

Changes

• building/pages.md
  • New section, “Changing a switch for the whole project”: covers upd.TEMPLATE_DEFAULTS, which value wins, the three buddy_* switches, and the startup check.
  • Adds the missing disable_alpinejs row to the switches table, and clarifies a few other rows.
  • Adds a warning about disable_auto_start and disable_bootstrap.
  • The translations section now says that you can replace uproot's wording in any language, including English.
• running/admin.md
  • New section, “Changing how the experimenter appears”: covers buddy_label, buddy_sender and buddy_image, plus the translation route for multilingual studies, as you suggested in the issue.
  • Fixes the chat button position: it is bottom-left, not bottom-right.
• building/alpinejs.md: short “Disabling Alpine.js” section.
• getting-started/project-structure.md: short “Template defaults” entry under main.py.
• AGENTS.md
  • Updates the template notes.
  • Adds a line saying that disable_auto_start and disable_bootstrap are effectively internal. I added it because my coding agent kept wanting to document their pitfalls and explain how to rescue a study after disabling them, when disabling them is clearly just a very bad idea. The line tells future agents to warn against these switches rather than document workarounds.

Question for you

Are disable_auto_start and disable_bootstrap strictly internal? Is there a legitimate reason for a user to disable them?

Disabling either one breaks a lot:

• disable_auto_start: Next silently stops working on experiment pages, and so do live methods and chat. Set project-wide, participants never reach the first page. The only uses I found are uproot's own RoomFull, RoomHello and JustPOST pages.
• disable_bootstrap: the modal text is visible on every page, pop-ups do not open, and sliders with a popover throw a JavaScript error. I found no use of it in the code, tests, examples or issues.

To me, these look like internal switches, and I think the docs should label them as such. For now, the docs only warn against them. If you agree, I can update this PR to say so. If there is a legitimate use case, I can document that instead and adjust the AGENTS.md line.

Testing

I checked the behaviour described here on a test project running uproot main, using Chrome. This covered which value wins, buddy_image, the startup check, the English and German translation example, and the main things the two risky switches break. I also sent a real admin chat message with buddy_label and buddy_sender set, and the new text appeared on both the admin and participant sides. The site builds with mkdocs build --strict, and I checked the internal links on the changed pages, including anchors.