bnquon · bnquon · Aug 29, 2026 · Aug 29, 2026 · Aug 29, 2026 · Aug 29, 2026
@@ -0,0 +1,2 @@
+# Default owner for all repository changes.
+* @bnquon
@@ -0,0 +1,61 @@
+name: Bug report
+description: Report a reproducible problem in Orson
+title: '[Bug]: '
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Please remove credentials and sensitive payload data from logs, screenshots, and examples.
+
+        Reports need enough detail for someone else to reproduce and investigate the problem. Include clear steps, exact error text, and a screenshot or recording when the issue is visual or interaction-related. Reports without enough information may not be addressed immediately and could be deprioritized until the missing context is provided.
+  - type: textarea
+    id: summary
+    attributes:
+      label: What happened?
+      description: Describe the problem and what you were trying to do.
+      placeholder: Tell us what went wrong.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Give the smallest reliable sequence of actions that shows the problem.
+      placeholder: |
+        1. Open ...
+        2. Configure ...
+        3. Click ...
+        4. Observe ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect Orson to do?
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What did Orson do instead? Include the exact error text when possible.
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: Include the commit or version, operating system, and Kafka/demo setup.
+      placeholder: 'commit abc123, macOS 15, local demo Kafka'
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Scenario or run context
+      description: Share the relevant scenario shape, run outcome, logs, or screenshots. Redact sensitive data.
+    validations:
+      required: false
@@ -0,0 +1,40 @@
+name: Feature request
+description: Suggest an improvement to Orson
+title: '[Feature]: '
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Describe the user problem first. Concrete Kafka workflow examples are especially helpful.
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: Who is affected, and what is difficult or unclear today?
+      placeholder: When I am debugging ..., it is hard to ...
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like to happen?
+      description: Describe the behavior or workflow you are proposing.
+      placeholder: Orson could ...
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What workarounds or other approaches have you tried?
+    validations:
+      required: false
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add examples, mockups, links, or relevant scenario details. Do not include secrets.
+    validations:
+      required: false
@@ -0,0 +1,19 @@
+## Summary
+
+<!-- What changed, and why? Keep this focused on the user or engineering problem. -->
+
+## User-facing changes
+
+<!-- Describe the behavior someone using Orson will notice. Mention affected workflows. -->
+
+## Validation/testing
+
+<!-- List the commands run and any manual scenarios exercised. If something could not be run, explain why. -->
+
+## Screenshots
+
+<!-- Include screenshots or a short recording for UI changes. Write “Not applicable” otherwise. -->
+
+## Risks, follow-ups, or deferred work
+
+<!-- Note migrations, compatibility concerns, known limitations, or intentionally deferred work. -->
@@ -0,0 +1,105 @@
+# Contributing to Orson
+
+Thanks for helping improve Orson. It is an early, local-first desktop app for
+understanding what happens after publishing a Kafka event. Focus contributions
+on making that debugging loop clearer, safer, and easier to reproduce.
+
+## Development setup
+
+Orson currently requires:
+
+- Go 1.25+
+- Node.js 20.19+ or 22.12+
+- Docker
+- Wails CLI v2.15.0
+
+Install the JavaScript dependencies from the repository root:
+
+```bash
+npm install
+npm --prefix frontend install
+```
+
+Install the matching Wails CLI if it is not already available:
+
+```bash
+go install github.com/wailsapp/wails/v2/cmd/wails@v2.15.0
+```
+
+Start the local Kafka demo from the repository root:
+
+```bash
+docker compose -f demo/compose.yaml up --build
+```
+
+Then start Orson in another terminal:
+
+```bash
+wails dev
+```
+
+The demo broker is available to the host at `localhost:9092`. The demo
+services, fixtures, and branch behavior are documented in
+[`demo/README.md`](demo/README.md) and [`demo/EVENTS.md`](demo/EVENTS.md).
+
+## Working on scenarios
+
+Scenario files are human-readable YAML intended to be shared through Git. The
+canonical bundled example is [`scenarios/order-flow.yaml`](scenarios/order-flow.yaml),
+and the format is documented in [`docs/scenario-format.md`](docs/scenario-format.md).
+
+Do not put credentials or captured run data in a scenario file. Keep payloads
+representative and safe to commit. Imported and newly saved scenarios should
+use the existing loader and serializer rather than introducing a second file
+format.
+
+## Branches and changes
+
+Create a focused branch from `main`. The usual prefixes are:
+
+- `feat/` for user-facing functionality
+- `fix/` for bug fixes
+- `docs/` for documentation-only changes
+- `refactor/` for behavior-preserving cleanup
+
+Keep unrelated formatting or generated-file changes out of the branch. For UI
+changes, describe the user-visible behavior and include a screenshot or short
+recording when it makes the change easier to review.
+
+## Validation
+
+Before opening a pull request, run the checks relevant to your change. The
+full repository validation is:
+
+```bash
+go test ./...
+go vet ./...
+npm run check
+npm run test:frontend
+npm --prefix frontend run build
+```
+
+`npm run check` covers formatting, linting, TypeScript, and export checks. Go
+changes should also remain `gofmt`-clean. If a check cannot be run locally,
+explain that in the pull request and include the reason.
+
+## Pull requests
+
+Keep the pull request focused and use the repository template. Explain:
+
+- what changed and why
+- the user-facing behavior
+- how it was tested
+- screenshots for UI changes
+- risks, follow-ups, or intentionally deferred work
+
+Small pull requests are easier to review, but a larger change is fine when it
+represents one coherent user workflow. Update the relevant documentation when
+behavior, commands, or scenario format changes.
+
+## Issues
+
+Use the bug report form for reproducible failures and the feature request form
+for proposed behavior. Include the Orson version or commit, operating system,
+Kafka/demo setup, and the smallest useful reproduction. Remove secrets and
+sensitive payload data from logs or screenshots before attaching them.
@@ -132,14 +132,17 @@ The demo services use plaintext Kafka and are intended for local development onl
 
 ## Roadmap
 
-- Multiple saved connection profiles
-- TLS and SASL configuration
-- More flexible correlation strategies
-- Richer graph interaction and layout
+See the [directional roadmap](ROADMAP.md) for current priorities. It is not
+strictly followed; priorities can change as Orson is used with real Kafka
+workflows.
 
 ## More documentation
 
 - [Product and architecture notes](PROJECT.md)
+- [Roadmap](ROADMAP.md)
+- [Contributing guide](CONTRIBUTING.md)
+- [Scenario format](docs/scenario-format.md)
+- [Scenario examples](scenarios/README.md)
 - [Kafka demo pipeline](demo/README.md)
 - [Demo event contracts](demo/EVENTS.md)
 - [Scenario example](scenarios/order-flow.yaml)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# Default owner for all repository changes.
		* @bnquon