Rewrite docs

[sandstrom]

Great gem! 💎

The current readme feels very AI-generated and is quite verbose. The signal to noise ratio isn't very high.

Some other thoughts:

• Great that it supports generic use-cases (hotcell-core and client/server gems), and that the active storage stuff is layered on top.
• The set of failure codes is pretty long, are all of them needed?
  • Maybe just let the hotcell return a JSON response instead? And reduce failure modes to those related to crashes etc.

[flavorjones]

@sandstrom Thanks for posting. I'm working towards a v1.0 release and I will be making a pass on the docs.

The hotcell does return JSON. I'm not sure I understand what your pain point is, especially if you're using the client base class as intended. Say more?

[sandstrom]

Great! 💯

Sure, I'll elaborate.

A failure carries a code -- unreadable, invalid, unsupported, failed, capacity, unavailable, timeout, protocol, or killed with a cause -- and each code is permanent or transient.

There is no clear definition of each code, and some of them seems overlapping. A few examples of questions these raise:

• What is the difference between unreadable and invalid? Is malformatted XML unreadable, invalid or unsupported?

• How is protocol different from invalid?

• Failed sounds like a superset of timeout and killed?

• How can an invalid error be transient?

My gut feeling is that the set could be reduced somewhat, and also more clearly labeled.

It's also unclear if these are intended only for the 'managed parts' (wire protocol, runner, etc) or also intended to be emitted by a custom operation I'd write.

---

But overall this looks awesome, I'm very positive! 💎

[flavorjones]

@sandstrom Good feedback, I'll make sure the docs clarify the intent here (and maybe I'll do a simplification pass, error-handling ended up being a bit more complex than originally intended).

[flavorjones]

@sandstrom I've merged changes restructuring the documentation, which I hope address the structural aspects of your feedback. It still reads as too agent-y in places and we'll fix that over time.

[sandstrom]

Nice! It's much better.

But still reads like a verbose LLM wrote it in some sections, which I guess is what happened.

Other misc thoughts:

1. "This is pre-release software. It may break in interesting ways. Use it with caution until the v1.0 release." This seems outdated now?

2. Docs and code seems to mix "hot cell" and "hotcell". In Ruby the convention is usually that single word class is Hotcell, or in paths hotcell, and not eg. HotCell or hot_cell.

   I don't care which one it is, but would try to pick one and be consistent.

Eager to try it out now that it's 1.0!