Fix/on boarding

[eschaar]

Summary

Improves the first-install experience for users who already have files in .github/, fixes documentation consistency issues found across the full doc set, and hardens the PyPI publish pipeline.

CLI — dry-run conflict resolution (feat(cli))

• vstack install --dry-run now prints a consistent per-file prefix (install, update, skip, preserve, adopt) and a structured summary block with action counters.
• Preserved files are listed as type/name selectors (e.g. agent/engineer, skill/verify) so users can resolve each conflict selectively with --force-name or --adopt-name.
• --force-name and --adopt-name both accept type/name selectors for disambiguation when multiple artifact types share a name.
• Adds unit tests for _print_summary and integration test asserting type/name selectors appear in --dry-run stdout.

User-facing docs (patch(docs))

• README and README-pypi: added first-install dry-run workflow section and troubleshooting entry for preserved files.
• --force-name / --adopt-name examples updated to show type/name selector syntax.

ADR consistency (chore(docs))

• Maintainer role corrected from agents → architect across all 12 ADRs.
• ADR-007: replaced stale scripts/ paths and package.json reference with current src/vstack/ structure; Python range updated to 3.11–3.14.
• ADR-008: updated tool names, removed dead TOOL_MAP, gen_skill_docs.py, and scripts/runner.py references.
• ADR-010: added 4th gate (Merge approval); removed stale scripts/runner.py reference.
• ADR-011: status changed from planned for v0.5.0 → implemented; guardrails disposition clarified as "retained as active skill".

Design doc consistency (chore(docs))

• BaseCommand.run() signature fixed (run(args,...) → run(*, context: CommandContext) -> int) in architecture.md and design.md.
• CLI dispatch flow diagram and component table updated.
• model field type corrected (string → string or list).
• Stale {{API_CONTRACT_CHECKLIST}} placeholder removed.
• security skill primary role corrected: engineer → tester.
• roadmap.md: 6 v2.0.0 shipped features added.
• CONTRIBUTING.md: make test → make test-local, make bootstrap note, make targets table, 100% coverage requirement.
• SECURITY.md: 2.x: Yes / 1.x: No support matrix updated.
• Module docstrings updated: CommandService and ArtifactGenerator.

CI (chore(ci))

• publish.yml: added trusted publishing with API token fallback and publish-pypi concurrency group.

Deps (chore(deps))

• cachetools 7.0.6 → 7.1.0, tox 4.53.0 → 4.53.1.

Why

Users with pre-existing .github/ files had no clear way to understand what install would skip or how to resolve preserved files selectively. The dry-run output now gives a complete picture and actionable next steps. The documentation fixes address consistency gaps found during a full doc review.

Version impact

• None
• Patch
• Minor
• Major

[Copilot]

Pull request overview

Improves the vstack first-install experience (especially when .github/ already contains files) by making install --dry-run output more actionable, while also aligning repository documentation/ADRs and hardening the PyPI publish workflow.

Changes:

• Enhance vstack install --dry-run with consistent per-artifact action output plus a structured summary (including type/name preserved selectors).
• Update docs/ADRs/roadmap for role naming, CLI architecture signatures, and current repo structure.
• Harden PyPI publish workflow (trusted publishing + fallback) and bump dev dependencies.

Reviewed changes

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

Show a summary per file

File	Description
tests/vstack/test_integration.py	Adds integration coverage asserting preserved selector output includes type/name.
tests/vstack/cli/test_install.py	Adds unit tests for install summary rendering and install action return values.
src/vstack/cli/service.py	Updates module docstring to match current CLI architecture.
src/vstack/cli/parser.py	Extends --force-name / --adopt-name help/metavar to support type/name selectors.
src/vstack/cli/install.py	Implements action counting + preserved selectors summary; supports type/name targeting in install decisions.
src/vstack/artifacts/protocol.py	Updates ArtifactGenerator protocol docstring to reflect all generator implementers.
poetry.lock	Bumps cachetools and tox versions.
docs/product/roadmap.md	Updates roadmap feature table and adds v2.0.0 shipped feature sections.
docs/design/skills.md	Corrects primary role for the security skill.
docs/design/design.md	Fixes CLI dispatch/run signature docs, updates diagrams/tables, removes stale placeholder.
docs/architecture/architecture.md	Aligns BaseCommand contract docs and removes stale placeholder mention.
docs/architecture/adr/012-flat-templates-install-time-generation.md	Maintainer role corrected to architect.
docs/architecture/adr/011-skill-restructure.md	Maintainer role corrected; status updated; clarifies guardrails disposition.
docs/architecture/adr/010-artifact-flow.md	Maintainer role corrected; adds 4th gate; removes stale runner reference.
docs/architecture/adr/009-role-model.md	Maintainer role corrected to architect.
docs/architecture/adr/008-agents-over-prompts.md	Maintainer role corrected; updates tool names/structure references.
docs/architecture/adr/007-python-runtime.md	Maintainer role corrected; updates repo structure and supported Python range.
docs/architecture/adr/006-no-runtime-dependency.md	Maintainer role corrected to architect.
docs/architecture/adr/005-vscode-prompt-format.md	Maintainer role corrected to architect.
docs/architecture/adr/004-option-a-to-b-pipeline.md	Maintainer role corrected to architect.
docs/architecture/adr/003-backend-first-verify.md	Maintainer role corrected to architect.
docs/architecture/adr/002-artifact-naming-and-compatibility-policy.md	Maintainer role corrected to architect.
docs/architecture/adr/001-vscode-native-variant.md	Maintainer role corrected to architect.
SECURITY.md	Updates support matrix to reflect 2.x supported and 1.x unsupported.
README.md	Adds first-install dry-run workflow and preserved-files troubleshooting; updates examples for type/name.
README-pypi.md	Mirrors README install guidance updates in a PyPI-safe form.
CONTRIBUTING.md	Updates developer commands (make test-local, make check) and documents 100% coverage requirement.
CHANGELOG.md	Normalizes bullet formatting for recent release entries.
.github/workflows/publish.yml	Adds publish concurrency + trusted publishing with API token fallback.
.github/copilot-instructions.md	Documents canonical dev commands and CLI architecture conventions for contributors/agents.