Complete uvs hardening and prepare for public feedback

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,86 @@
+name: Bug report
+description: Report reproducible behavior that appears to violate the supported contract.
+title: "Bug: "
+labels:
+  - bug
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a problem. For suspected vulnerabilities, use [private vulnerability reporting](https://github.com/maphew/uvs/security/advisories/new) instead.
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: What happened?
+      description: Briefly describe the problem and its impact.
+    validations:
+      required: true
+
+  - type: input
+    id: uvs_version
+    attributes:
+      label: uvs version or commit
+      placeholder: "0.1.0 or commit SHA"
+    validations:
+      required: true
+
+  - type: input
+    id: uv_version
+    attributes:
+      label: uv version
+      placeholder: "Output of: uv --version"
+    validations:
+      required: true
+
+  - type: input
+    id: python_version
+    attributes:
+      label: Python version
+      placeholder: "Output of: python --version"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: operating_system
+    attributes:
+      label: Operating system
+      options:
+        - Windows
+        - Linux
+        - macOS
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Include the smallest safe script and exact commands that reproduce the problem. Remove secrets and personal paths.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior and complete error output
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional_context
+    attributes:
+      label: Additional context
+      description: Add anything else that may help, including how uvs was installed.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+blank_issues_enabled: true
+contact_links: []

.github/ISSUE_TEMPLATE/usefulness-feedback.yml

@@ -0,0 +1,58 @@
+name: Usefulness or design feedback
+description: Tell us whether uvs helps with a real job, falls short, or should work differently.
+title: "Feedback: "
+labels: []
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Candid feedback is welcome, including that the project is not useful for your situation. Concrete experience is more helpful than enthusiasm alone.
+
+  - type: textarea
+    id: job
+    attributes:
+      label: What job were you trying to do?
+      description: Describe the outcome you needed, independently of uvs.
+    validations:
+      required: true
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: How do you handle this today?
+      description: Describe your current command, tool, manual process, or decision not to solve it.
+    validations:
+      required: true
+
+  - type: textarea
+    id: experience
+    attributes:
+      label: What did uvs help with or get in the way of?
+      description: Include what you tried and where the idea, interface, or documentation succeeded or failed.
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Relevant environment
+      description: If applicable, include your OS, Python version, uv version, and the shape of the script or workflow.
+    validations:
+      required: false
+
+  - type: textarea
+    id: change
+    attributes:
+      label: What change, if any, would make it useful?
+      description: A proposed solution is optional; the underlying need matters most.
+    validations:
+      required: false
+
+  - type: textarea
+    id: tradeoffs
+    attributes:
+      label: Trade-offs or alternatives
+      description: Note any added complexity, compatibility concern, or alternative design worth considering.
+    validations:
+      required: false

.github/workflows/tests.yml

@@ -0,0 +1,46 @@
+---
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # v5
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync locked development environment
+        run: uv sync --dev --locked
+
+      - name: Run fast test suite
+        run: uv run pytest -m "not integration"
+
+      - name: Run real integration tests serially
+        run: uv run pytest -m integration -n 0

AGENTS.md

@@ -165,8 +165,15 @@ integration suite. Do not describe mocked subprocess workflows as end-to-end.
 
 ## Architecture Overview
 
-_Add a brief overview of your project architecture_
+`src/uvs/uvs.py` owns PEP 723 parsing, disposable package generation, registry
+persistence, and the `uv` subprocess boundary. `src/uvs/cli.py` exposes the
+Click subcommands and user-facing output. Fast tests isolate external state;
+`tests/integration/` redirects all uv/uvs state and exercises the real lifecycle.
 
 ## Conventions & Patterns
 
-_Add your project-specific conventions here_
+- Preserve supported script source verbatim; installation has snapshot semantics.
+- Keep uv as the owner of tool environments and executables; the uvs registry
+  stores only source mapping and update metadata.
+- Route errors to stderr, keep JSON undecorated, and run real lifecycle tests
+  serially with every user-state directory redirected.

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+This project is not yet published on PyPI. The repository can be installed
+directly as described in the README.
+
+## Unreleased
+
+- Reframe the public documentation around testing whether the project is useful.
+- Add lightweight paths for bug reports, usefulness feedback, contributions, and
+  private security reports.
+- Reject ambiguous batch naming and clean up an installed tool when registry
+  persistence fails.
+
+## 0.1.0 - 2026-07-14
+
+- Install supported single-file PEP 723 scripts as persistent uv tools.
+- Track canonical source paths and update changed snapshots with patch versions.
+- List, inspect, and uninstall tools through a deterministic subcommand CLI.
+- Recover valid data from old or damaged registries with atomic, serialized writes.
+- Support Python 3.10+ with real lifecycle CI on Windows and Linux.

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing to uvs
+
+`uvs` is an experimental, one-maintainer project. Reports from real use,
+criticism of the underlying idea, documentation fixes, tests, and small focused
+code changes are all welcome. Feedback that the tool is not useful is valuable
+too, especially when it describes the job you were trying to do.
+
+## Scope
+
+The supported contract is intentionally narrow: `uvs` turns one Python file
+with a synchronous, top-level `main()` into a snapshot installed through
+`uv tool`. See the [README](README.md#supported-script-contract) and the
+[product contract](docs/adr/0001-uvs-product-contract.md) for details.
+
+Packaging sibling modules or data files, accepting arbitrary Python projects,
+publishing packages, and replacing `uv tool` management are non-goals.
+Proposals may be declined when they fall outside that scope, add more ongoing
+maintenance than their benefit supports, or lack enough evidence to justify a
+larger interface. That is a product trade-off, not a judgment on the
+contribution.
+
+Use the GitHub issue forms for bugs and usefulness or design feedback. Small,
+focused pull requests are easier to evaluate; consider opening an issue before
+investing in a broad change. The project has no promised roadmap or response
+schedule.
+
+## Quality gates
+
+Create the locked development environment and run the fast suite:
+
+```console
+uv sync --dev --locked
+uv run pytest
+```
+
+Changes that affect installation or lifecycle behavior should also pass the
+real integration suite, run serially:
+
+```console
+uv run pytest -m integration -n 0
+```
+
+See the [test inventory](docs/testing.md) for what each suite proves.