llm-sse 0.4.8 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,35 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-23
+
+### Added
+
+- `parseOpenAIResponsesStream(source)` and the `openai-responses` dispatcher
+  target for typed OpenAI Responses API streams.
+- Normalization for Responses API text, reasoning summaries, function-call
+  arguments, refusal text, completion, incomplete responses, and errors.
+- A public Responses API weather-tool fixture with normalized event and
+  collected-message expectations.
+- Public roadmap, governance, support channels, and a documented path from
+  contributor to maintainer.
+
+### Changed
+
+- Project documentation now links contribution, security, governance, support,
+  roadmap, and release resources from the README.
+- The published tarball now includes those public project documents and is
+  installation-tested before release.
+- Development tooling overrides `esbuild` to a patched release so a clean
+  install passes `npm audit` without changing the package's zero-dependency
+  runtime.
+
+## [0.4.9] - 2026-06-29
+
+### Changed
+
+- Documentation: replace em dashes with standard punctuation for consistent house style.
+
 ## [0.4.8] - 2026-06-29
 
 ### Changed
@@ -111,6 +140,16 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   and `Uint8Array` or string sources.
 - Zero runtime dependencies; ESM + CJS builds with type declarations.
 
+[0.5.0]: https://github.com/slegarraga/llm-sse/releases/tag/v0.5.0
+[0.4.9]: https://github.com/slegarraga/llm-sse/releases/tag/v0.4.9
+[0.4.8]: https://github.com/slegarraga/llm-sse/releases/tag/v0.4.8
+[0.4.7]: https://github.com/slegarraga/llm-sse/releases/tag/v0.4.7
+[0.4.6]: https://github.com/slegarraga/llm-sse/releases/tag/v0.4.6
+[0.4.5]: https://github.com/slegarraga/llm-sse/releases/tag/v0.4.5
+[0.4.4]: https://github.com/slegarraga/llm-sse/releases/tag/v0.4.4
+[0.4.3]: https://github.com/slegarraga/llm-sse/releases/tag/v0.4.3
+[0.4.2]: https://github.com/slegarraga/llm-sse/releases/tag/v0.4.2
+[0.4.1]: https://github.com/slegarraga/llm-sse/releases/tag/v0.4.1
 [0.4.0]: https://github.com/slegarraga/llm-sse/releases/tag/v0.4.0
 [0.3.0]: https://github.com/slegarraga/llm-sse/releases/tag/v0.3.0
 [0.2.0]: https://github.com/slegarraga/llm-sse/releases/tag/v0.2.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,57 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive, or
+harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at **sebastian@0a.cl**. All complaints will be
+reviewed and investigated promptly and fairly. All maintainers are obligated to
+respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

package/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to llm-sse
+
+Thanks for taking the time to contribute. This project aims to be a small,
+dependable, zero-dependency building block, so the bar for changes is clarity
+and correctness over breadth.
+
+## Getting started
+
+```sh
+git clone https://github.com/slegarraga/llm-sse.git
+cd llm-sse
+npm install
+```
+
+## Development workflow
+
+Every change should keep the full check suite green:
+
+```sh
+npm run typecheck   # tsc --noEmit
+npm run lint        # eslint
+npm test            # vitest
+npm run build       # tsup (ESM + CJS + types)
+npm run format      # prettier --write
+```
+
+Run `npm run test:watch` while developing.
+
+## Pull requests
+
+1. Fork the repo and create a branch from `main` (e.g. `fix/gemini-tool-index`).
+2. Add or update tests. New behaviour without a test will not be merged.
+3. Make sure `typecheck`, `lint`, `test` and `build` all pass.
+4. Keep the public API surface small and documented with JSDoc.
+5. Open a pull request describing the provider stream shape you are handling.
+
+## Commit messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/).
+Examples:
+
+```
+feat(anthropic): handle thinking_delta blocks
+fix(sse): join multi-line data fields per spec
+docs: clarify the tool-call delta model
+test: cover chunk boundaries splitting an event
+chore: bump dev dependencies
+```
+
+The type drives the next version bump (`fix` -> patch, `feat` -> minor, a
+`!` or `BREAKING CHANGE` footer -> major).
+
+## Reporting bugs
+
+Open an issue with a minimal reproduction: the raw stream bytes (or the `data:`
+lines) from the provider, which provider produced them, and the `StreamEvent`s
+you expected. A failing test case is the most useful form a bug report can take.
+
+## Scope and philosophy
+
+- Zero runtime dependencies. A dependency needs an exceptional justification.
+- Parsing is total: malformed or non-JSON `data:` lines are skipped, never
+  thrown, so one bad keep-alive can't break a stream.
+- Event mapping is grounded in official provider documentation. When you add or
+  change a rule, link the source in the PR.

