Improve usage documentation

[jugglinmike]

Update project description, remove information on the low-level "agent" utility (there are no known use-cases for direct invocation of this tool), remove CLI documentation (this is subject to rot), add instructions on installation and environment configuration, and add a usage example.

/cc @ChrisC

[gnarf]

LGTM - @ChrisC is some fresh 👀 here so curious if the updated readme leaves you with any questions we should answer

[ChrisC]

This all looks good to me @jugglinmike and reads pretty clearly imo.

I'm curious about the decision to leave out the CLI documentation. Are we also thinking of removing some of the additional flags as well to reduce possible CLI feature bloat? I get the sense that in actual usage of the tool, there may not be a whole lot of need for some of these flags?

[jugglinmike]

Thanks, Corey! Thanks, Chris!

I'm curious about the decision to leave out the CLI documentation. Are we also thinking of removing some of the additional flags as well to reduce possible CLI feature bloat? I get the sense that in actual usage of the tool, there may not be a whole lot of need for some of these flags?

To me, replicating the CLI documentation in the README is more a hazard for rot than a help for someone who is running the tool. I could be convinced otherwise, but I think the ideal solution would be to automate a check for parity between what the README says and what the CLI actually supports (for what it's worth, the two are currently out of sync on the main branch).

And yeah, I'm definitely in favor of removing features that we don't need (though we should also reach out to Vispero because it's not clear if/how they're using this code these days).