Plugin id and friendly name (M5 part 3a-0)

[txoof-bot]

Part of #238

What changed

Each [[plugin]] block now has a fixed id and an optional friendly name (agreed with txoof 2026-10-08; v2 does not read v1 configs, global decision, migration tool = #248).

• id: required, unique (capitals don't count, - is the same as _), only letters, digits, _ and -, at most 40, at least one letter or digit. It names the plugin's storage folder, the log lines and paperpi render --config … --id. IDs starting with built-in are kept for PaperPi's own plugins (fallback clock, default, splash), so they always have their own folder.
• name: what the web interface shows, any text up to 100 characters (no control characters, no invisible text-direction characters), not unique, can change at any time. Empty: the id is shown.
• Plugin Library: the add page asks only for the friendly name (may be empty) and makes the id: the type and 8 random hex characters, e.g. met_no-3f9a1c2e.
• Active Plugins shows the name, and type · id when the id differs, so two plugins with the same name can be told apart. Forms send the id.
• paperpi list has an id column and a name column. paperpi render --config takes --id (was --name).
• Example config, README, plugin READMEs and design notes (config-format.md, web-interface.md, plugin-interface.md, errors-and-time-limits.md) updated.

Choices made without asking:

• PaperPi never adds a missing id to a block by itself; a block without one is an error.
• paperpi render --id matches IDs the same way the uniqueness check does (--id clock finds id = "Clock").
• The fallback plugins' IDs are built-in-default, built-in-clock and built-in-splash, so their storage folders keep their names.

Size: +578/−335 (about 900 lines), a bit over the guideline. Most of it is the mechanical rename name → id in tests and docs. The next parts (3a-1 form logic, 3a-2 settings page) will be stacked on this branch.

Area

core (plugin.py PluginEntry, config.py, scheduler.py, cli.py, example.py), web (src/paperpi/web/), plugin READMEs, docs, paperpi.example.toml. No other open PR changes config.py, plugin.py, pyproject.toml or uv.lock.

Tests

New tests: id rules (length, empty, only _/-, - same as _, built-in kept), lookup by id, a name of only spaces shows the id, hidden direction characters refused, the Library makes a new id / never one in use / one that fits for a long type, empty or repeated names. Existing tests changed from name to id.

• uv run pytest passes (1323 on the Pi, 4 cores)
• uv run ruff check . passes
• Hardware tests run on the Pi (only if display or driver code changed): not needed

Review

• Review agents' comments answered: 2 local reviews (code + tests, security + docs) ran before the first push; every finding is fixed in the second commit (no security problems found).

Only txoof approves and merges this PR.

🤖 Generated with Claude Code