docs/lua-api.md (new, 380 lines):
- Section 1-2: Why Lua + file location (owlry.lua, NOT init.lua per D23)
- Section 3: Quick reference (one self-contained example covering every
surface)
- Section 4: API reference (owlry.set / providers / tabs / provider /
theme) with per-field tables and rules
- Section 5: Host API in scope (full stdlib + owlry.util convenience
helpers); no sandbox in 2.1
- Section 6: How providers/tabs/provider{} compose at runtime — the
three orthogonal axes (compiled in / enabled / shown as tab) made
explicit with a worked example and a what-if table
- Section 7: Hot reload via notify crate (re-added in Phase 3)
- Section 8: Validation via 'owlry config validate' / 'config show'
- Section 9: Migration via 'owlry migrate-config' with full TOML→Lua
mapping table
- Section 10: Open questions resolved before Phase 3 ships
- Section 11: Version compatibility roadmap (2.0 -> 2.1 -> 2.2 -> 3.0)
- Section 12: Implementation outline (handoff to engineering)
docs/RESTRUCTURE-V2.md:
- D23: config file named owlry.lua (brand identity over init.lua
convention; file is loaded explicitly, not via Lua's require)
- D24: owlry.providers vs owlry.tabs distinction made explicit — three
orthogonal axes (compiled in / enabled / shown as tab), full
composition spec lives in lua-api.md §6
The Lua API doc is intended as both the design spec we're committing to
AND the user-facing reference once Phase 3 ships.
vikingowl
1075eefbf3