EPIC: Add starter-config CLI with friendly help UX

[franciscojavierarceo]

Summary

Add a new CLI with commands that generates curated starter configuration files for common Praxis use cases.

The first release should establish a general starter-config framework, while only shipping a small set of AI-focused recipes initially. The v1 experience should be fast, predictable, and pleasant: choose a recipe, generate a known-good config, and get clear help text for what to do next.

Why

Praxis currently expects users to start from docs and example YAMLs. That works, but it creates a blank-page problem for new users.

A starter-config CLI would:

• make Praxis easier to try without writing YAML from scratch
• keep the workflow aligned with Praxis as a config-first proxy
• provide a durable entrypoint that can grow beyond AI-specific configs
• make the terminal UX more approachable and fun to explore

Proposed UX

Use an explicit action-oriented command shape:

praxis-config-generator <traffic-shape> <recipe>

Initial examples:

praxis-config-generator messages passthrough
praxis-config-generator messages to-openai
praxis-config-generator responses passthrough
praxis-config-generator responses full-flow

This is preferred over a flag-heavy shape like:

praxis-config-generator --api messages --type passthrough

because subcommands scale better as we add more recipes, help output, and future starter categories outside AI traffic.

Mental Model

• <traffic-shape> identifies the incoming API family or workload shape.
• <recipe> identifies how Praxis should handle that traffic.

This keeps discovery centered on what the user already has in hand, such as Anthropic Messages or OpenAI Responses traffic, instead of making them think first about the backend target.

Initial Scope

messages

• passthrough
  • Accept Anthropic Messages traffic and proxy it to Anthropic with the minimum routing/classification/credential setup required.
• to-openai
  • Accept Anthropic Messages traffic and transform it for an OpenAI-compatible backend such as vLLM.

responses

• passthrough
  • Accept OpenAI Responses traffic and proxy it to a compatible upstream.
• full-flow
  • Provide a more complete starter for common Responses workflows, likely including the filters needed for a realistic end-to-end setup rather than bare passthrough only.

Output Model

In v1, praxis-config-generator should generate output from curated templates checked into the repo.

Recommended behavior:

• default output path is ./praxis.yaml
• refuse to overwrite an existing file unless explicitly told to in a future flag
• keep generated YAML readable and lightly commented
• prefer starter configs that are valid with minimal edits, even if the user still needs to fill in backend addresses or credentials

The generated file should feel like a maintained example the user can trust, not opaque machine-produced config.

Help / Docs Expectations

This should be pleasant to use from the terminal:

• praxis-config-generator --help explains the purpose of starter generation
• praxis-config-generator messages --help explains available messages recipes
• invalid combinations suggest nearby valid recipes
• successful generation prints next steps such as where the file was written, how to validate it, how to start Praxis with it, and where to read more

Docs follow-up for v1:

• quickstart should mention praxis-config-generator as the easiest way to begin
• generated output should correspond to documented recipes
• help text should be written for approachability, not only for maintainers

Non-Goals

• interactive wizard flows in v1
• arbitrary config synthesis from many prompts or flags
• covering every example config in the repository on day 1
• replacing the existing example catalog or operator documentation

Follow-Up Ideas

• interactive guided mode for praxis-config-generator
• additional starter families beyond AI traffic
• template listing/search such as praxis-config-generator --list
• flags for output path, stdout printing, or non-overwriting dry runs

Open Questions

• should passthrough remain generic across traffic families, or should some recipes become more explicit like to-anthropic?
• which existing example configs should be treated as the source of truth for each initial recipe?
• should v1 include a listing command, or is help output enough?

Possible Sub-Issues

• implement praxis-config-generator command framework
• add initial messages starters
• add initial responses starters
• add help UX and suggestion text
• update quickstart/docs for starter generation
• design interactive guided mode as a follow-up