Docs/readme quickstart

[alxxjohn]

Summary

This PR makes the project landing page easier to understand for both technical and non-technical users. It now reads as a short, friendly
open-source-project README: install szr, connect it to an AI coding agent, use it, and see the savings.

Detailed material that does not need to be on the first page now lives in a dedicated user guide.

What changed

README structure and tone

• Rewrote the main README to be substantially shorter and focused on first use.

• Replaced dense implementation-oriented explanations with plain-language descriptions of what szr does:

  • makes noisy terminal output easier to read and cheaper to send to an AI assistant;
  • keeps errors, file locations, and exit codes;
  • can be used by people directly in a terminal or through supported AI coding-agent integrations.

• Reduced the badge set to the release, npm, PyPI, CI, and Apache 2.0 license badges.

Four-step onboarding flow

The README now guides a new user through these explicit steps:

1. Install szr
2. Connect szr to your agent
3. Use szr
4. See what you saved

The agent setup step shows the Codex command and names the other supported integrations:

szr install codex

Other supported options:

szr install claude-code
szr install cursor
szr install gemini

Remove an integration with:

szr uninstall

The usage step makes clear that agents can use szr while they work, while people who work directly in a terminal can manually prefix a command
with szr:

szr git status
szr git diff
szr go test ./...
szr find . --name "*.py"

It also states the core safety behavior in plain language: commands retain their normal success/failure result; szr only makes output easier
to scan, and shows original output when it cannot safely shorten it.

The savings step introduces:

szr spread
szr usage

spread reports terminal-output savings and usage compares those savings with token usage recorded by supported local AI-agent sessions.

Installation chooser

• Replaced the flat list of installation methods with GitHub-native expandable sections.
• Homebrew is open by default; npm, pip, Go, and local-checkout installation methods are available as separate selectable sections.
• Each method finishes with szr self doctor so users can immediately verify their installation.
• The README explains each method:
  • Homebrew for macOS or Linux;
  • npm and pip install prebuilt binaries without Go;
  • Go builds from source;
  • local checkout is for contributors.

GitHub README Markdown does not support true tab controls. Expandable

Details

sections are used as the reliable, accessible GitHub-native
equivalent.

New docs/USER_GUIDE.md

Added a user guide for material that is useful after the initial setup:

• everyday terminal use and shell-wrapper behavior;
• AI tool integrations and what each one configures;
• szr spread, --history, --cost, and --rate;
• local transcript discovery with szr discover;
• agent/session usage reporting with szr usage;
• recovery of full output with szr expand and szr tee --latest;
• integration and advanced-workflow commands, including szr rewrite --json, szr watch --jsonl, diagnostics, and SZR_SESSION;
• a concise advanced-command catalog and a pointer to szr commands for the complete catalog on the installed version.

Documentation links

The README now links to:

• the new user guide;
• profiles;
• user-defined filters;
• contributing guidance; and
• architecture documentation.

Verification

git diff --check

No whitespace errors were reported.

Commits included

• b0c648b — docs: streamline README quick start
• d4512ad — docs: clarify getting started guidance
• 1839bdf — docs: lead with AI integration workflow
• ceae983 — docs: organize README around onboarding steps