doc: MPT-20094 reorganize repository documentation

AI Generated.
Rework the repository documentation structure around a developer-focused usage guide, shared-standard links, and a concise README. Replace PROJECT_DESCRIPTION with usage.md, add documentation rules, and keep Docker-based workflow guidance in the topic-specific docs.

Author: d3rky

.github/workflows/copilot-instructions.md

@@ -1,43 +1,8 @@
 ---
-description: 'Python coding conventions and guidelines'
-applyTo: '**/*.py'
+description: 'Repository entry point for Copilot'
+applyTo: '**'
 ---
 
-# Python Coding Conventions
+# Copilot Instructions
 
-## General Instructions
-- All configuration **must be provided via environment variables**.
-- Do not hardcode configuration values.
-- Write maintainable, readable, and predictable code.
-- In `pyproject.toml`:
-  - Use `*` for **minor versions only**
-    ✅ `django==4.2.*`
-    ❌ `django==^4.2.2`
-
-- Use consistent naming conventions and follow language-specific best practices.
-
-## Python Instructions
-- Use type annotations (PEP 484) - except in the `tests/` folder.
-- All public functions, methods, and classes **must include [Google-style docstrings](https://google.github.io/styleguide/pyguide.html)**.
-- **Do not add inline comments**; rely on clear code and docstrings instead.
-- Function and variable names must be explicit and intention-revealing.
-- `pyproject.toml` is the source of truth for code quality rules. Generated code must not violate any configured rules.
-- **ruff** is the primary linter for general Python style and best practices.
-- **flake8** is used exclusively to run:
-  - `wemake-python-styleguide` - Enforces strict Python coding standards ([docs](https://wemake-python-styleguide.readthedocs.io/en/latest/))
-  - `flake8-aaa` - Validates the AAA pattern in tests
-- Follow PEP 8 unless explicitly overridden by ruff.
-- Prefer simple, explicit code over clever or compact implementations.
-
-## Testing
-- Use pytest only.
-- Tests must be written as **functions**, not classes.
-- Test files and functions must use the `test_` prefix.
-- Follow ***AAA(Arrange - Act - Assert)*** strictly. See the [flake8-aaa documentation](https://flake8-aaa.readthedocs.io/en/stable/index.html).
-- Do **not** use `if` statements or branching logic inside tests.
-- Prefer fixtures over mocks whenever possible.
-- Avoid duplicating test logic; extract shared setup into fixtures.
-- Use `mocker` only when mocking is unavoidable.
-- Never use `unittest.mock` directly.
-- Always use `spec` or `autospec` when mocking.
-- Use `@pytest.mark.parametrize` tests when testing permutations of the same behavior.
+Read [AGENTS.md](../../AGENTS.md) first.

AGENTS.md

@@ -1,32 +1,35 @@
 # AGENTS.md
 
-This file is the AI assistant entry point for `mpt-api-python-client`.
-
-## Repository Purpose
-
 Python API client for the SoftwareONE Marketplace Platform (MPT) API. Provides synchronous
 (`MPTClient`) and asynchronous (`AsyncMPTClient`) clients built on httpx, with typed
 resource services, mixin-based HTTP operations, and an RQL query builder.
 
 ## Documentation Reading Order
 
-1. `README.md` — project overview and quick start
-2. `docs/architecture.md` — layered architecture, directory structure, key abstractions
-3. `docs/testing.md` — test structure, tooling, conventions, how to run tests
-4. `docs/contributing.md` — development workflow, coding conventions, linting setup
-5. `docs/local-development.md` — Docker setup, Make targets, environment variables
-
-## Library Usage
-
-See `docs/PROJECT_DESCRIPTION.md` for installation and usage examples (sync and async).
+1. `README.md` — repository overview, quick start, and documentation map
+2. `docs/usage.md` — installation, configuration, Python usage examples, and supported Docker-based commands
+3. `docs/architecture.md` — layered architecture, directory structure, and key abstractions
+4. `docs/local-development.md` — Docker-only setup and execution model
+5. `docs/testing.md` — repository-specific testing strategy and command mapping
+6. `docs/contributing.md` — repository-specific workflow and links to shared standards
+7. `docs/documentation.md` — repository-specific documentation rules
+
+Then inspect the code paths relevant to the task:
+
+- `mpt_api_client/mpt_client.py` — public sync and async client entry points
+- `mpt_api_client/http/` — HTTP clients, services, query state, and reusable mixins
+- `mpt_api_client/resources/` — domain resource groups such as catalog, commerce, billing, and integration
+- `mpt_api_client/models/` — response model layer and collection wrappers
+- `mpt_api_client/rql/` — fluent RQL query builder
+- `tests/unit/` — unit coverage for transport, resources, models, and query builder
+- `tests/e2e/` — live API coverage by domain
+- `make/` and `compose.yaml` — Docker-based local command entry points
 
 ## API Reference
 
-The upstream MPT API is described by the OpenAPI spec:
+The upstream API contract is the MPT OpenAPI spec:
 https://api.s1.show/public/v1/openapi.json
 
-Use this to understand available endpoints, request/response schemas, and field names.
-
 ## Key Commands
 
 | Command          | Purpose                                  |
@@ -36,6 +39,15 @@ Use this to understand available endpoints, request/response schemas, and field
 | `make check`     | Run all linting and type checks          |
 | `make check-all` | Run checks + tests                       |
 | `make format`    | Auto-format code                         |
+| `make bash`      | Open a shell in the Docker container     |
+| `make run`       | Start an IPython session in Docker       |
+
+## Repository Rules
+
+- Prefer Docker-based `make` targets over ad hoc local Python commands.
+- Keep `README.md` concise and navigational.
+- Put topic-specific documentation under `docs/` instead of expanding `README.md`.
+- Link shared engineering rules from `mpt-extension-skills` instead of duplicating them locally.
 
 ## Project Structure
 
@@ -48,16 +60,3 @@ mpt_api_client/
 ├── rql/                # RQL query builder
 └── exceptions.py       # Error hierarchy
 ```
-
-## Shared Standards
-
-This repository follows shared engineering standards from
-[mpt-extension-skills](https://github.com/softwareone-platform/mpt-extension-skills):
-
-- `standards/python-style-guide.md`
-- `standards/testing-standard.md`
-- `standards/contributing-standard.md`
-- `standards/pull-request-guidelines.md`
-
-
-

README.md

@@ -1,7 +1,3 @@
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=softwareone-platform_mpt-api-python-client&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=softwareone-platform_mpt-api-python-client)
-[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=softwareone-platform_mpt-api-python-client&metric=coverage)](https://sonarcloud.io/summary/new_code?id=softwareone-platform_mpt-api-python-client)
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-
 # mpt-api-python-client
 
 Python API client for the SoftwareONE Marketplace Platform (MPT) API.
@@ -10,6 +6,20 @@ Provides synchronous (`MPTClient`) and asynchronous (`AsyncMPTClient`) clients b
 [httpx](https://www.python-httpx.org/), with typed resource services, mixin-based HTTP
 operations, and an RQL query builder.
 
+## Documentation
+
+Start with these documents:
+
+- [AGENTS.md](AGENTS.md): AI-agent entry point and reading order
+- [docs/usage.md](docs/usage.md): installation, configuration, Python usage examples, and Docker-based commands
+- [docs/architecture.md](docs/architecture.md): repository structure, layers, and key abstractions
+- [docs/local-development.md](docs/local-development.md): Docker-only local setup and execution model
+- [docs/testing.md](docs/testing.md): repository-specific test strategy and commands
+- [docs/contributing.md](docs/contributing.md): repository-specific workflow and links to shared standards
+- [docs/documentation.md](docs/documentation.md): repository-specific documentation rules
+- [docs/rql.md](docs/rql.md): fluent RQL query builder guide
+- [MPT OpenAPI Spec](https://api.s1.show/public/v1/openapi.json): upstream API contract
+
 ## Quick Start
 
 ```bash
@@ -18,51 +28,10 @@ make build
 make test
 ```
 
-## Usage
-
-**[Installation & Usage Guide](docs/PROJECT_DESCRIPTION.md)**
-
-```python
-from mpt_api_client import MPTClient
-
-client = MPTClient()  # reads MPT_API_TOKEN and MPT_API_BASE_URL from environment
-
-for product in client.catalog.products.iterate():
-    print(product.name)
-```
-
-### RQL Filtering Example
-
-```python
-from mpt_api_client import MPTClient, RQLQuery
-
-client = MPTClient()
-products = client.catalog.products
-
-target_ids = RQLQuery("id").in_([
-    "PRD-123-456",
-    "PRD-789-012",
-])
-active = RQLQuery(status="active")
-vendor = RQLQuery("vendor.name").eq("Microsoft")
-
-query = target_ids & active & vendor
-
-for product in products.filter(query).order_by("-audit.updated.at").select("id", "name").iterate():
-    print(product.id, product.name)
-```
-
-## Documentation
+Use `make help` to inspect all supported Docker-based commands.
 
-| Document                                                       | Description                                                 |
-|----------------------------------------------------------------|-------------------------------------------------------------|
-| [Architecture](docs/architecture.md)                           | Layered architecture, directory structure, key abstractions |
-| [RQL Guide](docs/rql.md)                                       | Fluent builder for Resource Query Language filters           |
-| [Contributing](docs/contributing.md)                           | Development workflow, coding conventions, linting setup     |
-| [Testing](docs/testing.md)                                     | Test structure, tooling, conventions                        |
-| [Local Development](docs/local-development.md)                 | Docker setup, Make targets, environment variables           |
-| [Usage Guide](docs/PROJECT_DESCRIPTION.md)                     | Installation, sync and async usage examples                 |
-| [MPT OpenAPI Spec](https://api.s1.show/public/v1/openapi.json) | Upstream API contract (endpoints, schemas)                  |
+See [docs/usage.md](docs/usage.md) for installation details, sync and async examples, RQL
+usage, and Docker-based command examples.
 
 ## Key Commands
 
@@ -75,5 +44,3 @@ make format     # auto-format code
 make bash       # open a shell in the container
 make run        # start an IPython session
 ```
-
-Run `make help` to see all available commands.

docs/PROJECT_DESCRIPTION.md

@@ -1,15 +1,42 @@
 # Contributing
 
-This document describes the development workflow and coding conventions for
-`mpt-api-python-client`.
+This document captures repository-specific contribution guidance. Shared engineering rules
+live in `mpt-extension-skills` and should be linked, not copied, from this repository.
 
-- [Package architecture](./architecture.md)
-- [Python coding standards](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/python-coding.md)
-- [Extensions best practices](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/extensions-best-practices.md)
+## Shared Standards
+
+- [Python coding conventions](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/python-coding.md)
 - [Packages and dependencies](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/packages-and-dependencies.md)
-- [Testing](./testing.md)
-  - [Unit tests](./unit_tests.md)
-  - [E2E tests](./e2e_tests.md)
 - [Pull requests](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/pull-requests.md)
-- [Makefiles](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/makefiles.md)
-  - [Makefile targets](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/knowledge/make-targets.md)
+- [Repository documentation](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/documentation.md)
+- [Makefile structure](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/makefiles.md)
+
+## Shared Knowledge
+
+- [Build and checks](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/knowledge/build-and-checks.md)
+- [Make target meanings](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/knowledge/make-targets.md)
+
+## Development Model
+
+This repository uses Docker as the default local execution model.
+
+- Use `make build` to build the container image.
+- Use `make bash` when you need an interactive shell inside the container.
+- Use `make run` for an IPython session with project dependencies available.
+- Use `make test`, `make check`, and `make check-all` through the provided `make` targets.
+
+## Repository-Specific Expectations
+
+- Keep public API changes aligned with [`mpt_api_client/mpt_client.py`](../mpt_api_client/mpt_client.py) and the resource/service layout described in [architecture.md](architecture.md).
+- Keep resource-specific behavior inside the matching module under [`mpt_api_client/resources/`](../mpt_api_client/resources).
+- Keep transport and query behavior inside [`mpt_api_client/http/`](../mpt_api_client/http) and [`mpt_api_client/rql/`](../mpt_api_client/rql).
+- Add or update tests near the affected domain under [`tests/unit/`](../tests/unit) or [`tests/e2e/`](../tests/e2e).
+- When repository behavior changes, update the narrowest relevant document under [`docs/`](.).
+
+## Validation Before Review
+
+Follow the shared validation flow from
+[knowledge/build-and-checks.md](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/knowledge/build-and-checks.md).
+
+In this repository, run validation through the Docker-based targets documented in
+[testing.md](testing.md). Use `make build` first when dependencies or `uv.lock` change.

docs/contributing.md

@@ -0,0 +1,31 @@
+# Documentation
+
+This repository follows the shared documentation standard:
+
+- [standards/documentation.md](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/documentation.md)
+
+This file documents repository-specific documentation rules only.
+
+## Repository Rules
+
+- `README.md` must stay concise and act as the main human entry point.
+- `AGENTS.md` must stay operational and tell AI agents which files to read first.
+- Topic-specific documentation must live in the matching file under [`docs/`](.).
+- Shared engineering rules must be linked from `mpt-extension-skills` instead of copied into this repository.
+- When changing setup, usage, testing, or architecture behavior, update the corresponding document in the same change.
+- `docs/usage.md` is the source of truth for installation, configuration, examples, and supported command entry points.
+
+## Current Documentation Map
+
+- [`README.md`](../README.md): overview, quick start, and documentation map
+- [`AGENTS.md`](../AGENTS.md): AI-agent entry point and reading order
+- [`usage.md`](usage.md): install, configure, and use the client
+- [`architecture.md`](architecture.md): repository structure and major abstractions
+- [`local-development.md`](local-development.md): Docker-only local setup and execution
+- [`testing.md`](testing.md): repository-specific testing strategy
+- [`contributing.md`](contributing.md): repository workflow and shared-standard links
+- [`rql.md`](rql.md): RQL query builder guide
+
+## Change Rule
+
+Prefer updating the smallest relevant document instead of creating overlapping summary files.