fix: harden typing in the code base; add pre-commit check; improve docs

fix: harden typing in the code base; add pre-commit check; improve docs #1748