Open the project to contributors

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,81 @@
+name: Bug report
+description: Something in the app behaved wrongly. For a bad crop use the detection template instead.
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ⚠️ **Never attach a card scan.** Paste text, or a screenshot with any
+        card artwork cropped out.
+
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened
+      description: What you did, what you expected, and what you got instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: >
+        If you can reproduce it with `bash Scripts/bundle-app.sh --synthetic`,
+        say so — that means anyone can fix it without a scanner, which makes it
+        far more likely to get fixed quickly.
+      value: |
+        1.
+        2.
+        3.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: how_run
+    attributes:
+      label: How were you running ScanDeck?
+      options:
+        - "bash Scripts/bundle-app.sh --run (real scanner)"
+        - "bash Scripts/bundle-app.sh --synthetic (no scanner)"
+        - "swift run ScanDeck"
+        - "swift run scandeck-m0 (command line)"
+    validations:
+      required: true
+
+  - type: markdown
+    attributes:
+      value: |
+        If you chose `swift run ScanDeck` and the symptom is that **typing does
+        nothing**: that is a known trap rather than a bug. A bare SwiftPM
+        executable registers as background-only and receives no keyboard events.
+        Use `bash Scripts/bundle-app.sh --run` instead and check with
+        `lsappinfo list | grep -A4 ScanDeck` that you get `type="Foreground"`.
+
+  - type: input
+    id: versions
+    attributes:
+      label: macOS version, and scanner if one was attached
+      placeholder: "macOS 26.5.2, fi-8170"
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Diagnostics report
+      description: >
+        Settings → Copy Diagnostics Report. Content-free by construction — no
+        path, file name or batch name can reach it.
+      render: shell
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: safety
+    attributes:
+      label: Before you submit
+      options:
+        - label: I have not attached any card scan or personal data
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: How changes land, and what to expect back
+    url: https://github.com/eliseorobles/ScanDeck/blob/main/CONTRIBUTING.md
+    about: Branch, PR, review. Also which changes want an issue opened first, and whether you need a scanner (usually not).
+  - name: Will my scanner work?
+    url: https://github.com/eliseorobles/ScanDeck/blob/main/README.md#about-scanner-support
+    about: Only the fi-8170 today. If you have something else, open a hardware datapoint — that is how the list grows.

.github/ISSUE_TEMPLATE/detection-report.yml

