Automate README table of contents with doctoc

[Prathamesh-Singh]

Summary

• replace the hard-coded README table of contents with a doctoc-generated TOC
• include all README heading levels
• add a prek hook to keep the TOC up to date

Fixes #640

Testing

• uv run prek run doctoc --all-files
• uv run prek run --all-files

All hooks passed successfully.

[deepsource-io]

DeepSource Code Review

We reviewed changes in b391a41...530696f on this pull request. Below is the summary for the review, and you can see the individual issues we found as inline review comments.

See full review on DeepSource ↗

PR Report Card

Overall Grade

Security   Reliability   Complexity   Hygiene

Code Review Summary

Analyzer	Status	Updated (UTC)	Details
JavaScript		Oct 4, 2026 3:12a.m.	Review ↗
Secrets		Oct 4, 2026 3:12a.m.	Review ↗

---

Important

AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.

[jbampton]

We don't want a local hook or any package.json

This is not correct.

pre-commit or prek hooks are self contained mostly we don't need extra dependencies.

https://github.com/thlorenz/doctoc#usage-as-a-git-hook

[Prathamesh-Singh]

Hi @jbampton,

Thanks for the feedback. I updated the pull request as requested:

Removed the doctoc dependency from package.json.
Restored package-lock.json.
Removed the local doctoc hook.
Added doctoc as a remote prek hook using the documented repository configuration.
Kept the existing local hooks unchanged.
Updated the README table of contents.
Updated the branch with the latest changes from upstream/main.
Ran the doctoc hook and the complete prek checks successfully.
The changes have been pushed to the existing pull request for review.

[jbampton]

Thanks 🏂

[Prathamesh-Singh]

Thanks for the review and for merging, @jbampton! Happy to help with anything else on the repo.

[jbampton]

You should join the team on Discord

https://discord.gg/hKUH56YHXp

Thanks once again