docs: improve README setup and usage

README.md

@@ -17,7 +17,7 @@ owns channels, schedules, history, approvals, security, and result delivery.
 Your coding agent owns the intelligence and tools.
 
 [Read the documentation](https://owainlewis.github.io/push/) ·
-[Install Push](https://owainlewis.github.io/push/getting-started/) ·
+[Get started](#quickstart) ·
 [View releases](https://github.com/owainlewis/push/releases)
 
 ## What Push gives you
@@ -52,6 +52,115 @@ makes one of those agents persistent, reachable, schedulable, and accountable.
 The backend can change. Your assistant repository remains portable, while
 Push keeps conversations, run history, schedules, and delivery routes durable.
 
+## Quickstart
+
+### Requirements
+
+- Apple Silicon macOS or x86_64 Linux for the current prebuilt release
+- macOS for iMessage, or macOS/Linux for Telegram
+- [Codex](https://developers.openai.com/codex/cli/),
+  [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), or
+  [Pi](https://pi.dev/) installed, authenticated, and runnable by the user that
+  will run Push
+- Git for the assistant repository created by `push init`
+- `curl` and `tar` for the release installer
+
+First confirm that your chosen backend works. For example:
+
+```sh
+codex --version
+```
+
+### Install
+
+Install the latest prebuilt release to `~/.local/bin/push`:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/owainlewis/push/main/install.sh | sh
+```
+
+The installer verifies the release archive against its published SHA-256
+checksum. If `~/.local/bin` is not on `PATH`, add it before continuing.
+
+To build from source instead, install the stable Rust toolchain first:
+
+```sh
+git clone https://github.com/owainlewis/push.git
+cd push
+cargo build --locked --release
+mkdir -p ~/.local/bin
+install -m 755 target/release/push ~/.local/bin/push
+```
+
+### Set up an assistant
+
+Create the assistant repository and default config:
+
+```sh
+push init ~/Code/assistant
+```
+
+This creates a Git repository containing `SOUL.md`, `AGENTS.md`, `context/`,
+and `jobs/`, then records its path in `~/.push/config.toml`. New configs use
+Telegram and Codex by default. Edit the config to add your Telegram bot token
+and numeric user ID:
+
+```toml
+channel = "telegram"
+agent = "codex"
+assistant_root = "~/Code/assistant"
+
+[telegram]
+bot_token = "token-from-BotFather"
+allow_user_ids = [123456789]
+```
+
+For iMessage, use the [iMessage setup guide](docs/channels/imessage.md). For
+Claude Code or Pi, set `agent = "claude"` or `agent = "pi"` after confirming
+that backend is authenticated for the same user.
+
+Validate the setup, then start the gateway:
+
+```sh
+push doctor
+push
+```
+
+Send a new message after the gateway starts. Telegram discards pending updates
+on its first run, so resend any message you used while creating the bot.
+
+## Use Push
+
+Chat messages go to the configured coding agent with the assistant repository
+as its working directory. Try a read-only first request:
+
+> Summarize `/absolute/path/to/my-project/README.md`. Do not change anything.
+
+Push leaves sandbox, approval, and tool permissions to the selected backend.
+Review [permissions and security](docs/security.md) before allowing unattended
+work.
+
+Chat commands:
+
+| Message | Effect |
+| --- | --- |
+| `/clear`, `/new`, `/reset` | Start a fresh backend session for this conversation |
+| `/help` | Show available chat commands |
+
+Jobs are Markdown runbooks stored in the assistant repository. Common commands
+are:
+
+```sh
+push job validate
+push job list
+push job run repo-review
+push job runs repo-review
+```
+
+See [jobs and schedules](docs/jobs.md) for the runbook format and scheduling,
+and [running as a service](docs/services.md) to keep Push online with `launchd`
+or `systemd`.
+
 ## Push and Hermes Agent
 
 [Hermes Agent](https://hermes-agent.nousresearch.com/docs/) is a broad,
@@ -91,27 +200,6 @@ permissions you give your backend. Push does not override agent permissions, so
 write access to the assistant repository can also change `SOUL.md` or installed
 jobs outside the draft approval workflow.
 
-## Start here
-
-Install the latest available prebuilt release:
-
-```sh
-curl -fsSL https://raw.githubusercontent.com/owainlewis/push/main/install.sh | sh
-```
-
-The current release publishes archives for Apple Silicon macOS and x86_64
-Linux. Other Rust-supported architectures can [build from source](docs/getting-started.md#build-from-source).
-
-Then follow the [quickstart](https://owainlewis.github.io/push/getting-started/)
-to create your assistant repository, choose a channel, configure a backend,
-run `push doctor`, and keep the gateway online.
-
-To use [Pi](https://pi.dev/), install it, complete provider authentication for
-the same service user that runs Push, and set `agent = "pi"`. `pi_bin` defaults
-to `pi`. Push stores Pi's reported session ID and resumes that exact session on
-later turns; `/clear` starts a new one. Push passes no tool override to Pi, so
-review Pi's own configuration before allowing unattended access.
-
 ## Documentation
 
 The Markdown under [`docs/`](docs/) is the canonical documentation source. It
@@ -126,6 +214,22 @@ every documentation change to `main`.
 - [Architecture](docs/architecture.md)
 - [Contributing](docs/contributing.md)
 
+## Contributing
+
+Push is a Rust project. After cloning the repository, run the same core checks
+used by CI:
+
+```sh
+cargo fmt --all --check
+cargo clippy --locked --all-targets -- -D warnings
+cargo build --locked
+cargo test --locked
+```
+
+Documentation changes should also pass `mkdocs build --strict` after installing
+`requirements-docs.txt`. Read the full [contributing guide](docs/contributing.md)
+before submitting a pull request.
+
 ## License
 
 Push is available under the [MIT License](LICENSE).