@@ -0,0 +1,100 @@
+name: ScanDeck measured a card wrong
+description: A crop clipped the card, kept too much, or the two sides disagreed when they should not have.
+title: "[detection] "
+labels: ["detection", "image-pipeline"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This is the bug class the project cares most about, because it is the one
+        that can publish a wrong image that still looks plausible.
+
+        ⚠️ **Do not attach the scan.** Card images are your property. Everything
+        below is numbers and text, which is all we need to reproduce the
+        reasoning — and if it turns out we need pixels, we will talk about how to
+        share them privately rather than in a public issue.
+
+  - type: dropdown
+    id: symptom
+    attributes:
+      label: What went wrong?
+      options:
+        - The crop cut into the card
+        - The crop kept far too much background
+        - The two sides of one card measured very differently
+        - Complete Batch was blocked and I think it should not have been
+        - Complete Batch was allowed and I think it should not have been
+        - The card published visibly crooked
+        - Something else
+    validations:
+      required: true
+
+  - type: textarea
+    id: what_the_app_said
+    attributes:
+      label: What did ScanDeck say?
+      description: >
+        The margin badge on the row, the text of any banner, and the completion
+        blocker if there was one. Copy the wording exactly — the copy is part of
+        the product and getting it wrong is itself a bug.
+    validations:
+      required: true
+
+  - type: input
+    id: footprints
+    attributes:
+      label: The two measured footprints, if the card row showed them
+      placeholder: "front 2104 x 2942 px, back 2098 x 2951 px"
+    validations:
+      required: false
+
+  - type: dropdown
+    id: media
+    attributes:
+      label: What was in the feeder?
+      options:
+        - Raw (bare) card
+        - Card in a toploader
+        - Card in a semi-rigid (note - not a supported format)
+        - Card in a penny sleeve only (note - not a supported format)
+        - Something else
+    validations:
+      required: true
+
+  - type: input
+    id: scanner
+    attributes:
+      label: Scanner and macOS version
+      placeholder: "fi-8170, macOS 26.5.2"
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Diagnostics report
+      description: >
+        Settings → Copy Diagnostics Report. It is content-free by construction —
+        it has no field a path, file name or batch name could go in, and there is
+        a test that proves it.
+      render: shell
+    validations:
+      required: false
+
+  - type: markdown
+    attributes:
+      value: |
+        **If you keep the masters**, you can turn this into a permanent
+        regression yourself without sending anyone an image:
+
+        ```sh
+        SCANDECK_CORPUS_DIR=<dir of _F/_B pairs> SCANDECK_CORPUS_REPORT=/tmp/r.csv \
+            swift test -c release --filter CardImageCropperCorpusDiagnostics
+        ```
+
+        That writes one row per side with both threshold reads, the dominant
+        component, the floor-supported bounds and the raw occupancy outside them
+        — which is the difference between "one side over-detected" and "the other
+        under-detected", opposite fixes on identical-looking evidence. Pasting
+        the CSV rows for the bad pair is the single most useful thing you can
+        attach.

.github/ISSUE_TEMPLATE/hardware-datapoint.yml

@@ -0,0 +1,95 @@
+name: Hardware datapoint
+description: Report what ScanDeck saw on a scanner other than the fi-8170. This is the most valuable report the project can get.
+title: "[hardware] "
+labels: ["hardware-datapoint", "scanner-support"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you — this is genuinely the highest-value contribution available.
+
+        ScanDeck supports exactly one scanner today, and widening that is capped
+        by nobody having capability data for anything else. Your report is the
+        seed of the supported-scanner matrix.
+
+        **You do not need the scan to have worked.** A device that fails is just
+        as useful as one that succeeds, as long as we can see *which* capability
+        was missing.
+
+        ⚠️ **Never attach a card scan.** Card images are your property and this
+        repository has never contained one. Paste text output only.
+
+  - type: input
+    id: model
+    attributes:
+      label: Scanner make and model
+      placeholder: "Ricoh fi-8040 / Brother ADS-4300N / Epson DS-C490"
+    validations:
+      required: true
+
+  - type: input
+    id: macos
+    attributes:
+      label: macOS version
+      placeholder: "26.5.2 (25F84)"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: connection
+    attributes:
+      label: How is it connected?
+      options:
+        - USB
+        - Network (Wi-Fi or Ethernet)
+        - Both available, reporting USB
+        - Both available, reporting network
+    validations:
+      required: true
+
+  - type: textarea
+    id: list
+    attributes:
+      label: Output of `swift run scandeck-m0 --list`
+      description: This works on any scanner and is not gated.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: inspect
+    attributes:
+      label: Output of `swift run scandeck-m0 --inspect`
+      description: >
+        Paste the whole thing, including any error. If it refuses your device,
+        that refusal IS the datapoint — paste it verbatim. Note that inspection
+        is currently gated to the fi-8170; if it refuses on those grounds, say
+        so and the `--list` output above is still useful on its own.
+      render: shell
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: capabilities
+    attributes:
+      label: Which of these does the scanner have?
+      description: >
+        These four are what the pipeline actually depends on. Tick what you know;
+        leave the rest blank rather than guessing. The vendor's spec sheet is a
+        fine source.
+      options:
+        - label: Duplex ADF (images both sides in one pass)
+        - label: 600 dpi
+        - label: 24-bit colour
+        - label: An overscan or margin mode that captures background *around* the detected media
+        - label: Automatic media-size detection
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else
+      description: >
+        Vendor driver name and version, whether Apple Image Capture sees it, or
+        anything that surprised you.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/spec-hole.yml

@@ -0,0 +1,40 @@
+name: Spec hole or design disagreement
+description: SPEC.md says something wrong, missing, over-engineered, or that you think is a mistake.
+title: "[spec] "
+labels: ["spec"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This is a real contribution and it is explicitly invited. SPEC.md is the
+        contract, and it has been changed before because someone argued it was
+        wrong — three of the seven invariants carry amendments for exactly that
+        reason.
+
+        You do not need code, a scanner, or a patch. An argument is enough.
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What does the spec say, and where?
+      description: Quote it, with the section number.
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What is wrong with it?
+      description: >
+        Wrong, missing, over-engineered, internally inconsistent, or contradicted
+        by the code — say which, and why it matters to someone using the app.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What should it say instead?
+      description: Optional. "I think this is wrong but I don't know the fix" is a legitimate issue.
+    validations:
+      required: false