package/GOVERNANCE.md

@@ -0,0 +1,71 @@
+# Governance
+
+`llm-sse` is an independent open-source project. Governance is designed to keep
+the parser small and dependable while making it possible for trusted
+contributors to take real ownership.
+
+## Current maintainer
+
+- [Sebastian Legarraga](https://github.com/slegarraga) — project direction,
+  releases, security response, and repository administration.
+
+The project currently has a single maintainer. Expanding the maintainer group is
+an explicit goal, not a prerequisite contributors must wait for.
+
+## How decisions are made
+
+- Bug fixes and small, backward-compatible improvements are decided through
+  pull-request review.
+- New provider formats, normalized event variants, and breaking changes should
+  start with a public issue or discussion.
+- Decisions prioritize primary provider documentation, reproducible fixtures,
+  interoperability, security, and maintenance cost.
+- If reasonable contributors disagree, the maintainer records the tradeoff and
+  decision publicly rather than moving the discussion to a private channel.
+
+## Roles
+
+### Contributor
+
+Anyone who reports a reproducible issue, improves documentation, supplies a
+sanitized fixture, or lands a code change.
+
+### Reviewer
+
+A contributor who understands an area of the project and regularly helps review
+changes or triage issues. Reviewers may be listed in the repository and invited
+to relevant reviews.
+
+### Maintainer
+
+A trusted reviewer with sustained, constructive involvement who can merge
+changes, manage issues, and help prepare releases. Maintainers are expected to:
+
+- uphold the code of conduct and security policy;
+- require tests and primary-source evidence for provider behavior changes;
+- disclose conflicts of interest;
+- avoid merging their own substantial changes without another review when a
+  second maintainer is available;
+- preserve the project's zero-dependency and compatibility commitments.
+
+Maintainer access is offered based on demonstrated judgment, reliability,
+project need, and mutual agreement. It is never exchanged for sponsorship,
+stars, or a fixed number of pull requests.
+
+## Releases
+
+Releases follow Semantic Versioning. The release workflow reruns type checking,
+linting, tests, and the build before publishing with npm provenance. Breaking
+changes require a migration note.
+
+## Security and conduct
+
+Security reports follow [SECURITY.md](./SECURITY.md). Community behavior follows
+[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md). A maintainer involved in a conduct
+or security concern should recuse themselves when another trusted reviewer is
+available.
+
+## Changes to governance
+
+Governance changes use the same public pull-request process as code changes and
+should explain the problem they solve.

package/README.md

@@ -9,16 +9,64 @@
 [![license](https://img.shields.io/npm/l/llm-sse.svg)](./LICENSE)
 [![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](./package.json)
 
-> Zero-dependency SSE parser that turns OpenAI, Anthropic, Gemini and any OpenAI-compatible stream into one unified event shape: text deltas, reasoning, tool-call fragments and finish reasons, handled the same way regardless of provider.
+> Zero-dependency SSE parser that turns OpenAI Responses, OpenAI Chat Completions, Anthropic, Gemini and OpenAI-compatible streams into one unified event shape: text deltas, reasoning, tool-call fragments and finish reasons, handled the same way regardless of provider.
 
 Security posture is tracked in [docs/security-posture.md](https://github.com/slegarraga/llm-sse/blob/main/docs/security-posture.md),
 including CodeQL, OpenSSF Scorecard, Dependabot and branch rules.
 
-Each provider streams differently. OpenAI sends `choices[].delta` chunks, Anthropic sends typed `content_block_*` / `message_*` events, Gemini sends `candidates[].content.parts` — and the SSE framing, tool-call argument fragments and stop reasons are all shaped differently. `llm-sse` turns any of them into the same small set of events, so your streaming UI or agent loop stays provider-agnostic.
+Each API streams differently. OpenAI Responses sends typed `response.*` events,
+OpenAI Chat Completions sends `choices[].delta` chunks, Anthropic sends typed
+`content_block_*` / `message_*` events, and Gemini sends
+`candidates[].content.parts`. `llm-sse` turns all of them into the same small
+set of events, so your streaming UI or agent loop stays provider-agnostic.
+
+## Project
+
+- [Roadmap](./ROADMAP.md): compatibility, conformance, and sustainability priorities
+- [Contributing](./CONTRIBUTING.md): local setup, tests, and pull-request expectations
+- [Governance](./GOVERNANCE.md): decision process and the path to reviewer or maintainer
+- [Support](./SUPPORT.md): where to ask questions or report reproducible bugs
+- [Security](./SECURITY.md): private vulnerability reporting and supported versions
+- [Changelog](./CHANGELOG.md): release history and migration notes
+- [Code of Conduct](./CODE_OF_CONDUCT.md): community standards
 
 ## Quickstart
 
-### OpenAI
+### OpenAI Responses API
+
+```ts
+import { parseOpenAIResponsesStream } from 'llm-sse';
+
+const res = await fetch('https://api.openai.com/v1/responses', {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${key}`,
+    'content-type': 'application/json',
+  },
+  body: JSON.stringify({
+    model: process.env.OPENAI_MODEL,
+    input: 'What is the weather in Santiago?',
+    tools,
+    stream: true,
+  }),
+});
+
+for await (const event of parseOpenAIResponsesStream(res.body)) {
+  if (event.type === 'text') process.stdout.write(event.text);
+  if (event.type === 'tool_call_delta') {
+    process.stderr.write(event.argumentsDelta);
+  }
+}
+```
+
+The parser follows the official
+[Responses streaming event reference](https://platform.openai.com/docs/api-reference/responses-streaming),
+including output text, reasoning summaries, function-call arguments,
+refusal text, completion, incomplete responses, and errors. Refusal deltas use
+the normalized `text` channel so provider-agnostic UIs do not drop the model's
+response.
+
+### OpenAI Chat Completions
 
 ```ts
 import { parseOpenAIStream } from 'llm-sse';
@@ -29,7 +77,11 @@ const res = await fetch('https://api.openai.com/v1/chat/completions', {
     Authorization: `Bearer ${key}`,
     'content-type': 'application/json',
   },
-  body: JSON.stringify({ model: 'gpt-4o', messages, stream: true }),
+  body: JSON.stringify({
+    model: process.env.OPENAI_MODEL,
+    messages,
+    stream: true,
+  }),
 });
 
 for await (const event of parseOpenAIStream(res.body)) {
@@ -112,16 +164,29 @@ for await (const event of parseOpenAIStream(res.body)) {
 
 ## Why
 
-- **One event shape, three providers.** `text`, `tool_call_start`, `tool_call_delta`, `finish`, `error` — the same whether the bytes came from OpenAI, Anthropic or Gemini.
+- **One event shape, four streaming formats.** `text`, `reasoning`, `tool_call_start`, `tool_call_delta`, `finish`, and `error`, whether the bytes came from OpenAI Responses, OpenAI Chat Completions, Anthropic, or Gemini.
 - **Tool calls just accumulate.** Streamed JSON argument fragments carry an `index`; concatenate by index (or let `collectStream` do it) to get the full call.
 - **Correct SSE framing.** Robust to chunk boundaries splitting a line or event mid-way, CRLF, multi-line `data:` fields, comments and keep-alives.
 - **Fixture-backed provider coverage.** Public OpenAI, Anthropic and Gemini `.sse` fixtures exercise text, reasoning, tool-call arguments and finish reasons.
-- **Bytes or strings.** Feed it a `fetch()` `ReadableStream<Uint8Array>`, a Node stream, or an async iterable of strings — multibyte UTF-8 split across chunks is handled.
+- **Bytes or strings.** Feed it a `fetch()` `ReadableStream<Uint8Array>`, a Node stream, or an async iterable of strings. Multibyte UTF-8 split across chunks is handled.
 - **Zero dependencies**, ESM + CJS, fully typed.
 
+| Streaming source               | Parser                       | Text |     Reasoning     | Function calls | Finish and errors |
+| ------------------------------ | ---------------------------- | :--: | :---------------: | :------------: | :---------------: |
+| OpenAI Responses API           | `parseOpenAIResponsesStream` |  ✓   |         ✓         |       ✓        |         ✓         |
+| OpenAI Chat Completions        | `parseOpenAIStream`          |  ✓   | compatible fields |       ✓        |         ✓         |
+| Anthropic Messages             | `parseAnthropicStream`       |  ✓   |         ✓         |       ✓        |         ✓         |
+| Gemini `streamGenerateContent` | `parseGeminiStream`          |  ✓   |         ✓         |       ✓        |         ✓         |
+
 ## Why not the provider SDK?
 
-The official SDKs (openai, @anthropic-ai/sdk, @google/generative-ai) each ship their own streaming abstraction, so combining two providers means learning two APIs and writing two adapter paths in your agent or UI. `llm-sse` is a thin, zero-dependency layer that normalizes the wire format only. You keep your own fetch/retry/auth logic, and every provider becomes the same three event types. If you are already using a provider SDK exclusively and do not plan to switch, the SDK's streaming helpers may be sufficient; this library is most useful when you need provider portability, a minimal footprint, or control over the HTTP layer.
+The official SDKs each ship their own streaming abstraction, so combining APIs
+means learning multiple event models and writing multiple adapter paths in your
+agent or UI. `llm-sse` is a thin, zero-dependency layer that normalizes the wire
+format only. You keep your own fetch, retry, and authentication logic. If you
+use one provider exclusively, its SDK helpers may be sufficient; this library is
+most useful when you need provider portability, a minimal footprint, or control
+over the HTTP layer.
 
 ## Install
 
@@ -131,9 +196,16 @@ npm install llm-sse
 
 ## API
 
+### `parseOpenAIResponsesStream(source)`
+
+Parses typed OpenAI Responses API SSE events. It maps
+`response.output_text.delta`, reasoning deltas, function-call item and argument
+events, and terminal response states into normalized events. The Responses
+`output_index` is used as the normalized tool-call index.
+
 ### `parseOpenAIStream(source)` · `parseAnthropicStream(source)` · `parseGeminiStream(source)`
 
-Each takes a `source` (`AsyncIterable<Uint8Array | string>` — `fetch().body` satisfies this) and returns an `AsyncGenerator<StreamEvent>`.
+Each takes a `source` (`AsyncIterable<Uint8Array | string>`, `fetch().body` satisfies this) and returns an `AsyncGenerator<StreamEvent>`.
 
 > Gemini: use the SSE form of the streaming endpoint (`streamGenerateContent?alt=sse`).
 
@@ -141,7 +213,8 @@ Each takes a `source` (`AsyncIterable<Uint8Array | string>` — `fetch().body` s
 
 ### `parseStream(source, provider)`
 
-Same thing, dispatching on `provider` (`'openai' | 'anthropic' | 'gemini'`).
+Same thing, dispatching on `provider`
+(`'openai-responses' | 'openai' | 'anthropic' | 'gemini'`).
 
 ### `StreamEvent`
 
@@ -155,7 +228,9 @@ type StreamEvent =
   | { type: 'error'; error: unknown };
 ```
 
-> `reasoning` carries the model's thinking (Anthropic extended thinking `thinking_delta` and Gemini `thought` parts) separately from `text`, so you can render it in its own affordance or drop it.
+> `reasoning` carries OpenAI reasoning text or summaries, Anthropic extended
+> thinking, and Gemini thought parts separately from `text`, so you can render
+> it in its own affordance or drop it.
 
 ### `collectStream(events)`
 
@@ -165,12 +240,12 @@ Drains an event stream into a single message:
 const { text, reasoning, toolCalls, finishReason } = await collectStream(
   parseAnthropicStream(res.body),
 );
-// toolCalls: { index, id?, name?, arguments }[]  — arguments is the joined JSON string
+// toolCalls: { index, id?, name?, arguments }[], arguments is the joined JSON string
 ```
 
 ### `toAssistantMessage(collected)`
 
-Turn a collected stream into a standard OpenAI-shape assistant message — the format `llm-messages` treats as canonical — so a streamed response composes straight back into your history or into a different provider:
+Turn a collected stream into a standard OpenAI-shape assistant message, the format `llm-messages` treats as canonical, so a streamed response composes straight back into your history or into a different provider:
 
 ```ts
 import { collectStream, toAssistantMessage } from 'llm-sse';
@@ -271,13 +346,19 @@ const result2 = await complete('openai', openaiResponse);
 
 ## Tool calls
 
-All three providers are normalized to the same pattern: a `tool_call_start` (with `index`, and `id` / `name` when available) followed by one or more `tool_call_delta`s whose `argumentsDelta` strings concatenate into the call's JSON arguments. OpenAI and Anthropic fragment the arguments; Gemini sends them whole in a single delta. `collectStream` joins them for you.
+All supported APIs are normalized to the same pattern: a `tool_call_start`
+(with `index`, and `id` / `name` when available) followed by one or more
+`tool_call_delta`s whose `argumentsDelta` strings concatenate into the call's
+JSON arguments. OpenAI Responses uses its stable `output_index`; Chat
+Completions and Anthropic stream argument fragments; Gemini sends arguments
+whole in a single delta. `collectStream` joins them for you.
 
 ## Fixture corpus
 
 The package includes a small public fixture corpus under [`fixtures/`](https://github.com/slegarraga/llm-sse/tree/main/fixtures):
 
 - `openai-weather-tool.sse`
+- `openai-responses-weather-tool.sse`
 - `anthropic-weather-tool.sse`
 - `gemini-weather-tool.sse`
 - expected normalized events and collected messages under `fixtures/expected/`
@@ -287,6 +368,15 @@ Each fixture describes the same semantic turn: reasoning, visible text, a
 The tests parse the fixtures directly, including byte-split stream boundaries,
 so contributors can change parsers with a stable cross-provider contract.
 
+## Community
+
+Contributions are welcome, especially sanitized provider fixtures, reproducible
+edge cases, interoperability examples, and review help. Start with
+[CONTRIBUTING.md](./CONTRIBUTING.md), use
+[Discussions](https://github.com/slegarraga/llm-sse/discussions) for design
+questions, and see [GOVERNANCE.md](./GOVERNANCE.md) for how sustained
+contributors can become reviewers or maintainers.
+
 ## Related
 
 - [`json-from-llm`](https://www.npmjs.com/package/json-from-llm): extract valid JSON from an LLM response, even inside reasoning tags, fenced blocks or prose

package/ROADMAP.md

@@ -0,0 +1,64 @@
+# Roadmap
+
+`llm-sse` exists to make provider streaming predictable without requiring a
+provider SDK or adding runtime dependencies. The roadmap prioritizes correctness,
+interoperability, and evidence-backed support over adding providers by name.
+
+## Current priorities
+
+### 1. Streaming conformance
+
+- Keep the public fixture corpus aligned with documented OpenAI Responses,
+  OpenAI Chat Completions, Anthropic Messages, and Gemini event shapes.
+- Add regression fixtures for real provider edge cases after removing secrets
+  and user content.
+- Preserve byte-boundary, line-ending, malformed-event, and multi-tool coverage.
+
+### 2. Provider portability
+
+- Keep normalized text, reasoning, tool-call, finish, and error events stable.
+- Document unavoidable information loss between provider formats.
+- Improve composition with
+  [`llm-messages`](https://github.com/slegarraga/llm-messages),
+  [`tool-schema`](https://github.com/slegarraga/tool-schema), and
+  [`llm-errors`](https://github.com/slegarraga/llm-errors).
+
+### 3. Maintainer workflows
+
+- Make provider-behavior changes reviewable through small fixtures and explicit
+  links to primary documentation.
+- Automate compatibility reports, release notes, and routine issue triage while
+  keeping release decisions human-reviewed.
+- Publish enough project context for contributors to reproduce and own an area
+  of the parser.
+
+### 4. Sustainable community
+
+- Grow usage through real integrations and examples rather than synthetic stars
+  or low-value promotion.
+- Welcome additional reviewers and maintainers through the path described in
+  [GOVERNANCE.md](./GOVERNANCE.md).
+- Track breaking proposals in public issues before implementation.
+
+## API credit use
+
+If the project receives sponsored API credits, they will be used for opt-in
+conformance checks against official provider endpoints, fixture refreshes,
+regression reproduction, and maintainer automation. Secrets and user prompts
+will not be committed. Pull requests will continue to run deterministically
+against sanitized offline fixtures.
+
+## Non-goals
+
+- Replacing full provider SDKs.
+- Managing authentication, retries, billing, or network requests.
+- Claiming compatibility with an endpoint without a documented event format or
+  reproducible fixture.
+- Adding runtime dependencies for convenience.
+
+## Propose an item
+
+Open a [GitHub Discussion](https://github.com/slegarraga/llm-sse/discussions)
+for design exploration or a
+[feature request](https://github.com/slegarraga/llm-sse/issues/new?template=feature_request.yml)
+for a scoped, testable change.

package/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported versions
+
+The latest published `0.x` release receives security fixes.
+
+## Reporting a vulnerability
+
+Please report security issues privately rather than opening a public issue.
+
+- Use GitHub's [private vulnerability reporting](https://github.com/slegarraga/llm-sse/security/advisories/new), or
+- Email **sebastian@0a.cl** with the details.
+
+Include a description, a reproduction, and the impact. You can expect an initial
+response within a few days. Once a fix is released, we are happy to credit you in
+the advisory unless you prefer to remain anonymous.
+
+## Scope
+
+`llm-sse` has zero runtime dependencies and performs only in-memory parsing
+of streamed text: it does not make network requests, read or write files, or
+execute code from its input. The most relevant risks are denial of service from
+pathological input (for example, unbounded buffering on a stream with no event
+delimiters). Reports along those lines are welcome.

package/SUPPORT.md

@@ -0,0 +1,38 @@
+# Support
+
+`llm-sse` is maintained in public on a best-effort basis.
+
+## Questions and design discussions
+
+Use [GitHub Discussions](https://github.com/slegarraga/llm-sse/discussions) for
+integration questions, design exploration, and help choosing the right parser.
+
+## Bugs
+
+Open a
+[bug report](https://github.com/slegarraga/llm-sse/issues/new?template=bug_report.yml)
+with:
+
+- the provider and API surface;
+- a minimal, sanitized sequence of SSE `data:` payloads;
+- the normalized events you expected and received;
+- the `llm-sse`, Node.js, and runtime versions;
+- a reproduction or failing test when possible.
+
+Please do not include API keys, private prompts, personal data, or proprietary
+model output.
+
+## Security
+
+Do not open a public issue for a vulnerability. Follow
+[SECURITY.md](./SECURITY.md) to use GitHub private vulnerability reporting or
+the listed security email.
+
+## Scope
+
+The project can help with parsing and normalization behavior. Provider account
+access, billing, rate limits, model availability, and general SDK support belong
+with the relevant provider.
+
+No response-time guarantee is offered, but well-scoped reproductions and pull
+requests are prioritized.