docs: add issue-first contribution policy

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,99 @@
+name: Bug report
+description: Report a reproducible problem in Khone.
+title: "bug: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping improve Khone. Please submit only reports you have reproduced or can substantiate with concrete evidence.
+
+        This project does not accept unsolicited external pull requests. If the issue is accepted, a maintainer will create the implementation PR and may invite you to review or test it.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Affected area
+      options:
+        - Gateway
+        - Bootstrap or SAM macro
+        - Lambda adapter
+        - Examples
+        - Benchmark tooling
+        - Documentation
+        - Website
+        - Other or not sure
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Khone version or commit
+      description: Include the release version, branch, or commit SHA you tested.
+      placeholder: "0.1.0, main@abc1234, or a commit SHA"
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: List the shortest sequence that reproduces the problem.
+      placeholder: |
+        1. Deploy ...
+        2. Send ...
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What happened instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence
+      description: Include logs, stack traces, response bodies, configuration snippets, or a minimal example. Remove secrets and private infrastructure details.
+      render: text
+    validations:
+      required: false
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include relevant AWS services, region, runtime, deployment mode, local tool versions, and dependency versions.
+      placeholder: |
+        AWS region:
+        Runtime:
+        Deployment mode:
+        SAM CLI:
+        cargo-lambda:
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: quality
+    attributes:
+      label: Report quality
+      options:
+        - label: I have reproduced this issue or provided concrete evidence for it.
+          required: true
+        - label: I have removed secrets, credentials, and private infrastructure details.
+          required: true
+        - label: I understand this repository does not accept unsolicited external PRs.
+          required: true
+

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/design_feedback.yml

@@ -0,0 +1,71 @@
+name: Design feedback or use case
+description: Share feedback about APIs, deployment, docs, or operational behavior.
+title: "feedback: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for design feedback, unclear documentation, operational concerns, or real-world scenarios that should shape Khone.
+
+        This project does not accept unsolicited external pull requests. Maintainers will create implementation PRs for accepted changes.
+
+  - type: dropdown
+    id: topic
+    attributes:
+      label: Feedback topic
+      options:
+        - API or protocol design
+        - Deployment model
+        - Batching behavior
+        - Operational behavior
+        - Documentation clarity
+        - Example coverage
+        - Benchmark methodology
+        - Other or not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: What were you reading, building, deploying, or evaluating when this came up?
+    validations:
+      required: true
+
+  - type: textarea
+    id: observation
+    attributes:
+      label: Observation or feedback
+      description: What seems confusing, risky, underspecified, or worth reconsidering?
+    validations:
+      required: true
+
+  - type: textarea
+    id: desired-change
+    attributes:
+      label: Desired change
+      description: What would make the project easier to understand, operate, or evaluate?
+    validations:
+      required: false
+
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Supporting context
+      description: Include links, examples, traces, diagrams, measurements, or snippets. Remove secrets and private details.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: quality
+    attributes:
+      label: Feedback quality
+      options:
+        - label: This feedback is based on a concrete reading, deployment, evaluation, or use case.
+          required: true
+        - label: I have removed secrets, credentials, and private infrastructure details.
+          required: true
+        - label: I understand this repository does not accept unsolicited external PRs.
+          required: true
+

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,85 @@
+name: Feature request
+description: Request a feature tied to a concrete use case.
+title: "feature: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for sharing a use case. Please focus on the problem, desired outcome, and constraints.
+
+        This project does not accept unsolicited external pull requests. If the request is accepted, a maintainer will create the implementation PR and may invite you to review or test it.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or use case
+      description: What are you trying to do, and why does the current project not cover it?
+      placeholder: "I want to..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: desired-outcome
+    attributes:
+      label: Desired outcome
+      description: Describe the user-visible or operator-visible behavior you want.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Relevant area
+      options:
+        - Gateway behavior
+        - Batching policy
+        - Lambda adapter
+        - Bootstrap or SAM deployment
+        - Observability
+        - Benchmarking
+        - Documentation
+        - Other or not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: constraints
+    attributes:
+      label: Constraints and tradeoffs
+      description: Include latency, cost, reliability, compatibility, AWS service limits, deployment, or operational constraints.
+      placeholder: |
+        Latency budget:
+        Cost sensitivity:
+        Deployment constraints:
+        Compatibility requirements:
+    validations:
+      required: false
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: Current workaround
+      description: What are you doing today, if anything?
+    validations:
+      required: false
+
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Supporting context
+      description: Link to docs, examples, benchmark data, logs, diagrams, or related prior art when useful. Remove secrets and private details.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: quality
+    attributes:
+      label: Request quality
+      options:
+        - label: This request is tied to a real use case or concrete workflow.
+          required: true
+        - label: I have described the problem and desired outcome, not only an implementation idea.
+          required: true
+        - label: I understand this repository does not accept unsolicited external PRs.
+          required: true
+

CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing
+
+Khone welcomes practical feedback, substantiated bug reports, feature requests,
+and real-world use cases through GitHub issues.
+
+This project does not accept unsolicited external pull requests.
+
+## Why Pull Requests Are Limited
+
+This is a maintainer-capacity, project-direction, and supply-chain security
+boundary.
+
+Modern coding agents make it inexpensive to generate plausible-looking code
+changes, bug reports, and security claims at high volume. Careful review still
+requires project context, reproduction, testing, design judgment, and trust.
+Unsubstantiated reports and broad unsolicited pull requests can consume more
+maintainer time than the original change took to generate.
+
+Untrusted pull requests can also exercise CI/CD paths and increase the risk of
+workflow or supply-chain abuse. Keeping implementation pull requests under
+maintainer control reduces that attack surface while keeping the issue tracker
+open for useful feedback.
+
+This policy is not a rejection of AI-assisted work. AI-assisted reports are
+welcome when a person has verified the claim, understands the issue, and can
+provide concrete evidence.
+
+## Accepted Contribution Channels
+
+Please use GitHub issues for:
+
+- Reproducible bug reports.
+- Feature requests tied to a real use case.
+- Design feedback about APIs, deployment model, batching behavior, docs, or
+  operational tradeoffs.
+- Examples of confusing documentation or unclear project boundaries.
+
+If a bug report or feature request is accepted, a maintainer will create the
+implementation pull request. The original reporter may be invited to review,
+test, and comment on that pull request.
+
+External pull requests may be considered only after explicit maintainer
+invitation for a specific accepted issue.
+
+## Bug Reports
+
+Good bug reports include:
+
+- The Khone version or commit tested.
+- The affected component, such as gateway, bootstrap, adapter, benchmark,
+  examples, docs, or website.
+- Reproduction steps.
+- Expected behavior.
+- Actual behavior.
+- Relevant logs, stack traces, configuration snippets, or minimal examples.
+- Environment details such as runtime, AWS service, region, deployment mode, and
+  local tool versions when relevant.
+
+Please do not submit generated bug reports or vulnerability claims that you
+cannot reproduce or explain.
+
+## Feature Requests
+
+Good feature requests describe:
+
+- The problem or workflow you are trying to support.
+- Why the current behavior is insufficient.
+- The desired outcome.
+- Operational constraints or tradeoffs, especially around latency, cost,
+  batching behavior, Lambda limits, and deployment model.
+- Any current workaround.
+
+Implementation ideas are welcome, but the most valuable part of a feature
+request is the problem statement and use case.
+
+## Security-Sensitive Reports
+
+Do not include secrets, credentials, private infrastructure details, or exploit
+instructions against live systems in a public issue.
+
+If a security report is sensitive, use GitHub private vulnerability reporting if
+it is available for the repository. If no private reporting channel is visible,
+open a minimal public issue asking for maintainer contact without including the
+sensitive technical details.

README.md

@@ -107,6 +107,13 @@ Start with [the public docs](docs/index.md):
 - [Configuration reference](docs/reference/configuration.md)
 - [Benchmark results](docs/benchmarks/results.mdx)
 
+## Contributing
+
+Khone welcomes substantiated bug reports, feature requests, design feedback, and
+real-world use cases through GitHub issues. The project does not accept
+unsolicited external pull requests; see [Contributing](CONTRIBUTING.md) for the
+full policy and rationale.
+
 ## Repository Layout
 
 - `gateway/`: Rust Axum/Lambda gateway.