@@ -1,48 +1,87 @@
 # Contributing to ClojureWasm
 
-Thanks for your interest. ClojureWasm is an early-stage runtime built by a very
-small team, so **Issues and Pull Requests are currently paused**. The most useful
-things you can do right now are to **read along, try it, and report behaviour that
-differs from JVM Clojure** — please do that in
-[GitHub Discussions](https://github.com/clojurewasm/ClojureWasm/discussions) and
-mention `@chaploud`.
+Thanks for your interest. **Issues and Pull Requests are open.** This is a
+small project, so replies can take a while — but the queue is real and it gets
+read.
 
-## Reporting a divergence from Clojure
+## The most useful thing you can do
+
+**Report Clojure code that behaves differently here than on the JVM.**
 
 ClojureWasm targets behavioural equivalence with JVM Clojure on the
-user-observable surface. If you find an expression that behaves differently:
+user-observable surface. Every divergence you find is either a bug or a gap
+that has not been written down yet — and finding them from the outside is worth
+more than anything else, because a project cannot easily see its own blind
+spots.
+
+There is a [Clojure divergence issue template](https://github.com/clojurewasm/ClojureWasm/issues/new?template=divergence.yml)
+that asks for the three things that make such a report actionable: the
+expression, what `cljw` prints, and what a JVM REPL prints.
 
-1. Check whether it is already a known, intentional difference in
-   [`docs/clojure_vs_clojurewasm.md`](../docs/clojure_vs_clojurewasm.md).
-2. If not, start a
-   [Discussion](https://github.com/clojurewasm/ClojureWasm/discussions) with the
-   expression, what `cljw` prints, and what a JVM Clojure REPL prints.
+Some differences are deliberate — check
+[`docs/clojure_vs_clojurewasm.md`](../docs/clojure_vs_clojurewasm.md) first. If
+one is listed there and you think the reasoning is wrong, that is a good
+Discussion.
 
 ## Working on the code
 
 ```sh
 direnv allow                              # one-time: load Zig 0.16.0 via Nix (or: nix develop)
 zig build -Dwasm -Doptimize=ReleaseSafe   # build the Wasm-enabled `cljw` binary
-bash test/run_all.sh                      # the full test suite must be green before a change lands
+bash test/run_all.sh --serial-e2e         # the full gate; must be green before a change lands
 ```
 
-`test/run_all.sh` runs the full gate; if a run flakes on a concurrency test, the
-serial mode (`bash test/run_all.sh --serial-e2e`) is authoritative.
+For a quick loop while iterating, `bash test/run_all.sh --smoke <e2e-step>`
+runs the unit tests, the dual-backend differential oracle, the linter, and the
+one end-to-end step you touched — tens of seconds instead of ~20 minutes. Run
+the full gate before you open the PR.
+
+Branch from `main` as `develop/<short-slug>`, open a PR, and let CI run. CI
+runs the same gate on macOS and Linux; a green CI is what merges.
+
+### What we do **not** ask of you
+
+This repository is developed largely by an autonomous loop working under
+written guardrails, and that loop follows conventions that exist to keep *it*
+honest. **None of them apply to your contribution:**
+
+- You do not need a `Smell-audited:` line in your commit message.
+- You do not need to add a row to `.dev/debt.yaml`.
+- You do not need to write an ADR, a per-task note, or a ROADMAP amendment.
+- You do not need to match the commit-message style of the surrounding history.
+
+Write a clear commit message, keep the gate green, and that is enough. If a
+change turns out to need a design record, writing it is the maintainer's job,
+not yours.
+
+### What helps a PR land
+
+- **One concern per PR.** A 30-line fix with a test merges; a 600-line
+  refactor bundled with a fix stalls.
+- **A test that fails before your change and passes after it.** The test
+  taxonomy is in [`.claude/rules/test_taxonomy.md`](../.claude/rules/test_taxonomy.md);
+  in short, unit tests live in `test "..."` blocks next to the code and CLI
+  behaviour lives in `test/e2e/*.sh`.
+- For a `clojure.core` behaviour change, **a line in the relevant corpus under
+  `test/diff/clj_corpus/`**, so the behaviour stays checked against real `clj`
+  from then on.
+
+A note on provenance: much of this codebase is machine-written under human
+review and direction. Contributions from people are very welcome and are
+reviewed the same way — on whether the code is right, not on who wrote it.
 
-The project follows a TDD loop (red → green → refactor) and keeps tests green on
-every commit. The development workflow, design principles, and the amendment
-process for the roadmap are documented in [`CLAUDE.md`](../.claude/CLAUDE.md) and
-[`.dev/`](../.dev/) (ROADMAP, decision records, principles). Load-bearing
-decisions are recorded as ADRs under [`.dev/decisions/`](../.dev/decisions/).
+## Design context, if you want it
 
-A note on provenance: much of this codebase is written by an autonomous
-development loop under written guardrails and ADR discipline. Human review and
-direction set the rails; contributions from people are very welcome and reviewed
-the same way.
+Load-bearing decisions are recorded as ADRs under
+[`.dev/decisions/`](../.dev/decisions/); the plan and its principles live in
+[`.dev/ROADMAP.md`](../.dev/ROADMAP.md); the development loop itself is
+described in [`.claude/CLAUDE.md`](../.claude/CLAUDE.md). None of this is
+required reading to send a patch — it is there if you want to know why
+something is the way it is.
 
 ## Getting in touch
 
-Questions and discussion are welcome in
+Open-ended questions belong in
 [GitHub Discussions](https://github.com/clojurewasm/ClojureWasm/discussions);
 the wider Clojure community also gathers on the
 [Clojurians Slack](https://clojurians.slack.com).
 
@@ -0,0 +1,70 @@
+name: "🐛 Bug"
+description: A crash, a hang, wrong output, or a build failure
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        If the bug is "this Clojure code gives a different answer than the JVM",
+        please use the **Clojure divergence** template instead — it asks for the
+        comparison that makes such a report actionable.
+
+        Crashes and hangs are the highest-priority reports here. A crash in the
+        WebAssembly FFI or the sandbox may be a security issue — in that case
+        please use [private vulnerability reporting](https://github.com/clojurewasm/ClojureWasm/security/advisories/new)
+        rather than a public issue.
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: How to reproduce
+      description: The exact command or code. Smaller is better.
+      render: shell
+      placeholder: cljw -e '(future (throw (ex-info "x" {})))'
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: What happened
+      description: Paste the output, error, or stack trace verbatim.
+      render: text
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: cljw version
+      description: Output of `cljw --version`.
+    validations:
+      required: true
+
+  - type: input
+    id: platform
+    attributes:
+      label: Platform and install method
+      placeholder: macOS aarch64, brew / Linux x86_64, built from source
+    validations:
+      required: true
+
+  - type: dropdown
+    id: wasm
+    attributes:
+      label: Does it involve the WebAssembly FFI?
+      options:
+        - "No"
+        - "Yes — wasm/load or wasm/call"
+        - "Yes — a component required as a namespace"
+        - "Not sure"
+    validations:
+      required: true
@@ -1,15 +1,14 @@
-# Issues are paused for ClojureWasm (small, resource-limited project).
-# Route everything to Discussions; disable blank issues.
+# Issues are open. Blank issues stay disabled so every report starts from a
+# template that asks for the one or two facts that make it actionable.
 blank_issues_enabled: false
 contact_links:
-  - name: 💬 Questions, bugs & Clojure divergences → Discussions
+  - name: 💬 Questions, ideas, "is this supposed to work?"
     url: https://github.com/clojurewasm/ClojureWasm/discussions
     about: >-
-      Issues and Pull Requests are currently paused. Please start a Discussion
-      and mention @chaploud. Reports of behaviour that differs from JVM Clojure
-      are especially welcome.
+      Anything open-ended belongs in Discussions rather than an issue — usage
+      questions, design conversations, showing what you built.
   - name: 🔒 Report a security vulnerability (private)
     url: https://github.com/clojurewasm/ClojureWasm/security/advisories/new
     about: >-
       Do NOT report security problems in public. Use private vulnerability
-      reporting — see SECURITY.md.
+      reporting — see SECURITY.md for scope and what to include.
@@ -0,0 +1,73 @@
+name: "🔀 Clojure divergence"
+description: Code that behaves differently on cljw than on JVM Clojure
+title: "[divergence] "
+labels: ["divergence"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This is the most valuable report you can file. ClojureWasm targets
+        behavioural equivalence with JVM Clojure on the user-observable
+        surface, so a difference is either a bug or a gap we have not written
+        down yet.
+
+        Before filing, it is worth a glance at
+        [`docs/clojure_vs_clojurewasm.md`](https://github.com/clojurewasm/ClojureWasm/blob/main/docs/clojure_vs_clojurewasm.md)
+        — some differences are deliberate and already recorded there. If yours
+        is listed, no need to file; if you think the reasoning is wrong, a
+        Discussion is the better place for that.
+
+  - type: textarea
+    id: expr
+    attributes:
+      label: The expression
+      description: The smallest form that shows the difference.
+      render: clojure
+      placeholder: (map inc [1 2 3])
+    validations:
+      required: true
+
+  - type: textarea
+    id: cljw
+    attributes:
+      label: What cljw prints
+      description: Paste the output verbatim, including any error.
+      render: text
+    validations:
+      required: true
+
+  - type: textarea
+    id: clj
+    attributes:
+      label: What a JVM Clojure REPL prints
+      description: Verbatim again. If you cannot run a JVM REPL, say so and we will check.
+      render: text
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: cljw version
+      description: Output of `cljw --version`.
+      placeholder: ClojureWasm v1.5.1 (ReleaseSafe, wasm)
+    validations:
+      required: true
+
+  - type: input
+    id: platform
+    attributes:
+      label: Platform
+      placeholder: macOS aarch64 / Linux x86_64 / installed via brew
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Anything else
+      description: >-
+        Optional. If you hit this inside a real library, naming it helps —
+        library compatibility is tracked in `docs/works/ladder.md`.
+    validations:
+      required: false
@@ -0,0 +1,49 @@
+name: "🧩 Missing var, namespace, or library support"
+description: Something from Clojure or a library that cljw does not have yet
+title: "[missing] "
+labels: ["missing"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        cljw implements most of `clojure.core` and a growing set of standard
+        namespaces, but not all of it, and some of it never will be — anything
+        that requires the JVM class system (`gen-class`, `proxy` against real
+        Java base classes, `bean`'s reflective variant) is permanently out of
+        scope, recorded in [`data/compat_tiers.yaml`](https://github.com/clojurewasm/ClojureWasm/blob/main/data/compat_tiers.yaml).
+
+        Telling us *what you were trying to do* matters more than the var name
+        — often there is a supported path, and if there is not, the use case is
+        what decides the priority.
+
+  - type: input
+    id: what
+    attributes:
+      label: What is missing
+      placeholder: clojure.core/load-file, or clojure.spec.alpha, or next.jdbc
+    validations:
+      required: true
+
+  - type: textarea
+    id: usecase
+    attributes:
+      label: What you were trying to do
+      description: The actual task, not just the missing name.
+    validations:
+      required: true
+
+  - type: textarea
+    id: error
+    attributes:
+      label: What cljw said
+      description: The error output, if you got one.
+      render: text
+    validations:
+      required: false
+
+  - type: input
+    id: version
+    attributes:
+      label: cljw version
+    validations:
+      required: true
@@ -9,13 +9,18 @@ reports seriously.
 
 ## Supported versions
 
-ClojureWasm is currently **pre-1.0** (`1.0.0-rc.*` / `1.0.0-alpha.*`). Security
-fixes land on the `main` branch and the newest pre-release tag.
-
-| Version                 | Supported |
-|-------------------------|-----------|
-| `1.0.0-rc.*` / `main`   | ✅        |
-| earlier `1.0.0-alpha.*` | ❌        |
+Security fixes land on the `main` branch and in the next release cut from it.
+Only the newest release line is supported — this is a small project and there
+is no backport branch.
+
+| Version                        | Supported |
+|--------------------------------|-----------|
+| `main`                         | ✅        |
+| newest `1.x` release           | ✅        |
+| any older release              | ❌        |
+
+If you are on Homebrew, `brew upgrade clojurewasm/tap/cljw` puts you on the
+supported line.
 
 ## Reporting a vulnerability
 
 
@@ -17,10 +17,14 @@
 </p>
 
 > [!NOTE]
-> ClojureWasm has reached its first stable release (**1.0.0**), but it is built by
-> a very small team with limited resources. To keep that focus, **Issues and Pull Requests are not
-> being accepted** right now. You are very welcome to read along, try it, and
-> say hello in [GitHub Discussions](https://github.com/clojurewasm/ClojureWasm/discussions).
+> ClojureWasm is stable and released regularly; the current line is **1.x**
+> (see [Releases](https://github.com/clojurewasm/ClojureWasm/releases)). It is
+> built by a very small team, so replies can take a while — but
+> [Issues](https://github.com/clojurewasm/ClojureWasm/issues) and Pull Requests
+> are open. **The single most useful thing you can report is Clojure code that
+> behaves differently here than on the JVM**; there is an issue template for
+> exactly that. Questions and general discussion are welcome in
+> [Discussions](https://github.com/clojurewasm/ClojureWasm/discussions).
 
 ## What it is