refactor: simplify CLI surface and add end-to-end smoke coverage

.github/workflows/ci.yml

@@ -23,8 +23,7 @@ jobs:
           python -m pip install --upgrade pip
           pip install -e ".[dev,rich]"
       - name: Run tests
-        run: |
-          python -m pytest tests/ -v
+        run: python -m pytest tests/ -v
 
   core:
     name: zero-dependency core
@@ -35,12 +34,84 @@ jobs:
         with:
           python-version: "3.11"
           cache: "pip"
-      - name: Install core + dev only (no optional extras)
+      - name: Install core + dev only (no optional runtime extras)
         run: pip install -e ".[dev]"
       - name: Run tests
-        # The core runs on the stdlib alone; optional-extra tests skip cleanly.
         run: python -m pytest -q
 
+  e2e:
+    name: all-extras end-to-end smoke
+    runs-on: ubuntu-latest
+    env:
+      SOLVENT_HOME: ${{ runner.temp }}/solvent
+      SOLVENT_SKIP_ONBOARD: "1"
+      SOLVENT_FORCE_STRIPE_SIMULATE: "1"
+      SOLVENT_DELIVERY_SECRET: "ci-only-delivery-secret-0123456789abcdef"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      - name: Install every optional feature
+        run: pip install -e ".[all,dev]"
+      - name: Run the full suite with every extra installed
+        run: python -m pytest -q
+      - name: Exercise offline CLI flows
+        run: |
+          solvent --version
+          solvent help
+          SOLVENT_HOME="${RUNNER_TEMP}/guardrails" python demo_guardrails.py
+          python run_demo.py --no-onboard --seed 100
+          solvent status
+          solvent jobs --json
+          solvent finance --json
+          solvent webhooks stats
+          solvent worker --once --keep-balance
+          solvent workspace setup
+          solvent workspace list
+          solvent pairing list
+          printf '/fund 25\nCI interactive brief\n50\nn\n' | python run_demo.py --interactive --no-onboard --seed 100
+          solvent doctor
+      - name: Exercise the real HTTP server and QR endpoint
+        run: |
+          solvent serve --port 8787 --keep-balance >"${RUNNER_TEMP}/solvent-server.log" 2>&1 &
+          server_pid=$!
+          trap 'kill "$server_pid" 2>/dev/null || true' EXIT
+          ready=0
+          for attempt in $(seq 1 30); do
+            if curl -fsS http://127.0.0.1:8787/health > /dev/null; then
+              ready=1
+              break
+            fi
+            sleep 1
+          done
+          if [ "$ready" -ne 1 ]; then
+            cat "${RUNNER_TEMP}/solvent-server.log"
+            exit 1
+          fi
+          curl -fsS http://127.0.0.1:8787/health
+          curl -fsS http://127.0.0.1:8787/api/status
+          curl -fsS http://127.0.0.1:8787/ > /dev/null
+          curl -fsS -X POST http://127.0.0.1:8787/api/chat \
+            -H 'Content-Type: application/json' \
+            -d '{"message":"/status"}' > "${RUNNER_TEMP}/chat.json"
+          grep -q 'Balance' "${RUNNER_TEMP}/chat.json"
+          timeout 3 curl -fsSN http://127.0.0.1:8787/api/events \
+            > "${RUNNER_TEMP}/events.txt" || [ "$?" -eq 124 ]
+          grep -q 'hello' "${RUNNER_TEMP}/events.txt"
+          curl -fsS -X POST http://127.0.0.1:8787/jobs \
+            -H 'Content-Type: application/json' \
+            -d '{"id":"J-http-smoke","topic":"HTTP smoke test","budget_cents":5000,"customer_email":"ci@example.com"}' \
+            > "${RUNNER_TEMP}/job.json"
+          grep -q 'session_id' "${RUNNER_TEMP}/job.json"
+          curl -fsS http://127.0.0.1:8787/jobs/J-http-smoke
+          curl -fsS http://127.0.0.1:8787/api/pair/qr -o "${RUNNER_TEMP}/pairing-qr"
+          test -s "${RUNNER_TEMP}/pairing-qr"
+          kill "$server_pid"
+          wait "$server_pid" || true
+          trap - EXIT
+
   build:
     name: build + install + CLI smoke
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -1,40 +1,39 @@
 # Contributing to SOLVENT
 
-Thanks for your interest in SOLVENT! This is a hackathon project that I'm actively improving — contributions of all kinds are welcome.
-
-## Good First Issues
-
-| Area | What to do |
-|---|---|
-| **New research topics** | Add more sample jobs in `solvent/jobs.py` |
-| **Nemotron prompts** | Improve the brief template in `solvent/service.py` |
-| **New guardrail policies** | Add a rule to `solvent/guardrails.py` |
-| **Dashboard improvements** | New charts or metrics in `solvent/dashboard.py` |
-| **Tests** | Extend the pytest suite in `tests/` |
-
-## Running Locally
+## Setup
 
 ```bash
 git clone https://github.com/ianalloway/solvent-agent.git
 cd solvent-agent
-python3 run_demo.py          # no install required for the demo
-pip install pytest
-python3 -m pytest tests/ -v  # run the test suite
+pip install -e ".[dev]"
+python3 run_demo.py --no-onboard
+python3 -m pytest -q
 ```
 
-## Pull Request Process
+Install only the optional features you are changing:
+
+```bash
+pip install -e ".[stripe]"
+pip install -e ".[serve]"
+pip install -e ".[telegram]"
+pip install -e ".[rich]"
+pip install -e ".[qr]"
+```
 
-1. Fork the repo and create a branch: `git checkout -b feat/your-feature`
-2. Make your changes.
-3. Ensure `python3 -m pytest tests/ -q` passes.
-4. Open a pull request with a clear description of what changed and why.
+Dependency declarations live in `pyproject.toml`; do not add parallel requirements files.
 
-## Code Style
+## Pull requests
 
-- Python 3.10+ with type hints where it helps readability.
-- No external dependencies in core `solvent/` (keep it importable with stdlib only).
-- Dependencies in `requirements.txt` are for optional live integrations only.
+1. Create a focused branch.
+2. Keep the standard-library core importable without optional extras.
+3. Add or update tests for behavior changes.
+4. Run `python3 -m pytest -q`.
+5. Open a pull request that explains the user-visible behavior and tradeoffs.
 
-## Questions?
+## Project boundaries
 
-Open an [issue](https://github.com/ianalloway/solvent-agent/issues) — happy to discuss ideas!
+- `solvent/agent.py` is a thin public orchestrator; durable workflow logic belongs in `solvent/stages.py`.
+- Treasury writes and Stripe actions stay behind stages and guardrails.
+- API keys belong in environment variables only.
+- Live Stripe keys are never accepted.
+- Offline mode must keep working without credentials.