docs: replace Space README with usage and storage notes

- keep the Space title as StockAnalysis and refresh short_description
- remove the old placeholder/offensive README content
- document discovery, cheapest-then-fastest routing, pass criteria, and budget
- document the UI controls, history dropdown, and JSON download
- document HF_TOKEN requirements and that the token is never written to disk
- describe the /data/hf-inference-smoke storage layout
- describe the project layout for app.py, smoke.py, and requirements.txt

README.md

@@ -9,7 +9,65 @@ python_version: '3.13'
 app_file: app.py
 pinned: false
 license: mit
-short_description: A proven 10x investment tool.
+short_description: Smoke-test the 30 most trending chat models.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# StockAnalysis - HF Inference Smoke Test
+
+Smoke-tests the **30 most trending** chat-completion models on Hugging Face
+through [Inference Providers](https://huggingface.co/docs/inference-providers)
+and reports a literal `True` or `False` for each model.
+
+## What it does
+
+1. **Discovery** - queries the Hub for `conversational` models sorted by
+   `trendingScore`, scanning past the requested count so models without a live
+   inference provider are skipped.
+2. **Routing** - calls each model through the HF router with `:cheapest`. If the
+   request fails, it retries once with `:fastest`.
+3. **Pass criteria** - `True` only when the router returns HTTP 200 with a
+   non-empty `choices` array. Anything else is `False` with a recorded error.
+4. **Concurrency** - three models are tested at a time with a 60s timeout each.
+5. **Budget** - each attempt requests at most 8 output tokens, so a 30-model run
+   costs well under a cent of Inference Providers credit.
+
+## Using the app
+
+- Press **Run smoke test** to test the top trending models.
+- Adjust **Models to test** to scan more or fewer models.
+- The table shows rank, model, `True`/`False`, the routing policy that produced
+  the passing attempt, latency, and the error for failures.
+- Use **Run history** to reload a previous run.
+- **Download run JSON** exports the currently displayed run.
+
+`HF_TOKEN` must be available as a Space secret or environment variable. This is
+a normal read token with Inference Providers access; the app never writes the
+token to disk. Without a token the app shows a clear error and refuses to make
+inference calls.
+
+## Storage
+
+Run artifacts go to the persistent bucket, not the repository:
+
+```text
+/data/hf-inference-smoke/
+├── latest.json              # most recent run (mirror)
+├── runs/<run_id>.json       # one file per run
+└── models/latest.json       # most recent discovery snapshot
+```
+
+## Project layout
+
+```text
+app.py             # Gradio Blocks dashboard
+smoke.py           # discovery, routing, runner, persistence
+requirements.txt   # pinned dependencies
+```
+
+## Notes
+
+- Models are ordered by trending score, not downloads.
+- Trending models can lack a live provider; discovery scans further to keep the
+  requested count.
+- A `False` result means that model could not produce a valid chat completion
+  through either routing policy at the time of the run.