1.2.1, 3/4: issue forms, PR template, the pyz rule and a social preview

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,51 @@
+name: Bug report
+description: shim-cli did something wrong, or did not do what the docs say.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Do not paste a real secret or real personal data here, not even a revoked one.**
+        Use a synthetic example instead: `AKIAIOSFODNN7EXAMPLE`, `ops@example.com`,
+        `GB82WEST12345698765432`. This issue is public.
+  - type: input
+    id: version
+    attributes:
+      label: shim version
+      description: The output of `shim --version`, or the plugin version if you use only the plugin.
+      placeholder: shim 1.2.1
+    validations:
+      required: true
+  - type: input
+    id: client
+    attributes:
+      label: Client and its version
+      placeholder: Claude Code 2.1.286, Codex CLI 0.159.0, GitHub Copilot CLI 1.0.85 or VS Code 1.140.0
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: macOS 26.4 arm64, Ubuntu 24.04 x86_64
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: shim doctor output
+      description: The output of `shim doctor <client> --json` (VS Code has no doctor target; leave this empty). It holds paths on your machine; edit your user name out if you like.
+      render: json
+  - type: textarea
+    id: steps
+    attributes:
+      label: What you did
+      description: The commands or the prompt, with synthetic values.
+    validations:
+      required: true
+  - type: textarea
+    id: result
+    attributes:
+      label: What you expected, and what happened
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/GetSHIM/shim-cli/security/advisories/new
+    about: Report it privately through a GitHub security advisory, as SECURITY.md describes. Not in a public issue.

.github/ISSUE_TEMPLATE/detection_report.yml

@@ -0,0 +1,50 @@
+name: Detection report (missed or false positive)
+description: shim missed a value it should find, or flagged one it should not.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        A value shim missed is the report we value most: it is the one nobody else sees.
+
+        **Do not paste a real secret or real personal data.** Build a synthetic value with the
+        same shape: same prefix, same length, same separators, made-up digits.
+        This issue is public.
+  - type: dropdown
+    id: kind
+    attributes:
+      label: What happened
+      options:
+        - Missed (a value that should be found was not)
+        - False positive (something that is not sensitive was flagged)
+    validations:
+      required: true
+  - type: input
+    id: entity
+    attributes:
+      label: Entity type
+      description: The type shim should or should not have reported, such as SECRET, EMAIL, IBAN, PHONE or TR_NATIONAL_ID.
+    validations:
+      required: true
+  - type: textarea
+    id: example
+    attributes:
+      label: Synthetic example
+      description: The smallest text that shows it, with a made-up value, and where it came from (a typed prompt, a file the agent read, command output).
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: result
+    attributes:
+      label: Expected and seen
+      description: What you expected, and what `echo '<your example>' | shim redact` or `shim scan --json` printed.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: shim version
+      placeholder: shim 1.2.1
+    validations:
+      required: true

.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## What changes
+
+<!-- The behaviour a user sees before and after. -->
+
+## Checks
+
+- [ ] `python scripts/check.py` is green (paste the test count):
+- [ ] Docs updated where behaviour changed (README, `docs/commands.md`, `docs/privacy.md`, `docs/compatibility.md`), or no user-visible change
+- [ ] Only synthetic values in tests and examples
+- [ ] `plugins/shim-cli/bin/shim.pyz` is not rebuilt (only a release commit rebuilds it)

.github/workflows/ci.yml

@@ -129,3 +129,28 @@ jobs:
               <(answer '${{ steps.floor.outputs.python-path }}' "$fixture") \
               <(answer '${{ steps.current.outputs.python-path }}' "$fixture")
           done
+  archive-follows-version:
+    # The marketplace installs the plugin from main, so a shim.pyz rebuilt
+    # without a release ships unreleased code to plugin users.
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: The plugin archive changes only with the version
+        env:
+          BASE: ${{ github.event.pull_request.base.sha }}
+        run: |
+          set -eu
+          if git diff --quiet "$BASE" HEAD -- plugins/shim-cli/bin/shim.pyz; then
+            exit 0
+          fi
+          if git diff "$BASE" HEAD -- pyproject.toml | grep -q '^+version = '; then
+            exit 0
+          fi
+          echo "plugins/shim-cli/bin/shim.pyz changed without a version change in pyproject.toml."
+          echo "Only a release commit rebuilds the archive (CONTRIBUTING.md, The plugin archive)."
+          exit 1

AGENTS.md

@@ -29,6 +29,8 @@ Apply the `ponytail:ponytail` and `code-writing-guidelines` skills to every impl
   `guard/entities.py`; malformed or unsafe settings fail closed, and no
   settings field may contain prompt-derived data.
 - Never modify real user configuration in development or tests; use temporary paths.
+- Rebuild `plugins/shim-cli/bin/shim.pyz` only in a release commit: the plugin
+  installs from `main`, so a rebuilt archive ships unreleased code to its users.
 - This repository is public and much of its documentation and corpus comes from
   running the tool for real. Nothing committed may carry the machine it was
   written on — a home directory, an editor path, a scratch directory, a

CONTRIBUTING.md

@@ -13,3 +13,20 @@ python scripts/check.py
 Use synthetic values in tests and examples. Never commit real prompts, secrets,
 or personal data. Changes to hook output, supported entities, installation, or
 compatibility claims need contract and documentation updates.
+
+## Issues
+
+Open an issue at <https://github.com/GetSHIM/shim-cli/issues/new/choose>: a
+bug report, or a detection report for a value shim missed or flagged by
+mistake. Paste synthetic values only; the issue is public. A missed value is
+the most useful report you can send. Security vulnerabilities go through a
+private advisory, as [SECURITY.md](SECURITY.md) describes, never an issue.
+
+## The plugin archive
+
+`plugins/shim-cli/bin/shim.pyz` is rebuilt only in a release commit, with
+`scripts/build_zipapp.py`. The Claude Code marketplace installs the plugin from
+`main`, so an archive rebuilt between releases would ship unreleased code to
+plugin users while PyPI still serves the last release. A pull request that is
+not a release leaves the archive alone; CI fails one that changes the archive
+without changing the version in `pyproject.toml`.