docs: add alternatives, glossary, and why-a-gateway

[sunib]

What

Three new docs for a first-time reader, plus one npm keyword.

docs/alternatives.md — where krm-stream sits relative to existing work: Kubernetes client libraries, browser dashboards (Headlamp is the closest architectural precedent for the gateway, not hawtio), config-as-data systems, and CRDT/merge libraries. Ends with the claim we can actually defend, which is the combination rather than "first Kubernetes streaming library". gitops-reverser is covered as the write-and-record half of the same loop rather than as a competitor, and is deliberately absent from the comparison table for that reason.

docs/glossary.md — the Kubernetes vocabulary a frontend developer needs, on the assumption that a first-time user of this library may never have touched a cluster. About a dozen terms, then a walk of the read and write paths that pins each term to a real place in the code.

docs/why-a-gateway.md — why the browser cannot watch the API server directly, and why watches are shared. The README carries a short version and links here.

config-as-data added to the npm keywords; it ships with the next release-please cut.

Two things worth a reviewer's attention

A watch is not a protocol upgrade. It is a plain GET ?watch=1 returning chunked newline-delimited JSON. Upgrades are what exec/attach/port-forward need. The real obstacles to watching from a browser are the cluster credential, the absence of CORS on the API server, and the fact that a watch returns whole objects including Secret data. The doc says that, and says the transport is explicitly not the problem.

ValidateMergePatch does not blanket-block status. Reading gateway/patch.go: it rejects redacted paths, metadata.managedFields and the last-applied annotation always, but /status only under ProjectionSpec. The glossary states it that way rather than the broader claim.

Docs only, plus one keyword. task lint-client passes.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added guidance explaining the gateway’s role in safely streaming Kubernetes resources to browsers.
  • Added a glossary covering Kubernetes resources, streaming, editing, merging, and conflict handling.
  • Added an alternatives and prior art guide comparing related tools and approaches.
  • Expanded the README with new guides and architectural context.
• Chores
  • Added “config-as-data” to the package’s searchable keywords.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b3001529-8c92-4119-8a89-269dcb1e4091

📥 Commits

Reviewing files that changed from the base of the PR and between e4ed804 and 204613a.

📒 Files selected for processing (5)

• README.md
• docs/alternatives.md
• docs/glossary.md
• docs/why-a-gateway.md
• packages/krm-stream/package.json

---

📝 Walkthrough

Walkthrough

The changes add documentation for gateway architecture, frontend terminology, and related projects; update README guide links; and add config-as-data to the package keywords.

Changes

Documentation and metadata

Layer / File(s)	Summary
Gateway and frontend guidance README.md, docs/why-a-gateway.md, docs/glossary.md	Documents Kubernetes watch limitations, gateway responsibilities, shared watches, frontend concepts, merge behavior, and related guides.
Alternatives and project positioning docs/alternatives.md, packages/krm-stream/package.json	Compares krm-stream with Kubernetes clients, browser UIs, config-as-data systems, local-first tools, and caching libraries; adds the config-as-data package keyword.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding three documentation pages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/alternatives-glossary-why

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}