docs(readme): improve project description and formatting

Amolith created 2 months ago

Improved the project description to better explain synu's purpose as a
universal wrapper for LLM agents that tracks Synthetic usage and
interactively preconfigures supported agents. Fixed line wrapping and
formatting throughout the document.

Assisted-by: GLM 4.6 via Crush

Change summary

README.md | 53 ++++++++++++++++++++++++++++-------------------------
1 file changed, 28 insertions(+), 25 deletions(-)

Detailed changes

README.md

@@ -6,15 +6,21 @@ SPDX-License-Identifier: Unlicense
 
 # synu
 
-A universal wrapper for AI agents that tracks quota usage for [Synthetic](https://synthetic.new) API calls.
+Universal wrapper for LLM agents that tracks
+[Synthetic](https://synthetic.new) usage and interactively preconfigures
+supported agents for currently-available models (so you can try a new
+one as soon as they support it, without waiting for the agent itself to
+gain support!)
 
 ## Requirements
 
 - Fish
 - `curl` - for API requests
 - `jq` - for JSON parsing
-- `gum` - for interactive model selection ([install](https://github.com/charmbracelet/gum))
-- `SYNTHETIC_API_KEY` environment variable (for quota tracking with Synthetic)
+- `gum` - for interactive model selection
+  ([install](https://github.com/charmbracelet/gum))
+- `SYNTHETIC_API_KEY` environment variable (for quota tracking with
+  Synthetic)
 
 ## Installation
 
@@ -23,7 +29,7 @@ A universal wrapper for AI agents that tracks quota usage for [Synthetic](https:
 Add to your `~/.config/fish/config.fish`:
 
 ```fish
-fundle plugin 'synu' --url 'https://git.secluded.site/amolith/llm-projects'
+fundle plugin 'synu' --url 'https://git.secluded.site/synu'
 fundle init
 ```
 
@@ -58,11 +64,15 @@ synu crush "Help me write code"
 synu [agent-name] [agent-args...]
 ```
 
-> **Note**: synu's configuration is ephemeral and non-invasive. Running `synu claude` routes requests through Synthetic, but running `claude` directly still uses Anthropic's API with your normal configuration. synu never modifies the agent's own config files.
+> **Note**: synu's configuration is ephemeral and non-invasive. Running
+> `synu claude` routes requests through Synthetic, but running `claude`
+> directly still uses Anthropic's API with your normal configuration.
+> synu never modifies the agent's own config files.
 
 ### Interactive Model Selection
 
-Use `synu i <agent>` to interactively select models using gum:
+Use `synu i <agent>` to fetch the list of available models and
+interactively filter/select them using gum:
 
 ```fish
 synu i claude "prompt"
@@ -70,11 +80,14 @@ synu i opencode "prompt"
 synu i aider "prompt"
 ```
 
-This presents a TUI to filter and select from available Synthetic models. You'll be prompted to save your selection as the default for future sessions.
+You'll be asked whether to save your selection as the default for future
+sessions.
 
 ### Persistent Preferences
 
-Model selections made in interactive mode can be saved to `~/.config/synu/models.conf`. These become the new defaults until changed. Command-line flags always override saved preferences.
+Model selections made in interactive mode can be saved to
+`~/.config/synu/models.conf`. These become the new defaults until
+changed. Command-line flags always override saved preferences.
 
 ## Configured Agents
 
@@ -151,27 +164,17 @@ synu qwen --model hf:other/model "prompt"
 `synu` works by:
 
 1. Loading agent-specific configuration if available
-2. Fetching initial quota from the Synthetic API before running the agent
-3. Configuring the agent's environment/CLI args to route through Synthetic
+2. Fetching initial quota from the Synthetic API before running the
+   agent
+3. Configuring the agent's environment/CLI args to route through
+   Synthetic
 4. Executing the specified agent with all provided arguments
 5. Cleaning up environment variables after execution
 6. Fetching final quota and displaying session usage
 
-The quota tracking requires the `SYNTHETIC_API_KEY` environment variable. Without it, `synu` will show a warning and skip quota tracking, but still attempt to run the agent.
-
-### Adding Support for New Agents
-
-Agent definitions are stored in `functions/_synu_agents/`. Each agent file can define:
-
-- `_synu_agent_<name>_flags` - Returns argparse flag specification
-- `_synu_agent_<name>_configure` - Sets environment variables/state before execution
-- `_synu_agent_<name>_args` - Returns CLI arguments to inject
-- `_synu_agent_<name>_env_vars` - Lists environment variables to clean up
-- `_synu_agent_<name>_interactive` - Implements interactive model selection
-
-Agents without definitions work as passthrough with quota tracking.
-
-See `AGENTS.md` for detailed implementation guidance.
+The quota tracking requires the `SYNTHETIC_API_KEY` environment
+variable. Without it, `synu` will show a warning and skip quota
+tracking, but still attempt to run the agent.
 
 ## Shell completions