docs(pypi): align 1.3.5 changelog and package metadata

Author: eschaar

.github/copilot-instructions.md

@@ -113,6 +113,14 @@ For hand-authored Markdown in this repository, treat baseline docs as a coherent
 - Prefer consistency across related docs: if `README.md`, architecture docs, and workflow docs describe the same flow, they should use compatible terminology and diagram style.
 - When modernizing older docs, convert diagrams selectively rather than mechanically. Preserve useful content first, then improve presentation.
 
+## PyPI README Sync Rules
+
+- `README.md` is the canonical full documentation for GitHub rendering.
+- `README-pypi.md` is the PyPI-compatible long description source referenced by `pyproject.toml`.
+- Whenever `README.md` changes in a way that affects installation, usage, positioning, links, or badges, update `README-pypi.md` in the same change.
+- Keep `README-pypi.md` minimal and PyPI-safe: no Mermaid blocks, no relative documentation links, and no `<picture>` markup.
+- Use absolute GitHub URLs in `README-pypi.md` for cross-document links and images.
+
 ## Python Docstring Style
 
 For Python modules in this repository, treat code as the source of truth and keep docstrings aligned with shipped behavior.

CHANGELOG.md

@@ -2,11 +2,18 @@
 
 ## 1.3.5 - 2026-04-22
 
-Changelog alignment update.
+Changelog and PyPI packaging metadata alignment update.
 
 ### Changed in 1.3.5
 
 - Corrected changelog version history from 1.3.0 onward so entries align with actual created tags and release chronology.
+- Switched published long description source from `README.md` to `README-pypi.md` for PyPI-compatible rendering.
+- Added PyPI-focused project metadata in `pyproject.toml`: `keywords`, `classifiers`, and `project.urls`.
+- Added explicit repository guidance to keep `README-pypi.md` in sync with `README.md`.
+
+### Added in 1.3.5
+
+- Added a dedicated `README-pypi.md` with PyPI-safe links, badges, and a concise DX-first quickstart.
 
 ## 1.3.4 - 2026-04-22
 

README-pypi.md

@@ -0,0 +1,96 @@
+# vstack
+
+[![PyPI version](https://img.shields.io/pypi/v/vstack?color=0B8A6F)](https://pypi.org/project/vstack/)
+[![Python version](https://img.shields.io/badge/python-3.11--3.14-0B8A6F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml)
+[![Verify status](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/verify.yml?branch=main&label=verify&color=1D6FA5)](https://github.com/eschaar/vstack/actions/workflows/verify.yml)
+[![Security checks](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/security.yml?branch=main&label=security&color=B15E00)](https://github.com/eschaar/vstack/actions/workflows/security.yml)
+[![Runtime: stdlib only](https://img.shields.io/badge/runtime-stdlib%20only-5B6C8F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/github/license/eschaar/vstack?color=5F7A1F)](https://github.com/eschaar/vstack/blob/main/LICENSE)
+[![GitHub Discussions](https://img.shields.io/badge/discussions-ask%20%26%20share-blueviolet?logo=github)](https://github.com/eschaar/vstack/discussions)
+
+![vstack logo](https://raw.githubusercontent.com/eschaar/vstack/main/assets/branding/vstack.png)
+
+The VS Code-native AI workflow system for backend engineering.
+
+vstack installs structured agents, skills, instructions, and prompts into `.github/` so GitHub Copilot Agent Mode can run repeatable backend workflows with clear role boundaries.
+
+It provides a fixed role model for end-to-end software delivery: `product`, `architect`, `designer`, `engineer`, `tester`, and `release`.
+
+## Best for
+
+- Backend and API teams using GitHub Copilot Agent Mode in VS Code
+- Repositories that want consistent planning, implementation, verification, and release flow
+- Teams that want reusable AI workflows instead of one-off prompt crafting
+
+## What you get
+
+- Fixed role model: `product`, `architect`, `designer`, `engineer`, `tester`, `release`
+- Template-driven install model from `src/vstack/_templates/`
+- Backend-first verification, security, and release discipline
+- Standard-library-only runtime dependencies
+
+## Quick start
+
+Install with `pipx`, then install vstack artifacts into your repository:
+
+```bash
+pipx install vstack
+vstack install --target /path/to/your/project
+vstack validate
+```
+
+Run a first task in Copilot Agent Mode:
+
+```text
+@tester /verify Check this repository and summarize findings
+```
+
+Expected result:
+
+- `vstack validate` reports no unresolved template tokens
+- Agent command returns a concrete verification summary for your repository
+
+## Why this helps
+
+- Consistent role boundaries for planning, implementation, validation, and release
+- Reusable skills and instructions instead of ad hoc prompts
+- Better release hygiene with documented workflows and CI alignment
+
+## Core commands
+
+```bash
+vstack --version
+vstack validate
+vstack install --target /path/to/your/project
+vstack verify --target /path/to/your/project
+```
+
+## Common usage patterns
+
+Repository-scoped install (recommended for teams):
+
+```bash
+vstack install --target /path/to/your/project
+```
+
+Profile-wide install (optional defaults for all projects):
+
+```bash
+vstack install --global
+```
+
+## Fast troubleshooting
+
+- Command not found after install: ensure your `pipx` binary path is in `PATH`
+- Validation error: rerun `vstack install --target ...` and then `vstack validate`
+- Agent results look generic: explicitly invoke a role (for example `@tester`) before a skill
+
+## Full documentation
+
+For complete documentation (including architecture details, workflow diagrams, and contributor guides), use GitHub:
+
+- [GitHub repository](https://github.com/eschaar/vstack)
+- [Full README](https://github.com/eschaar/vstack/blob/main/README.md)
+- [Documentation](https://github.com/eschaar/vstack/tree/main/docs)
+- [Contributing guide](https://github.com/eschaar/vstack/blob/main/CONTRIBUTING.md)
+- [Security policy](https://github.com/eschaar/vstack/blob/main/SECURITY.md)

pyproject.toml

@@ -3,9 +3,44 @@ name = "vstack"
 dynamic = ["version"]
 description = "VS Code-native AI engineering workflow system for microservices, libraries, and backend systems."
 license = "MIT"
-readme = "README.md"
+readme = "README-pypi.md"
 requires-python = ">=3.11,<3.15"
 dependencies = []
+keywords = [
+    "github-copilot",
+    "vscode",
+    "ai-workflows",
+    "developer-tools",
+    "devx",
+    "engineering-workflow",
+    "copilot-agent-mode",
+    "backend",
+    "microservices",
+    "api",
+    "workflow-automation",
+    "release-engineering",
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/eschaar/vstack"
+Documentation = "https://github.com/eschaar/vstack/blob/main/README.md"
+Repository = "https://github.com/eschaar/vstack"
+Issues = "https://github.com/eschaar/vstack/issues"
+Changelog = "https://github.com/eschaar/vstack/blob/main/CHANGELOG.md"
+Discussions = "https://github.com/eschaar/vstack/discussions"
+Security = "https://github.com/eschaar/vstack/blob/main/SECURITY.md"
 
 [project.scripts]
 vstack = "vstack:main"