Community-health files, issue/PR templates, and repo metadata

.editorconfig

@@ -1,5 +1,12 @@
 root = true
 
 [*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
 indent_style = space
 indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# Default review ownership for GhostRoboticsLab/rp2350js_emulator.
+# @prat96 (Pratheek Balakrishna) is requested on every PR; under the
+# GhostRoboticsLab org this is the catch-all owner for anything without a
+# more specific rule below.
+* @prat96

.github/ISSUE_TEMPLATE/01-isa-instruction-bug.yml

@@ -0,0 +1,82 @@
+name: "RISC-V instruction / ISA incorrectness"
+description: "An instruction decodes, traps, or computes a result that disagrees with the RISC-V spec or Hazard3."
+title: "[isa] "
+labels: ["bug", "riscv-core"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for stress-testing the Hazard3 core.
+
+        **Before you file:**
+        - Search [existing issues](https://github.com/GhostRoboticsLab/rp2350js_emulator/issues?q=is%3Aissue) — this is an **early-but-real** fork and known gaps are tracked in [ROADMAP.md](https://github.com/GhostRoboticsLab/rp2350js_emulator/blob/main/ROADMAP.md).
+        - This template is for a *single wrong instruction*: a bad decode, a wrong result word, a mis-targeted trap, a missing CSR side effect. The core is `RV32IMAC + Zba/Zbb/Zbs/Zcb`; the M-extension family (incl. `MULHSU`), trap entry, and the Hazard3 IRQ controller were the largest fix areas — see [README.md](https://github.com/GhostRoboticsLab/rp2350js_emulator/blob/main/README.md#what-this-fork-fixes-in-the-risc-v-core).
+        - For a whole peripheral or a firmware that won't boot, use the *Peripheral / firmware boot issue* template instead.
+  - type: input
+    id: instructions
+    attributes:
+      label: "Affected instruction(s)"
+      description: "Mnemonic(s), exactly as the assembler spells them. If you have the 16/32-bit encoding, include it."
+      placeholder: "MULHSU, or c.zext.h, or csrrc — encoding 0x02C5_A5B3 if known"
+    validations:
+      required: true
+  - type: dropdown
+    id: isa-area
+    attributes:
+      label: "ISA area"
+      description: "Which extension or subsystem the instruction belongs to."
+      options:
+        - "RV32I (base integer)"
+        - "RV32M (mul/div)"
+        - "RV32A (atomics)"
+        - "RV32C (compressed)"
+        - "Zba/Zbb/Zbs (bit-manipulation)"
+        - "Zcb (extra compressed)"
+        - "Zicsr (CSR access)"
+        - "trap / CSR machine state (mtvec, mcause, mstatus, mepc, …)"
+        - "Xh3irq (Hazard3 interrupt controller: meinext, meiea, meipa, …)"
+        - "other / not sure"
+    validations:
+      required: true
+  - type: textarea
+    id: expected-vs-actual
+    attributes:
+      label: "Expected vs actual"
+      description: "What the spec says should happen, and what the engine does instead. Be exact: operand values, the result word, the resulting PC, or mcause/mepc for a trap."
+      placeholder: |
+        Inputs: rs1 = 0xFFFF_FFFF (-1, signed), rs2 = 0x0000_0002 (2, unsigned)
+        Expected (MULHSU = signed*unsigned, high word): 0xFFFF_FFFF
+        Actual: 0x0000_0001
+    validations:
+      required: true
+  - type: textarea
+    id: reproducer
+    attributes:
+      label: "Minimal reproducer"
+      description: "Smallest asm sequence (the in-tree assembler is fine) or a firmware ELF/UF2 plus the steps to reach the faulting instruction. Paste the snippet; attach the binary if needed."
+      placeholder: |
+        li   a0, -1
+        li   a1, 2
+        mulhsu a2, a0, a1   # a2 should be 0xFFFFFFFF
+        # then: dump x12 after one step
+      render: text
+    validations:
+      required: true
+  - type: checkboxes
+    id: negative-control
+    attributes:
+      label: "Regression test"
+      description: "Every core fix in this repo ships with a falsifiable test in src/riscv/test/cpu-fixes.spec.ts that is proven to FAIL on the pre-fix engine (a negative control). It speeds up triage enormously if you can supply one."
+      options:
+        - label: "I can/will add a negative-control test (an assertion proven to fail on the current engine)."
+          required: false
+        - label: "I confirmed this isn't already a deferred item in ROADMAP.md (e.g. the intentional illegal-instruction `throw`)."
+          required: false
+  - type: input
+    id: version
+    attributes:
+      label: "Engine version / commit"
+      description: "The release tag (e.g. rp2350-v0.1.0) or `git rev-parse --short HEAD`. Note: v0.1.0..v1.3.3 are inherited upstream rp2040js tags, not this fork's releases."
+      placeholder: "rp2350-v0.1.0 / fb7f130"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/02-peripheral-or-firmware.yml

@@ -0,0 +1,77 @@
+name: "Peripheral / firmware boot issue"
+description: "A RP2350 peripheral behaves wrong, or a real firmware won't boot / hangs / produces the wrong output."
+title: "[peripheral] "
+labels: ["bug", "rp2350-peripheral"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for running real firmware through the chip.
+
+        **Before you file:**
+        - Search [existing issues](https://github.com/GhostRoboticsLab/rp2350js_emulator/issues?q=is%3Aissue) first. The peripheral layer is freshly multi-chip parameterized and some RP2350 PIO features are **deliberately deferred** until firmware exercises them — check the "remaining RP2350 PIO features" section of [ROADMAP.md](https://github.com/GhostRoboticsLab/rp2350js_emulator/blob/main/ROADMAP.md) before reporting a PIO gap (`IN_COUNT` masking, PIO IRQ-index mode, neighbour-SM restart, `FJOIN_RX/TX`, `WAIT PIN` gpiobase offset are known-deferred).
+        - Three firmware integration tests are known-good baselines: `blink_simple` (GPIO via SIO), `hello_timer` (250M-step timer-IRQ run, 19 prints), `pio_blink` (two PIO blocks, GPIO3 + GPIO32 via the GPIOBASE pin-window). If yours diverges from one of these, say which.
+        - If the root cause is a single wrong *instruction*, use the *RISC-V instruction / ISA incorrectness* template instead.
+  - type: dropdown
+    id: peripheral
+    attributes:
+      label: "Peripheral"
+      description: "The block most likely at fault. Pick `bootrom` if the chip never reaches your firmware's entry point."
+      options:
+        - "SIO (single-cycle IO, GPIO atomic set/clr/xor)"
+        - "TIMER"
+        - "PIO"
+        - "DMA"
+        - "GPIO / pads (function-select, pad mask, GPIOBASE pin-window)"
+        - "UART"
+        - "SPI"
+        - "I2C"
+        - "PWM"
+        - "ADC"
+        - "USB"
+        - "RESETS (reset_mask / RESET_DONE)"
+        - "POWMAN"
+        - "bootrom (A2)"
+        - "other / not sure"
+    validations:
+      required: true
+  - type: textarea
+    id: firmware
+    attributes:
+      label: "Firmware under test"
+      description: "What is it, and how was it built? SDK version, target board, RISC-V vs Arm toolchain. Link or attach the ELF/UF2 if you can."
+      placeholder: |
+        pico-sdk 2.1.0, board pico2 (rp2350, riscv), pio_ws2812 example driving GP28.
+        Built with the riscv toolchain; attaching ws2812.elf.
+    validations:
+      required: true
+  - type: textarea
+    id: expected-vs-actual
+    attributes:
+      label: "What happens vs what you expected"
+      description: "Observed behaviour against intended. Be concrete: which GPIO/register, expected vs actual value, where it hangs (PC, the spin loop), or how the output stream differs."
+      placeholder: |
+        Expected: GP28 emits a 24-bit WS2812 frame, GP3 toggles twice.
+        Actual: chip spins in the bootrom RESET_DONE loop and never reaches main().
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: "Steps to reproduce"
+      description: "Exactly how you ran it: the harness/script, step budget, and what you inspected. A minimal failing snippet beats a prose description."
+      placeholder: |
+        1. const mcu = new RP2350(); load ws2812.uf2; mcu.core0.pc = 0x...
+        2. step ~2,000,000 cycles
+        3. read gpioValues — GP28 never changes
+      render: text
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: "Engine version / commit"
+      description: "The release tag (e.g. rp2350-v0.1.0) or `git rev-parse --short HEAD`. (v0.1.0..v1.3.3 are inherited upstream rp2040js tags, not this fork's.)"
+      placeholder: "rp2350-v0.1.0 / fb7f130"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/03-bug-report.yml

@@ -0,0 +1,52 @@
+name: "Bug report"
+description: "Anything wrong that isn't a single ISA instruction or a specific peripheral/firmware boot — tooling, build, test harness, assembler, API."
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report.
+
+        **Before you file:**
+        - Search [existing issues](https://github.com/GhostRoboticsLab/rp2350js_emulator/issues?q=is%3Aissue).
+        - If this is a wrong RISC-V instruction, or a peripheral/firmware boot problem, the two dedicated templates collect the right details faster.
+        - Pure RP2040 (Arm) issues that also reproduce on upstream belong at [wokwi/rp2040js](https://github.com/wokwi/rp2040js/issues).
+  - type: textarea
+    id: summary
+    attributes:
+      label: "What's wrong"
+      description: "A clear, concrete description of the bug and where it surfaces (build, lint, a vitest case, the assembler, the public API, …)."
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: "Steps to reproduce"
+      description: "Minimal steps or a snippet. `npm install` then the exact command you ran (e.g. `npx vitest run src/riscv`)."
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: "Expected behaviour"
+      description: "What you expected to happen instead."
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: "Logs / output"
+      description: "Relevant error text, stack trace, or failing test output. Will be rendered as code — no backticks needed."
+      render: shell
+    validations:
+      required: false
+  - type: input
+    id: environment
+    attributes:
+      label: "Environment"
+      description: "Node version (CI runs 20 and 22; the project needs >=18), OS, and the engine version/commit (`git rev-parse --short HEAD`)."
+      placeholder: "Node 22, macOS 15, rp2350-v0.1.0 / fb7f130"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/04-feature-request.yml

@@ -0,0 +1,45 @@
+name: "Feature request / enhancement"
+description: "Propose a new capability — an unimplemented RP2350 peripheral feature, an ISA extension, tooling, or an API improvement."
+title: "[feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping shape the fork.
+
+        **Check [ROADMAP.md](https://github.com/GhostRoboticsLab/rp2350js_emulator/blob/main/ROADMAP.md) first.** Several RP2350 features are *already designed and deliberately deferred* — they'll land each with its own falsifiable test rather than be ported unverified. If your request is one of these (e.g. PIO `IN_COUNT` masking, PIO IRQ-index mode / `resolveIrqTarget`, neighbour state-machine synchronous restart, `FJOIN_RX/TX` joined FIFOs, the `WAIT PIN` gpiobase offset, or the intentional illegal-instruction `throw`), please **upvote / comment** rather than open a duplicate, and tell us the firmware that needs it — firmware-driven demand is what moves a deferred item up the list.
+  - type: textarea
+    id: problem
+    attributes:
+      label: "Problem / motivation"
+      description: "What can't you do today, and what firmware or use case needs it? Concrete beats abstract."
+      placeholder: "My firmware joins the PIO TX FIFO (FJOIN_TX) for a 8-deep DMA-fed stream; the engine only offers a 4-deep FIFO, so the program underruns."
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: "Proposed behaviour"
+      description: "What should the engine do? Reference the relevant register/instruction/bitfield if you know it (e.g. SHIFTCTRL.FJOIN_TX, GPIOBASE, MEINEXT)."
+    validations:
+      required: true
+  - type: dropdown
+    id: roadmap-check
+    attributes:
+      label: "ROADMAP.md status"
+      description: "Where does this sit relative to the roadmap?"
+      options:
+        - "Already listed as deferred in ROADMAP.md (I'm adding demand/context)"
+        - "Not on the roadmap — genuinely new"
+        - "Not sure"
+    validations:
+      required: true
+  - type: textarea
+    id: test
+    attributes:
+      label: "How would we know it works?"
+      description: "This fork gates every behaviour with a falsifiable test. Sketch the assertion or the firmware run that would prove the feature correct (and ideally fail on today's engine)."
+      placeholder: "A PIO test that fills 8 TX words after FJOIN_TX and asserts no underrun over N cycles; fails today because the FIFO caps at 4."
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: "RP2040-only (Arm) issue"
+    url: "https://github.com/wokwi/rp2040js/issues"
+    about: "This fork's contribution is the RP2350 / Hazard3 RISC-V side. A bug that reproduces on plain RP2040 belongs upstream at wokwi/rp2040js."
+  - name: "Questions & ideas"
+    url: "https://github.com/GhostRoboticsLab/rp2350js_emulator"
+    about: "Not sure it's a bug? Read the README and open a Discussion (or a thread on the repo) rather than an issue."

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## What & why
+
+<!--
+A short, concrete description of the change and the reason for it. Name real
+things: the instruction, register, peripheral, or test involved (e.g. "MULHSU
+was undecoded", "MTVEC mode bits weren't masked", "GPIOBASE pin-window"). If
+this corrects RISC-V behavior, state the spec rule and how the engine violated it.
+-->
+
+Closes #
+
+## Checklist
+
+- [ ] Where behavior changed, a regression test was added and **PROVEN to fail on the pre-fix engine** (negative control — see `src/riscv/test/cpu-fixes.spec.ts`).
+- [ ] `npm test` is green (348+ tests, 0 skipped).
+- [ ] `npx tsc --noEmit` is clean.
+- [ ] prettier + eslint clean (`npm run format:check` && `npm run lint`).
+- [ ] DCO sign-off present on every commit (`git commit -s`); no co-author trailers.
+- [ ] For any imported code, original authorship and [CREDITS.md](../CREDITS.md) are preserved.
+- [ ] [ROADMAP.md](../ROADMAP.md) / [CHANGELOG.md](../CHANGELOG.md) updated if this lands or defers a tracked item.

.github/dependabot.yml

@@ -0,0 +1,30 @@
+# Dependabot config — batched, monthly, low-noise.
+# Minor + patch bumps are grouped into a single PR per ecosystem; majors come
+# through on their own so they get individual review.
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    groups:
+      npm-minor-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    groups:
+      actions-minor-patch:
+        update-types:
+          - "minor"
+          - "patch"