docs: rewrite mkdocs site for v0.2.1 and expand source docstrings

Replace the stale v0.2.0 docs tree (api/, advanced/, responses/, sources/,
tasks/) with a new structure: getting-started, guides, reference, about.
The reference pages are generated by mkdocstrings against the new
v0.2.1 module layout (ogpu.client, ogpu.chain, ogpu.protocol, ogpu.types,
ogpu.events, ogpu.agent, ogpu.ipfs, ogpu.service).

Add Google-style docstrings (Args / Returns / Raises / Example) to every
public class and method across the SDK so mkdocstrings has rich content
to render. Examples use fenced ```python blocks instead of doctest-style
prompts so they pick up syntax highlighting in the rendered docs.

Each reference page also gets an intro prose section explaining the
module's role, signer handling, and how it fits into the rest of the
SDK.

`mkdocs build --strict` is clean.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kutay-ogpu

docs/about/changelog.md

@@ -0,0 +1,76 @@
+# Changelog
+
+The canonical changelog lives in the repo root at
+[`CHANGELOG.md`](https://github.com/OpenGPU-Network/sdk-ogpu-py/blob/main/CHANGELOG.md).
+The current release is **v0.2.1**.
+
+## v0.2.1 — highlights
+
+### New features
+
+- **`ogpu.chain`** — new top-level home for `ChainConfig`, `ChainId`,
+  `Web3Manager`, `NonceManager`, ABI files, and RPC URL config.
+  Role-agnostic, used by every SDK module. `from ogpu import ChainConfig`
+  ergonomically re-exports the public surface.
+- **`ogpu.ipfs`** — public module (previously `_ipfs`) with
+  `publish_to_ipfs` and `fetch_ipfs_json`, top-level re-exported:
+  `from ogpu import publish_to_ipfs, fetch_ipfs_json`.
+- **Instance classes** — `Source`, `Task`, `Response`, `Provider`,
+  `Master` as live stateless proxies bound to contract addresses. Full
+  read + write methods and `snapshot()` batch capture.
+- **Vault module** (`ogpu.protocol.vault`) — deposit, withdraw, lock,
+  unbond, cancel_unbonding, claim, plus 9 reads and 2 constants.
+  Previously 0% covered from Python.
+- **Event subscription** (`ogpu.events`) — 6 async generators for
+  critical Nexus events. The one async island — rest of SDK stays sync.
+- **Agent package** (`ogpu.agent`) — scheduler wrappers for agent-role
+  operations (`register_to`, `unregister_from`, `attempt`). Uses
+  `AGENT_PRIVATE_KEY` env var fallback.
+- **Exception hierarchy** — 22 concrete exception classes under
+  `OGPUError` base, grouped by domain (NotFound, State, Permission,
+  Vault, Tx, Config, IPFS).
+- **`TxExecutor`** — unified transaction sender with nonce retry,
+  underpriced backoff, and typed revert decoding. Replaces ~300 lines
+  of duplicated retry logic.
+- **`Receipt` dataclass** — unified return type for all write operations.
+- **`ChainConfig.set_rpc / get_rpc / reset_rpc`** — custom RPC endpoint support.
+- **Type-safe status enums** — `TaskStatus`, `SourceStatus`,
+  `ResponseStatus`, `Environment`, `DeliveryMethod`.
+- **`Response.fetch_data()`** — follows the URL returned by
+  `response.get_data()` and parses the JSON body.
+- **Pagination helper** — transparent internal chunking for all
+  list-returning methods.
+
+### Breaking changes
+
+- **`publish_source()` now returns `Source`** (was `str`). Use `.address`
+  for the raw address.
+- **`publish_task()` now returns `Task`** (was `str`).
+- **Default chain flipped to `OGPU_MAINNET`** (was `OGPU_TESTNET`).
+  Testnet users must prepend
+  `ChainConfig.set_chain(ChainId.OGPU_TESTNET)`.
+- **`get_confirmed_response()` standalone function deleted.** Use
+  `Task(addr).get_confirmed_response()` instead (chain-only, no HTTP).
+- **`get_task_responses()` returns `list[Response]` instances** (was
+  list of old dataclass).
+- **`ogpu.agent` module previously existed for `set_agent` — that has
+  been replaced.** `set_agent` is now at `ogpu.protocol.terminal.set_agent`
+  or `ogpu.client.set_agent`; `ogpu.agent` is now the scheduler-role
+  high-level package.
+- **`ImageMetadata` renamed to `SourceMetadata`.**
+- **Old `Response` and `ConfirmedResponse` dataclasses deleted.**
+  Replaced by `Response` instance class.
+- **`requires-python` bumped to `>=3.10`.**
+- **No HTTP dependency for contract reads.** The management-backend
+  HTTP call in the old `get_confirmed_response` is removed entirely.
+- **Chain infrastructure moved out of `ogpu.client`** (clean break):
+    - `from ogpu.client import ChainConfig` → `from ogpu import ChainConfig`
+    - `from ogpu.client.chain_config import ChainId` → `from ogpu.chain.config import ChainId`
+    - `from ogpu.client import fix_nonce` → `from ogpu import fix_nonce`
+    - ABI files moved from `ogpu/client/abis/` to `ogpu/chain/abis/`
+- **`SourceInfo.to_source_params` / `TaskInfo.to_task_params` deleted.**
+  These type-methods triggered hidden IPFS uploads. The work is now in
+  private helpers in `ogpu.client` — user-facing API is unchanged, but
+  `SourceInfo` and `TaskInfo` are now pure dataclasses.
+
+See the [full changelog](https://github.com/OpenGPU-Network/sdk-ogpu-py/blob/main/CHANGELOG.md) for every entry.

docs/about/contributing.md

@@ -0,0 +1,114 @@
+# Contributing
+
+The SDK is open source under the MIT license. Contributions welcome.
+
+## Development setup
+
+```bash
+git clone https://github.com/OpenGPU-Network/sdk-ogpu-py.git
+cd sdk-ogpu-py
+pip install -e ".[dev]"
+```
+
+This pulls in `pytest`, `pytest-asyncio`, `pytest-cov`, `mypy`, `ruff`,
+and `nbformat`.
+
+## Running the test suite
+
+```bash
+pytest tests/                    # full suite (all mocked, no chain)
+pytest tests/unit/test_vault.py  # one module
+pytest tests/ -k "vault"         # by keyword
+```
+
+Every test in `tests/unit/` is mock-based — nothing hits a real chain.
+The suite runs in under 2 seconds.
+
+## Type checking and lint
+
+```bash
+mypy ogpu/       # strict mode, configured in pyproject.toml
+ruff check ogpu/ # lint
+ruff format ogpu/  # format
+```
+
+Run all three before opening a PR.
+
+## Layer discipline
+
+The SDK is organized by layer:
+
+```
+types  chain  ipfs          ← leaves, no outward dependencies
+   ↑
+protocol                     ← 1:1 contract wrappers
+   ↑
+client / agent / events      ← role-first workflows
+```
+
+New code must respect this direction:
+
+- Nothing under `ogpu/types/` may import from higher layers
+- `ogpu/protocol/` may import from `types`, `chain`, `ipfs` but not `client`
+- `ogpu/client/`, `ogpu/agent/`, `ogpu/events/` sit at the top
+
+If you find yourself wanting to import a higher layer from a lower one,
+the code probably belongs in the higher layer.
+
+## Adding a new method on an instance class
+
+Example: adding `Task.get_something_new()`.
+
+1. Check the `TaskAbi.json` to find the underlying function name
+2. Add the method to `ogpu/protocol/task.py`:
+   ```python
+   def get_something_new(self) -> int:
+       return int(self._contract().functions.somethingNew().call())
+   ```
+3. Add a unit test in `tests/unit/test_instance_task.py`:
+   ```python
+   def test_get_something_new(self):
+       c = _mc(somethingNew=42)
+       t, p = self._t(c)
+       with p:
+           assert t.get_something_new() == 42
+   ```
+4. If it's a write method, update `REVERT_PATTERN_MAP` in `_base.py`
+   with any new revert strings.
+5. Run `pytest`, `mypy`, `ruff`.
+
+## Documentation
+
+Docs live in `docs/` and build with mkdocs-material:
+
+```bash
+pip install -r docs-requirements.txt
+mkdocs serve   # local preview at http://localhost:8000
+mkdocs build --strict   # CI-equivalent build
+```
+
+API reference pages use `mkdocstrings` to pull docstrings from source.
+Adding a new method with a Google-style docstring is enough — it will
+appear in the reference automatically.
+
+## Commit conventions
+
+The repo uses conventional commits (`feat:`, `fix:`, `docs:`, `chore:`,
+`refactor:`, `test:`).
+
+## Reporting issues
+
+File issues at
+[github.com/OpenGPU-Network/sdk-ogpu-py/issues](https://github.com/OpenGPU-Network/sdk-ogpu-py/issues).
+
+Please include:
+
+- Python version
+- SDK version (`python -c "import ogpu; print(ogpu.__file__)"`)
+- Minimal reproduction code
+- Expected vs actual behavior
+- Full traceback if it's a crash
+
+## License
+
+MIT. See [LICENSE](https://github.com/OpenGPU-Network/sdk-ogpu-py/blob/main/LICENSE).