docs: complete reference for pak architecture, capabilities and limits

[lepht]

Documentation only — no code changes.

PAKS.md was inherited from upstream as an emulator-pak authoring tutorial. It used $BIOS_PATH, $CORES_PATH and $LOGS_PATH in its examples without ever defining them, gave tool paks a single sentence, and never described the execution model — which is what actually explains most of what paks can and cannot do. HOOKS.md was in better shape but had several claims that don't match run_hooks.sh.

PAKS.md

Expanded into a full reference. New material:

• The launch model, up front. The launcher writes /tmp/next, sets its quit flag and terminates; the shell loop in MinUI.pak/launch.sh runs the pak and re-execs the launcher afterward. Includes the consequence that a pak cannot chain-launch through /tmp/next, since the loop does rm -f $NEXT_PATH after eval $CMD returns — the emulator has to be exec'd directly.
• Complete environment variable table, plus two gotchas: HOME is not exported on desktop, and DEVICE is only set on tg5050 when the model string matches, so it can legitimately be empty.
• Tool paks — example and visibility rules from hide(): dot-prefix, .disabled suffix, map.txt. The .disabled convention is how Remove Loading.pak self-uninstalls but wasn't written down anywhere.
• Emulator resolution order. getEmuPath() checks /Emus/<platform>/ before the built-in pak, so a user pak overrides a built-in of the same tag. That's the supported way to customize a stock emulator without touching .system/, and it was undocumented.
• Capabilities — bundled helper binaries, settings via minuisettings.txt / nextval.elf, drop-in assets, and the hardcoded Settings / Pak Store / FN-button integrations.
• An explicit "what paks cannot do" section, covering why anything that needs to live inside the menu requires patching nextui.c.
• Lifecycle — the .system wiped / .userdata persists asymmetry and the orphaned-file problem that follows from it.
• Debugging and platform/pixel-format caveats.

Also default-<device>.cfg precedence over default.cfg, and the - option prefix that sets a value and hides it, both of which were only visible in the source.

HOOKS.md

Four corrections against the implementation:

1. "Scripts run in alphabetical order" was misleading. They are started in glob order but backgrounded, so they run concurrently. Only *.sync.sh files are ordered — a suffix the doc never mentioned, along with --sync-only.
2. HOOK_CATEGORY was undocumented despite being exported by run_hooks.sh. This matters because HOOK_PHASE does not identify the event — it's derived from the directory prefix, so pre-launch.d and pre-sleep.d both report pre. HOOK_CATEGORY is the only disambiguator.
3. The HOOK_CMD / HOOK_TYPE / HOOK_EMU_PATH / HOOK_ROM_PATH / HOOK_LAST variables are set only for the launch phases. They're populated by parse_hook_cmd() on the launch path, so they are unset in boot.d, pre-sleep.d and post-resume.d. The table presented them as universal.
4. Backgrounding does not make a slow hook free, because the runner waits on everything before returning. The doc said "keep hooks fast" without the reason, which read as advice rather than a constraint.

Added: sleep hooks never fire on desktop (no bin/suspend); pre-sleep.d runs with wifi and bluetooth still up while post-resume.d runs before they're restarted; hook installation guidance, since hooks live in .userdata/ and survive both updates and pak deletion with nothing running on uninstall to clean them up.

Naming

Second commit renames OS references to nexterUI so these docs don't stay on the old name once #3 merges. "NextUI" is kept in the four places it's still correct:

• a compatibility note up top — nexterUI keeps the pak format unchanged, so paks built for NextUI work here as-is and this document applies to both, matching the framing in docs: rebrand to nexterUI and document why this fork exists #3's README
• IS_NEXT, which is set by both, so it detects the lineage rather than the fork — nothing in the environment separates the two
• the third-party support caveat, which is equally true of upstream and MinUI

A # NextUI-only features code comment became # not available on stock MinUI, which is what the IS_NEXT guard actually means.

Conflicts

None. Test-merged clean against all three open PR heads both before and after the rename; none of them touch PAKS.md or HOOKS.md. Based on main rather than stacked on the others, since it's independent of all of them and shouldn't have to wait on the chain.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Hu2BibaMPDtFk7S3NYywZE