@@ -0,0 +1,52 @@
+name: main
+
+on:
+  push:
+    branches:
+      - main
+  pull_request: {}
+
+concurrency:
+  group: ${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: extractions/setup-just@v2
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+      - run: uv python install 3.11
+      - run: just install lint-ci
+
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: extractions/setup-just@v2
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+      - run: uv python install ${{ matrix.python-version }}
+      - run: just install
+      - run: just test --cov=src/httpware --cov-report xml
+      - uses: codecov/codecov-action@v4.0.1
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        with:
+          files: ./coverage.xml
+          flags: unittests
+          name: codecov-${{ matrix.python-version }}
@@ -0,0 +1,25 @@
+# Generic things
+*.pyc
+*~
+__pycache__/*
+*.swp
+*.sqlite3
+*.map
+.vscode
+.idea
+.DS_Store
+.env
+.pytest_cache
+.ruff_cache
+.coverage
+htmlcov/
+coverage.xml
+pytest.xml
+dist/
+build/
+wheels/
+*.egg-info
+.python-version
+.venv
+uv.lock
+plan.md
@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `httpware` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial project scaffold: `src/httpware/` package, `py.typed` marker, `pyproject.toml` with `uv_build` backend.
+- Org conventions ported from `modern-python/modern-di`: `Justfile`, `.github/workflows/ci.yml`, `[tool.ruff]` config, `[tool.pytest.ini_options]`, dev and lint dep groups.
+- Declared dependencies: `httpx2>=2.0.0b1,<3.0`, `pydantic>=2.0,<3.0`.
+- Declared install extras: `[msgspec]`, `[otel]`, `[niquests]`, `[all]`.
+- `SECURITY.md` with 90-day private-disclosure window.
+- `CONTRIBUTING.md` with development workflow.
+- `CLAUDE.md` with AI-agent guidance.
+
+[Unreleased]: https://github.com/modern-python/httpware/compare/HEAD...HEAD
@@ -0,0 +1,102 @@
+# CLAUDE.md
+
+Guidance for AI agents (Claude Code, etc.) working in this repository.
+
+## Project Overview
+
+`httpware` is a Python async HTTP client framework for building resilient service clients. It supersedes `community-of-python/base-client` and ships under the `modern-python` org. The framework owns the abstraction layer above the underlying HTTP client (`httpx2` by default); consumers never import the transport.
+
+**Source-of-truth planning artifacts** live in the sibling `base-client` repo (until httpware is fully self-hosted):
+
+- `base-client/docs/prd.md` — Product Requirements Document (47 FRs, 25 NFRs)
+- `base-client/docs/architecture.md` — 12 architectural decisions, 5 protocol seams, full module layout
+- `base-client/docs/epics.md` — 6 epics, 32 stories with Given/When/Then acceptance criteria
+
+Stories under active dev live in `httpware/docs/stories/`.
+
+## Commands
+
+This project uses `just` (task runner) and `uv` (package manager).
+
+```bash
+just install      # uv lock --upgrade && uv sync --all-extras --frozen --group lint
+just lint         # eof-fixer + ruff format + ruff check --fix + ty check
+just lint-ci      # same checks without auto-fixing (used in CI)
+just test         # uv run pytest (with coverage by default)
+just test-branch  # pytest with branch coverage
+```
+
+`just test` passes extra args to pytest:
+
+```bash
+just test tests/test_client.py
+just test tests/test_client.py -k test_get_returns_typed_response
+```
+
+Without `just`:
+
+```bash
+uv run ruff format . && uv run ruff check . --fix && uv run ty check
+uv run pytest
+```
+
+## Architecture invariants (CI-enforced)
+
+These are non-negotiable. CI rejects PRs that violate them.
+
+- **No `httpx2` leakage**: `import httpx2` / `from httpx2` is allowed ONLY inside `src/httpware/transports/httpx2.py`. The mapping of `httpx2` exceptions to `httpware` exceptions happens at that single seam.
+- **No `httpx2` private API**: `grep -rE 'httpx2\._' src/httpware/` must return zero matches.
+- **No `from __future__ import annotations`**: Python 3.11+ floor; PEP 604/585 syntax is native.
+- **No `print()`**: enforced by ruff.
+- **No global logging config**: no `logging.basicConfig()`, no bare `logging.getLogger()`. Acquire `logging.getLogger("httpware")` or `logging.getLogger(f"httpware.{module}")` only.
+- **Type suppressions**: use `# ty: ignore[<rule>]`, never `# type: ignore` or `# mypy: ignore`.
+
+## Code conventions
+
+- **Modules**: `snake_case` (`client.py`, `request.py`, `transports/httpx2.py`).
+- **Classes**: `PascalCase`. `Http` is two letters: `Httpx2Transport`, not `HTTPX2Transport`.
+- **Methods**: `snake_case`. No `a` prefix on async methods (match `httpx2`); `aclose()` is the sole exception.
+- **Private symbols**: `_leading_underscore`. Cross-module private code lives in `_internal/`.
+- **Imports**: absolute paths inside `src/httpware/`; relative imports only within the same subpackage.
+- **Docstrings**: PEP 257. Module/class/public-method required; `D1` (missing docstring) is ignored.
+- **Exception construction**: keyword arguments only. Mandatory fields: `status: int`, `body: bytes`, `headers: Mapping`, `json: Any | None`, `request_method: str`, `request_url: str`.
+
+## Module layout
+
+```
+src/httpware/
+├── __init__.py                    # public exports + __all__
+├── client.py                      # AsyncClient
+├── request.py                     # Request + with_*
+├── response.py                    # Response, StreamResponse
+├── errors.py                      # status-keyed exception hierarchy
+├── config.py                      # Limits, Timeout, ClientConfig, Redactor
+├── middleware/                    # protocols + built-in middleware
+├── transports/                    # Transport protocol + Httpx2Transport + RecordedTransport
+├── decoders/                      # ResponseDecoder protocol + adapters
+├── _internal/                     # private cross-module helpers
+└── py.typed
+```
+
+Story 1.1 ships only the scaffold; subsequent stories add modules.
+
+## Protocol seams
+
+Five documented internal boundaries. AI agents must respect them — never cross a seam except through its documented protocol.
+
+1. **`Middleware ↔ Transport`** — chain bottom calls `transport.__call__`.
+2. **`AsyncClient ↔ Middleware`** — chain composed at construction.
+3. **`AsyncClient ↔ ResponseDecoder`** — called when `response_model` provided.
+4. **`Httpx2Transport ↔ httpx2`** — only `transports/httpx2.py` imports `httpx2`.
+5. **`httpware ↔ optional extras`** — extras imported only inside their dedicated modules.
+
+## Testing
+
+- `pytest-asyncio` auto mode — async tests do NOT need `@pytest.mark.asyncio`.
+- Property-based tests (Hypothesis) for concurrency-sensitive code: `RetryBudget`, `Bulkhead`, retry interleaving. Files named `test_*_props.py`.
+- Tests for transport-level mocking use `RecordedTransport` (shipped with the library); not `respx`.
+
+## When in doubt
+
+- Check the architecture document (`base-client/docs/architecture.md`) before adding a new module or extension point.
+- Surface ambiguity as a documentation gap rather than improvising.
@@ -0,0 +1,49 @@
+# Contributing to httpware
+
+Thank you for your interest in contributing. `httpware` is an open-source resilience-first async HTTP client framework for Python, maintained under the [`modern-python`](https://github.com/modern-python) org.
+
+## Quick start
+
+```bash
+git clone https://github.com/modern-python/httpware.git
+cd httpware
+just install        # uv lock --upgrade && uv sync --all-extras --frozen --group lint
+just lint           # ruff format + ruff check + ty check
+just test           # pytest with coverage
+```
+
+## Development workflow
+
+1. **Open an issue first** for non-trivial changes — design discussion catches issues earlier than code review.
+2. **Branch from `main`**, use a descriptive name (`feat/retry-budget-jitter`, `fix/transport-cancel-leak`).
+3. **Run `just lint` and `just test`** locally before pushing. CI will reject changes that fail either.
+4. **Add tests** for any code change. Property-based tests (via Hypothesis) are required for concurrency-sensitive code (retry budget, bulkhead, retry interleaving).
+5. **Update `CHANGELOG.md`** in the `Unreleased` section.
+6. **Open a pull request** against `main`. PR titles use conventional-commits style (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`).
+
+## Code style
+
+- `ruff format` enforces formatting; do not hand-format.
+- Type-check with `ty` (Astral). Use `# ty: ignore[<rule>]` for suppressions, not `# type: ignore`.
+- Do NOT use `from __future__ import annotations`. Python 3.11+ is the floor.
+- Module docstrings are required; per-method docstrings only when types alone are insufficient.
+
+See `docs/concepts/middleware.md` and `docs/recipes/custom-middleware.md` (once published) for architecture conventions.
+
+## Architecture invariants
+
+These are enforced by CI grep gates. Do not break them in pull requests:
+
+- No `import httpx2` outside `src/httpware/transports/httpx2.py`.
+- No `httpx2._*` (private API) usage anywhere in the library.
+- No `from __future__ import annotations`.
+- No `print()` calls.
+- No `logging.basicConfig()` or bare `logging.getLogger()`.
+
+## Code of Conduct
+
+By participating in this project, you agree to abide by its Code of Conduct. Be excellent to one another.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the project's MIT license.
@@ -0,0 +1,29 @@
+default: install lint test
+
+install:
+    uv lock --upgrade
+    uv sync --all-extras --frozen --group lint
+
+lint:
+    uv run eof-fixer .
+    uv run ruff format
+    uv run ruff check --fix
+    uv run ty check
+
+lint-ci:
+    uv run eof-fixer . --check
+    uv run ruff format --check
+    uv run ruff check --no-fix
+    uv run ty check
+
+test *args:
+    uv run --no-sync pytest {{ args }}
+
+test-branch:
+    @just test --cov-branch
+
+publish:
+    rm -rf dist
+    uv version $GITHUB_REF_NAME
+    uv build
+    uv publish --token $PYPI_TOKEN
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Modern Python contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,62 @@
+# httpware
+
+[![Test](https://github.com/modern-python/httpware/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/httpware.svg)](https://pypi.org/project/httpware/)
+[![Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Resilience-first async HTTP client framework for Python.**
+
+`httpware` is to Python what Polly is to .NET and resilience4j is to the JVM — a canonical resilience-first HTTP framework. The public API is transport-agnostic (the underlying client is `httpx2` by default, sitting behind a swappable `Transport` protocol). Retries, timeouts, bulkheads, and a Finagle-style **retry budget** ship as composable middleware. Tests use a `RecordedTransport` and never see the underlying client.
+
+> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0. See [CHANGELOG.md](./CHANGELOG.md).
+
+## Install
+
+```bash
+pip install httpware
+```
+
+Optional extras:
+
+```bash
+pip install httpware[msgspec]    # msgspec ResponseDecoder
+pip install httpware[otel]       # OpenTelemetry instrumentation
+pip install httpware[all]        # all of the above
+```
+
+## Quickstart
+
+```python
+from httpware import AsyncClient
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    id: int
+    name: str
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        user = await client.get("/users/1", response_model=User)
+        print(user.name)
+```
+
+## Highlights
+
+- **Transport-agnostic API.** No `httpx2` symbols leak through `httpware`. Swap to a different backend with one constructor argument.
+- **Onion middleware** with phase shortcuts (`@before_request`, `@after_response`, `@on_error`). Built-in middleware: `Retry`, `RetryBudget`, `Bulkhead`, `Timeout`, `Observability`.
+- **Retry budget by default** — token-bucket admission control (Finagle defaults). Caps retry storms before they happen.
+- **Pluggable validation.** Default pydantic decoder with cached `TypeAdapter`; msgspec decoder via extras; bring your own.
+- **`RecordedTransport` for tests.** A 3-line fixture replaces respx routes and transport-level mocking.
+- **Status-keyed exceptions** with plain fields (`status: int`, `body: bytes`, `headers`, `json`). No transport exception types in user code.
+- **First-class OpenTelemetry** instrumentation via `httpware[otel]`.
+
+## Documentation
+
+Full docs (in progress): https://httpware.readthedocs.io
+
+## License
+
+MIT — see [LICENSE](./LICENSE).