First I appreciate that you added API for access to your mod's features.
After hearing the news, I decided to add support of the stamina of your mod for my mod (parcool) and it was released for 1.20.1.

From now I'll talking about the things refered in the title. When I were using your API of Stamina, I noticed the stamina value behaved weirdly. The stamina seemed to be consumed by calling int Stamina.takeStamina( int, boolean, boolean) but actually it was not consumed and recover immediately on next tick after stopping consuming it.
Let me jump to conclusion. This is because the method was called from client side and it was not synchronized automatically. As for this problem, itself was solved due to manually (meaning by other synchronization way) synchronizing its value with the server.
(This is menthoned by you before at #77)

How about adding little more detailed description about this as warning, to document comment (or making a reference/document and add to it) ? If you can detect which logical side calls the methods easily, what do you think about throwing exceptions when called from client?

Ideally I hope you make the code automatically sync its value with Server if it is changed from client but I am sure this is a relatively troublesome task.

In addition, I think there are lack of description about some arguments of methods which API has. For example, int Stamina.giveStamina( int amount, boolean simulate) has an argument named simulate as its second arg but I could not understand its mean soon until reading source code.
Even document comment says just

Simulation only if true

If you admit, I can modify them and send pull-request.

I will apologize if these problems are already solved and written on somewhere. In this case, please close this issue.

Anyway this mod is great work. This has no need to rush. Take your time.

I agree actually it should be impossible to synchronize value from client when it is managed by the server.

Thank you.

Uhhh, that would be nice.

A coupe of docs have been adjusted. Thank you for your suggestion.

I don't plan to make client-side access to the API to cause outright crash, since that kind of approach directly opposes user experience; I would imagine players rather want client desync than hard crash, especially when the subject is client-side logic, where the errors generally do not directly interfere with server-side logic.

Auto-sync from client to server is something that I actively avoided, because it leaves too easy of an exploit point to the clients. You only need one packet to completely nullify the entirety of stamina system. Part of the reason why I chose to not use preexisting stamina API - the one that start with F, to be specific - was this. Objectively speaking the client and server both having control over stamina value muddles the ownership of that value, which I consider is a bad practice.