aptitude-resolver 0.0.1__tar.gz

aptitude_resolver-0.0.1/PKG-INFO

@@ -0,0 +1,368 @@
+Metadata-Version: 2.3
+Name: aptitude-resolver
+Version: 0.0.1
+Summary: Deterministic package-manager-style resolver for AI skills
+Requires-Dist: diskcache>=5.6
+Requires-Dist: httpx>=0.27
+Requires-Dist: packaging>=24.0
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: ruff==0.15.9
+Requires-Dist: structlog>=25.0
+Requires-Dist: tenacity>=9.0
+Requires-Dist: tomli>=2.0 ; python_full_version < '3.11'
+Requires-Dist: typer>=0.12
+Requires-Dist: mypy>=1.0 ; extra == 'dev'
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.0.1 ; extra == 'dev'
+Requires-Python: >=3.9
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# Aptitude Resolver
+
+![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)
+![uv](https://img.shields.io/badge/uv-managed-6E56CF?style=for-the-badge&logo=uv&logoColor=white)
+![Pydantic](https://img.shields.io/badge/pydantic-E92063?style=for-the-badge&logo=pydantic&logoColor=white)
+![pytest](https://img.shields.io/badge/pytest-0A9EDC?style=for-the-badge&logo=pytest&logoColor=white)
+![Ruff](https://img.shields.io/badge/ruff-D7FF64?style=for-the-badge&logo=ruff&logoColor=111111)
+[![DeepWiki](https://img.shields.io/badge/Ask-DeepWiki-0A66C2?style=for-the-badge&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAAAsVBMVEVHcEwmWMYZy38Akt0gwZoSaFIbYssUmr4gwJkBlN4WbNE4acofwZkBj9k4aMkBk94WgM0bsIM4aMkewJc2ZMM3Z8cbvIwYpHsewJYAftgBkt0fvpgBkt0cv44cv5wzYckAjtsCk90pasUboXsgwJkfwpYfwJg4aMoct44yXswAkd0BkN84Z8cBktwduZIjcO85lM4hwZo5acoBleA6a88iyaABmOQ8b9QhxZ0CnOoizaOW4DOvAAAAMHRSTlMAKCfW%2FAgWA%2F7%2FDfvMc9j7MU%2Frj3XBcRW%2FJMbe7kUxjI%2FlUzzz6tPQkJ%2BjVmW1oeulmmslAAAByUlEQVQ4y32Tia6jIBSGUVFcqliXtlq73rm3d50ERNC%2B%2F4PNQetoptMeE0PgC%2F9%2FFhCaBSH9Hz2J%2BONgPDl2DolSUWY%2FPL8oEQRCfPxHpFc3Ah5wHoiI6I05NXgjAOgQF3Jn1Dlo4XMPDDes09UE2d%2BREvl3lijBg4CrHNmrbcM2u9u5nwsRcAFfFHFY5sZ607Yua3GqpQiKE6G9cZHZThblZ4T2mLnMxde3ATASMUj72o0Pbs1fADDcLHqAjEDugJ3lC%2BztMGYTADcoLaFyH%2B02DP9%2BWS4ahrXE4laALFKcq8vZfscNY8312mxfr27bLJZjnsYhSDIHmUxLu9h9N%2Fep%2B7pazwoZQw%2B1Nwi33epu7c2p8RooeqCdAHMGoOJIq3CUwIMEniRIaHVe3ZVnO2Vgsh1MstEkQUXVUc%2BjXfk3zbemxS6%2BpQmlPtUeALJ8VKj4JHvAelBqFFdSS3h1SPzQKr%2F%2BaRa0%2B0cCIWtJLauG5U%2FfbgyG01uiNqQhyzA8ddKj1OvK28AsZyN3DKE4X6AEWrU1jJx9N7RFpdPxpHU%2FtMOQG9SjfTp3Yz8KgRVKpfx88Dqhpseq606h%2F%2Bzxfh6LJ8eEDKWbxx9XEDwqzP1SVgAAAABJRU5ErkJggg%3D%3D)](https://deepwiki.com/y0ncha/aptitude-client)
+![Last Commit](https://img.shields.io/github/last-commit/aptitude-stack/resolver?style=for-the-badge)
+
+Aptitude is a deterministic, package-manager-style resolver for AI skills.
+
+The system is intentionally split in two:
+
+- Aptitude Server owns registry data, metadata, immutable artifacts, and discovery indexes
+- Aptitude owns intent interpretation, candidate selection, dependency resolution, governance, lock generation, and execution planning
+
+## Current CLI
+
+Primary commands:
+
+- `aptitude install "<query>"`
+- `aptitude sync --lock aptitude.lock.json`
+- `aptitude manifest`
+
+Internal preview command:
+
+- `aptitude resolve "<query>"`
+
+Running `aptitude` with no arguments launches the install-first wizard. `install` and `sync` stay as the promoted task commands, while `manifest` exposes the complete command and flag surface. `resolve` still exists for preview, debugging, and CI, but it is hidden from normal CLI help.
+
+## How To Install
+
+Install the resolver and its development dependencies with `uv`:
+
+```bash
+uv sync --extra dev
+```
+
+This creates the local environment from `pyproject.toml` and makes the `aptitude` entrypoint available through `uv run` or an activated environment.
+
+## Packaging And Publishing
+
+This project builds and publishes as a normal Python package. `uv` is the build and publish tool, and the release registry is PyPI. There is no separate special "uv registry" format.
+
+The packaging metadata lives in `pyproject.toml`:
+
+- `[project]` defines the package name, version, dependencies, and console entry point
+- `[project.scripts]` maps the installed `aptitude` command to `aptitude.interfaces.cli.main:main`
+- `[build-system]` tells `uv` to build the package with `uv_build`
+
+Build the package artifacts locally:
+
+```bash
+make package
+```
+
+`make package` runs `uv build --no-sources` and creates:
+
+```text
+dist/*.whl
+dist/*.tar.gz
+```
+
+The wheel is the main installable artifact. It contains the `aptitude` package, its dependency metadata, and the `aptitude` console script.
+
+For a local manual publish with a PyPI API token:
+
+```bash
+export PYPI_API_TOKEN=your-pypi-token
+make build-publish
+```
+
+`make build-publish`:
+
+- requires `PYPI_API_TOKEN`
+- builds fresh artifacts into `.build-publish-dist/`
+- publishes with `uv publish`
+- defaults to the production PyPI upload endpoint
+
+To rehearse the local flow against TestPyPI instead of production PyPI:
+
+```bash
+export PYPI_API_TOKEN=your-testpypi-token
+make build-publish REPOSITORY=testpypi
+```
+
+For the normal release path, publish to PyPI through GitHub Actions trusted publishing:
+
+```bash
+git tag v0.0.1
+git push origin v0.0.1
+```
+
+The release workflow lives at `.github/workflows/publish.yml` and:
+
+- triggers on tags matching `v*`
+- builds the wheel and sdist with `uv build --no-sources`
+- publishes with `pypa/gh-action-pypi-publish`
+- authenticates to PyPI with GitHub OIDC trusted publishing
+- does not use PyPI API tokens or repository secrets for the CI release path
+
+The publish job uses the GitHub Environment `pypi`. That is not required by PyPI itself, but it is recommended because it gives releases a dedicated protection boundary in GitHub.
+
+Install and run after publishing:
+
+```bash
+uv tool install aptitude
+aptitude --help
+```
+
+For one-off execution without a persistent install:
+
+```bash
+uvx aptitude --help
+```
+
+Use this mental model:
+
+- `make package` builds the distributable artifacts
+- `make build-publish` performs a local token-based publish to PyPI or TestPyPI
+- pushing a `v*` tag triggers the trusted publishing workflow
+- `uv tool install aptitude` installs the published CLI
+- `aptitude ...` is the command end users run after installation
+
+## How To Use
+
+For repo-local development, typical usage starts with one of these commands:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main --help
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main install "Postman Primary Skill"
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main sync --lock aptitude.lock.json
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main manifest
+```
+
+The no-args entrypoint launches the install-first wizard. Use `install` for fresh planning from a query, `sync --lock` for replaying an existing lockfile, and `manifest` for the full capability map. The help text and examples still use the logical `aptitude` command name, but the verified repo-local entrypoint is the module invocation above.
+
+For published usage, prefer the installed CLI:
+
+```bash
+aptitude --help
+aptitude install "Postman Primary Skill"
+aptitude sync --lock aptitude.lock.json
+aptitude manifest
+```
+
+## What Works Today
+
+- discovery-backed query resolution from human-readable input
+- resolver-owned candidate version selection
+- deterministic recursive dependency graph resolution
+- candidate-policy filtering and graph governance before lock generation
+- workspace policy loading from `aptitude.toml`
+- hard policy CLI overrides for fresh planning
+- rich lockfile generation, serialization, parsing, and replay
+- lock-driven execution plan generation
+- local materialization from either a fresh plan or an existing lockfile
+- `sync --lock` as the lock-replay equivalent of `uv sync`
+- registry caching and bounded transient retry
+- additive telemetry for planning and materialization stages
+- deterministic lockfiles for identical logical inputs
+- trace output for discovery, selection, resolver, lock, and execution steps
+
+## What Is Still Incomplete
+
+- organization-managed policy loading is not implemented yet
+- broader organization-specific rules are not implemented yet
+- winner-vs-runner-up explanation still derives from parallel explanation logic instead of directly from reranker output
+- `plugins/` extensibility is not implemented yet
+- MCP and SDK interfaces are not implemented yet
+
+## Selection, Governance, And Integrity Direction
+
+The canonical architecture now defines these required semantics:
+
+- server provides immutable metadata such as lifecycle, trust, token, size, and checksum facts
+- resolver owns policy and candidate selection
+- governance is split into:
+  - candidate-policy filtering before final ranking and final root selection
+  - full graph governance after resolution and before lock generation
+- ranking compares only policy-compliant candidates
+- phase 1 checksum verification uses server-published `sha256` checksum metadata and fails fast on mismatch
+
+Current code now implements Governance Phase 1, profile-aware ranking, and explainability snapshots. The canonical source of truth for remaining evolution lives under [docs/README.md](docs/README.md).
+
+## Current User Flows
+
+Fresh planning and install:
+
+```text
+install query
+-> discovery
+-> resolver
+-> governance
+-> lockfile
+-> execution plan
+-> materialization
+```
+
+Lock replay:
+
+```text
+sync --lock aptitude.lock.json
+-> lockfile parse
+-> lock replay
+-> execution plan
+-> materialization
+```
+
+## Example Commands
+
+Install from a query:
+
+```bash
+aptitude install "Postman Primary Skill"
+```
+
+Install as JSON for automation:
+
+```bash
+aptitude install "Postman Primary Skill" --json
+```
+
+Inspect the complete CLI surface:
+
+```bash
+aptitude manifest
+```
+
+Sync from an existing lockfile:
+
+```bash
+aptitude sync --lock aptitude.lock.json
+```
+
+Preview the resolved graph, lock, and execution plan without materializing:
+
+```bash
+uv run python -m aptitude.interfaces.cli.main resolve "Postman Primary Skill"
+```
+
+## Current Package Map
+
+```text
+src/aptitude/
+  application/
+    dto/
+    queries/
+    use_cases/
+  cache/
+  discovery/
+    intent/
+    query_builder/
+    reranking/
+  domain/
+    errors/
+    models/
+    policy/
+    tracing/
+  execution/
+  governance/
+  interfaces/
+    cli/
+  lockfile/
+  registry/
+  resolution/
+    conflict/
+    graph/
+    normalizer/
+    solver/
+    validation/
+  shared/
+    config/
+    logging/
+  telemetry/
+```
+
+## Current Registry Contract Used By The Resolver
+
+The resolver currently talks to the live registry through `registry/` using these runtime paths:
+
+- `POST /discovery`
+- `GET /skills/{slug}`
+- `GET /skills/{slug}/{version}`
+- `GET /resolution/{slug}/{version}`
+- `GET /skills/{slug}/{version}/content`
+
+The resolver treats the server as a source of immutable facts and candidate generation only. Final ranking, version choice, solving, policy enforcement, lock generation, and execution planning remain resolver-owned.
+
+## Development
+
+Requirements:
+
+- Python `>=3.9`
+
+Run the CLI:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main --help
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main install "Postman Primary Skill"
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main sync --lock aptitude.lock.json
+```
+
+Or via Python:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main --help
+```
+
+Developer workflow:
+
+```bash
+make help
+make format
+make format-check
+make lint
+make typecheck
+make test
+make test-cov
+make check
+```
+
+## Source Of Truth Docs
+
+Start with the docs index:
+
+- [docs/README.md](docs/README.md)
+
+The canonical architecture pair for future implementation work is:
+
+- [docs/architecture/system-overview.md](docs/architecture/system-overview.md)
+- [docs/architecture/decision-rules.md](docs/architecture/decision-rules.md)
+
+Before any non-trivial implementation or refactor, read both.
+
+Supporting docs:
+
+- [docs/contributors/README.md](docs/contributors/README.md)
+- [docs/reference/recommended-libraries.md](docs/reference/recommended-libraries.md)
+- [docs/roadmap/README.md](docs/roadmap/README.md)
+
+The `docs/reference/openapi/` directory is kept as raw server reference material, not as the sole source of truth for runtime behavior.

aptitude_resolver-0.0.1/README.md

@@ -0,0 +1,344 @@
+# Aptitude Resolver
+
+![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)
+![uv](https://img.shields.io/badge/uv-managed-6E56CF?style=for-the-badge&logo=uv&logoColor=white)
+![Pydantic](https://img.shields.io/badge/pydantic-E92063?style=for-the-badge&logo=pydantic&logoColor=white)
+![pytest](https://img.shields.io/badge/pytest-0A9EDC?style=for-the-badge&logo=pytest&logoColor=white)
+![Ruff](https://img.shields.io/badge/ruff-D7FF64?style=for-the-badge&logo=ruff&logoColor=111111)
+[![DeepWiki](https://img.shields.io/badge/Ask-DeepWiki-0A66C2?style=for-the-badge&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAAAsVBMVEVHcEwmWMYZy38Akt0gwZoSaFIbYssUmr4gwJkBlN4WbNE4acofwZkBj9k4aMkBk94WgM0bsIM4aMkewJc2ZMM3Z8cbvIwYpHsewJYAftgBkt0fvpgBkt0cv44cv5wzYckAjtsCk90pasUboXsgwJkfwpYfwJg4aMoct44yXswAkd0BkN84Z8cBktwduZIjcO85lM4hwZo5acoBleA6a88iyaABmOQ8b9QhxZ0CnOoizaOW4DOvAAAAMHRSTlMAKCfW%2FAgWA%2F7%2FDfvMc9j7MU%2Frj3XBcRW%2FJMbe7kUxjI%2FlUzzz6tPQkJ%2BjVmW1oeulmmslAAAByUlEQVQ4y32Tia6jIBSGUVFcqliXtlq73rm3d50ERNC%2B%2F4PNQetoptMeE0PgC%2F9%2FFhCaBSH9Hz2J%2BONgPDl2DolSUWY%2FPL8oEQRCfPxHpFc3Ah5wHoiI6I05NXgjAOgQF3Jn1Dlo4XMPDDes09UE2d%2BREvl3lijBg4CrHNmrbcM2u9u5nwsRcAFfFHFY5sZ607Yua3GqpQiKE6G9cZHZThblZ4T2mLnMxde3ATASMUj72o0Pbs1fADDcLHqAjEDugJ3lC%2BztMGYTADcoLaFyH%2B02DP9%2BWS4ahrXE4laALFKcq8vZfscNY8312mxfr27bLJZjnsYhSDIHmUxLu9h9N%2Fep%2B7pazwoZQw%2B1Nwi33epu7c2p8RooeqCdAHMGoOJIq3CUwIMEniRIaHVe3ZVnO2Vgsh1MstEkQUXVUc%2BjXfk3zbemxS6%2BpQmlPtUeALJ8VKj4JHvAelBqFFdSS3h1SPzQKr%2F%2BaRa0%2B0cCIWtJLauG5U%2FfbgyG01uiNqQhyzA8ddKj1OvK28AsZyN3DKE4X6AEWrU1jJx9N7RFpdPxpHU%2FtMOQG9SjfTp3Yz8KgRVKpfx88Dqhpseq606h%2F%2Bzxfh6LJ8eEDKWbxx9XEDwqzP1SVgAAAABJRU5ErkJggg%3D%3D)](https://deepwiki.com/y0ncha/aptitude-client)
+![Last Commit](https://img.shields.io/github/last-commit/aptitude-stack/resolver?style=for-the-badge)
+
+Aptitude is a deterministic, package-manager-style resolver for AI skills.
+
+The system is intentionally split in two:
+
+- Aptitude Server owns registry data, metadata, immutable artifacts, and discovery indexes
+- Aptitude owns intent interpretation, candidate selection, dependency resolution, governance, lock generation, and execution planning
+
+## Current CLI
+
+Primary commands:
+
+- `aptitude install "<query>"`
+- `aptitude sync --lock aptitude.lock.json`
+- `aptitude manifest`
+
+Internal preview command:
+
+- `aptitude resolve "<query>"`
+
+Running `aptitude` with no arguments launches the install-first wizard. `install` and `sync` stay as the promoted task commands, while `manifest` exposes the complete command and flag surface. `resolve` still exists for preview, debugging, and CI, but it is hidden from normal CLI help.
+
+## How To Install
+
+Install the resolver and its development dependencies with `uv`:
+
+```bash
+uv sync --extra dev
+```
+
+This creates the local environment from `pyproject.toml` and makes the `aptitude` entrypoint available through `uv run` or an activated environment.
+
+## Packaging And Publishing
+
+This project builds and publishes as a normal Python package. `uv` is the build and publish tool, and the release registry is PyPI. There is no separate special "uv registry" format.
+
+The packaging metadata lives in `pyproject.toml`:
+
+- `[project]` defines the package name, version, dependencies, and console entry point
+- `[project.scripts]` maps the installed `aptitude` command to `aptitude.interfaces.cli.main:main`
+- `[build-system]` tells `uv` to build the package with `uv_build`
+
+Build the package artifacts locally:
+
+```bash
+make package
+```
+
+`make package` runs `uv build --no-sources` and creates:
+
+```text
+dist/*.whl
+dist/*.tar.gz
+```
+
+The wheel is the main installable artifact. It contains the `aptitude` package, its dependency metadata, and the `aptitude` console script.
+
+For a local manual publish with a PyPI API token:
+
+```bash
+export PYPI_API_TOKEN=your-pypi-token
+make build-publish
+```
+
+`make build-publish`:
+
+- requires `PYPI_API_TOKEN`
+- builds fresh artifacts into `.build-publish-dist/`
+- publishes with `uv publish`
+- defaults to the production PyPI upload endpoint
+
+To rehearse the local flow against TestPyPI instead of production PyPI:
+
+```bash
+export PYPI_API_TOKEN=your-testpypi-token
+make build-publish REPOSITORY=testpypi
+```
+
+For the normal release path, publish to PyPI through GitHub Actions trusted publishing:
+
+```bash
+git tag v0.0.1
+git push origin v0.0.1
+```
+
+The release workflow lives at `.github/workflows/publish.yml` and:
+
+- triggers on tags matching `v*`
+- builds the wheel and sdist with `uv build --no-sources`
+- publishes with `pypa/gh-action-pypi-publish`
+- authenticates to PyPI with GitHub OIDC trusted publishing
+- does not use PyPI API tokens or repository secrets for the CI release path
+
+The publish job uses the GitHub Environment `pypi`. That is not required by PyPI itself, but it is recommended because it gives releases a dedicated protection boundary in GitHub.
+
+Install and run after publishing:
+
+```bash
+uv tool install aptitude
+aptitude --help
+```
+
+For one-off execution without a persistent install:
+
+```bash
+uvx aptitude --help
+```
+
+Use this mental model:
+
+- `make package` builds the distributable artifacts
+- `make build-publish` performs a local token-based publish to PyPI or TestPyPI
+- pushing a `v*` tag triggers the trusted publishing workflow
+- `uv tool install aptitude` installs the published CLI
+- `aptitude ...` is the command end users run after installation
+
+## How To Use
+
+For repo-local development, typical usage starts with one of these commands:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main --help
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main install "Postman Primary Skill"
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main sync --lock aptitude.lock.json
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main manifest
+```
+
+The no-args entrypoint launches the install-first wizard. Use `install` for fresh planning from a query, `sync --lock` for replaying an existing lockfile, and `manifest` for the full capability map. The help text and examples still use the logical `aptitude` command name, but the verified repo-local entrypoint is the module invocation above.
+
+For published usage, prefer the installed CLI:
+
+```bash
+aptitude --help
+aptitude install "Postman Primary Skill"
+aptitude sync --lock aptitude.lock.json
+aptitude manifest
+```
+
+## What Works Today
+
+- discovery-backed query resolution from human-readable input
+- resolver-owned candidate version selection
+- deterministic recursive dependency graph resolution
+- candidate-policy filtering and graph governance before lock generation
+- workspace policy loading from `aptitude.toml`
+- hard policy CLI overrides for fresh planning
+- rich lockfile generation, serialization, parsing, and replay
+- lock-driven execution plan generation
+- local materialization from either a fresh plan or an existing lockfile
+- `sync --lock` as the lock-replay equivalent of `uv sync`
+- registry caching and bounded transient retry
+- additive telemetry for planning and materialization stages
+- deterministic lockfiles for identical logical inputs
+- trace output for discovery, selection, resolver, lock, and execution steps
+
+## What Is Still Incomplete
+
+- organization-managed policy loading is not implemented yet
+- broader organization-specific rules are not implemented yet
+- winner-vs-runner-up explanation still derives from parallel explanation logic instead of directly from reranker output
+- `plugins/` extensibility is not implemented yet
+- MCP and SDK interfaces are not implemented yet
+
+## Selection, Governance, And Integrity Direction
+
+The canonical architecture now defines these required semantics:
+
+- server provides immutable metadata such as lifecycle, trust, token, size, and checksum facts
+- resolver owns policy and candidate selection
+- governance is split into:
+  - candidate-policy filtering before final ranking and final root selection
+  - full graph governance after resolution and before lock generation
+- ranking compares only policy-compliant candidates
+- phase 1 checksum verification uses server-published `sha256` checksum metadata and fails fast on mismatch
+
+Current code now implements Governance Phase 1, profile-aware ranking, and explainability snapshots. The canonical source of truth for remaining evolution lives under [docs/README.md](docs/README.md).
+
+## Current User Flows
+
+Fresh planning and install:
+
+```text
+install query
+-> discovery
+-> resolver
+-> governance
+-> lockfile
+-> execution plan
+-> materialization
+```
+
+Lock replay:
+
+```text
+sync --lock aptitude.lock.json
+-> lockfile parse
+-> lock replay
+-> execution plan
+-> materialization
+```
+
+## Example Commands
+
+Install from a query:
+
+```bash
+aptitude install "Postman Primary Skill"
+```
+
+Install as JSON for automation:
+
+```bash
+aptitude install "Postman Primary Skill" --json
+```
+
+Inspect the complete CLI surface:
+
+```bash
+aptitude manifest
+```
+
+Sync from an existing lockfile:
+
+```bash
+aptitude sync --lock aptitude.lock.json
+```
+
+Preview the resolved graph, lock, and execution plan without materializing:
+
+```bash
+uv run python -m aptitude.interfaces.cli.main resolve "Postman Primary Skill"
+```
+
+## Current Package Map
+
+```text
+src/aptitude/
+  application/
+    dto/
+    queries/
+    use_cases/
+  cache/
+  discovery/
+    intent/
+    query_builder/
+    reranking/
+  domain/
+    errors/
+    models/
+    policy/
+    tracing/
+  execution/
+  governance/
+  interfaces/
+    cli/
+  lockfile/
+  registry/
+  resolution/
+    conflict/
+    graph/
+    normalizer/
+    solver/
+    validation/
+  shared/
+    config/
+    logging/
+  telemetry/
+```
+
+## Current Registry Contract Used By The Resolver
+
+The resolver currently talks to the live registry through `registry/` using these runtime paths:
+
+- `POST /discovery`
+- `GET /skills/{slug}`
+- `GET /skills/{slug}/{version}`
+- `GET /resolution/{slug}/{version}`
+- `GET /skills/{slug}/{version}/content`
+
+The resolver treats the server as a source of immutable facts and candidate generation only. Final ranking, version choice, solving, policy enforcement, lock generation, and execution planning remain resolver-owned.
+
+## Development
+
+Requirements:
+
+- Python `>=3.9`
+
+Run the CLI:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main --help
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main install "Postman Primary Skill"
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main sync --lock aptitude.lock.json
+```
+
+Or via Python:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m aptitude.interfaces.cli.main --help
+```
+
+Developer workflow:
+
+```bash
+make help
+make format
+make format-check
+make lint
+make typecheck
+make test
+make test-cov
+make check
+```
+
+## Source Of Truth Docs
+
+Start with the docs index:
+
+- [docs/README.md](docs/README.md)
+
+The canonical architecture pair for future implementation work is:
+
+- [docs/architecture/system-overview.md](docs/architecture/system-overview.md)
+- [docs/architecture/decision-rules.md](docs/architecture/decision-rules.md)
+
+Before any non-trivial implementation or refactor, read both.
+
+Supporting docs:
+
+- [docs/contributors/README.md](docs/contributors/README.md)
+- [docs/reference/recommended-libraries.md](docs/reference/recommended-libraries.md)
+- [docs/roadmap/README.md](docs/roadmap/README.md)
+
+The `docs/reference/openapi/` directory is kept as raw server reference material, not as the sole source of truth for runtime behavior.