Set up PyPI publishing via GitHub Actions

[anormang1992]

Summary

Enables release-triggered publishing to PyPI. When a GitHub release is published (with a tag matching v*), a workflow runs CI and then publishes the built package to PyPI via OIDC trusted publishing — no API tokens required.

Also overhauls the README around a clearer narrative arc (problem -> concepts -> getting started -> core API -> integrations) with a table of contents, and reframes the examples/ directory as reference material rather than shipped code.

Changes

• Add .github/workflows/publish.yml — CI job (lint + test) followed by a publish job gated on the pypi environment, using pypa/gh-action-pypi-publish with OIDC
• Standardize release trigger on release: types: [published] so releases created from the GitHub UI drive the flow
• Add readme = "README.md" to pyproject.toml so PyPI renders project context on first publish
• Bump version to 0.4.3 in preparation for the first PyPI release
• Restructure README with TOC, consolidated policy section, and clearer framing of examples as reference integrations (not part of the vre package)

VRE Design Alignment

Infrastructure / documentation only. No changes to grounding, policy evaluation, gap detection, primitives, relation types, or depth semantics. Epistemic honesty invariants are unaffected.

Test Plan

• Merge, then create a v0.4.3 release from the GitHub UI
• Confirm ci job passes
• Confirm publish job runs in the pypi environment and succeeds
• Confirm the project appears at https://pypi.org/project/vre/ with the README rendered

Notes

• PyPI trusted publisher must be registered (pending publisher with workflow publish.yml, environment pypi) before the first release — done out-of-band.
• GitHub pypi environment is configured with a deployment tag rule (v*), so arbitrary branches cannot trigger a publish.
• No secrets are stored in the repo; authentication is via short-lived OIDC tokens on each run.

[Copilot]

Pull request overview

Sets up automated, release-driven publishing to PyPI (using GitHub Actions + OIDC trusted publishing) and refreshes project packaging metadata/documentation so the first PyPI release renders correctly and has updated guidance.

Changes:

• Add a release-triggered GitHub Actions workflow that runs CI and then publishes to PyPI from a protected pypi environment.
• Update pyproject.toml with readme = "README.md" and bump version to 0.4.3.
• Restructure/expand the README with a TOC and updated “getting started” + integrations narrative.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
pyproject.toml	Bumps version and configures PyPI to render README.md.
README.md	Major documentation rewrite/restructure (TOC, onboarding flow, integrations framing).
.github/workflows/publish.yml	Adds the release-triggered CI + PyPI publish workflow using OIDC.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.