docs: update README.md - #502
Merged
Merged
Conversation
github-actions
Bot
added
documentation
📝 WalkthroughSummary by CodeRabbit
WalkthroughREADME documentation was rewritten and reorganized. The changes update product messaging, quick-start and setup guidance, project status text, and contribution, security, and AI disclosure sections. A PostHog setup report was removed. ChangesREADME Documentation
PostHog report removal
Estimated code review effort: 1 (Trivial) | ~5 minutes Merge Risk: 🟡 Moderate · up to The README currently provides incomplete startup guidance and insufficiently clear security/reporting instructions, including tokenless local usage and vulnerability-report routing. Merge should wait until these bounded documentation issues are corrected or explicitly accepted by the owner. Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 9247b8b2-a246-483c-9b38-2d0e87d2c767
📒 Files selected for processing (1)
README.md
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.
📜 Review details
⏰ Context from checks skipped due to timeout. (4)
- GitHub Check: Lint
- GitHub Check: Analyze (go)
- GitHub Check: Analyze (go)
- GitHub Check: Analyze (javascript-typescript)
⚠️ CI failures not shown inline (3)
GitHub Actions: PR housekeeping / PR housekeeping: chore(docs): Update README.md
Conclusion: failure
##[group]Run # Single source of truth for the rule: scripts/lint-pr-title.sh — the
�[36;1m# Single source of truth for the rule: scripts/lint-pr-title.sh — the�[0m
�[36;1m# SAME validator the local agent gate runs (.claude/hooks/agent-bash-gate.sh),�[0m
�[36;1m# so CI and local can't drift. The checkout above is ref: main, so this is�[0m
�[36;1m# always the default-branch script. Dependabot's grouped-update titles�[0m
�[36;1m# routinely exceed the 72-char subject cap and the format isn't�[0m
�[36;1m# configurable, so Dependabot PRs are exempt from the length check�[0m
�[36;1m# (the format check still applies).�[0m
�[36;1mif [[ "$PR_AUTHOR" == "dependabot[bot]" || "$PR_AUTHOR" == "app/dependabot" ]]; then�[0m
�[36;1m export PR_TITLE_SKIP_LENGTH=1�[0m
�[36;1mfi�[0m
�[36;1m�[0m
�[36;1mif reason=$(bash scripts/lint-pr-title.sh "$PR_TITLE" 2>&1); then�[0m
�[36;1m echo "passed=true" >> "$GITHUB_OUTPUT"�[0m
�[36;1m echo "PR title OK: $PR_TITLE"�[0m
�[36;1melse�[0m
�[36;1m echo "passed=false" >> "$GITHUB_OUTPUT"�[0m
�[36;1m printf '%s\n' "$reason"�[0m
�[36;1m echo "::error::$(printf '%s' "$reason" | head -1)"�[0m
GitHub Actions: PR housekeeping / PR housekeeping: chore(docs): Update README.md
Conclusion: failure
##[group]Run exit 1
�[36;1mexit 1�[0m
shell: /usr/bin/bash -e {0}
##[endgroup]
##[error]Process completed with exit code 1.
GitHub Actions: PR housekeeping / 0_PR housekeeping.txt: chore(docs): Update README.md
Conclusion: failure
##[group]Run # Single source of truth for the rule: scripts/lint-pr-title.sh — the
�[36;1m# Single source of truth for the rule: scripts/lint-pr-title.sh — the�[0m
�[36;1m# SAME validator the local agent gate runs (.claude/hooks/agent-bash-gate.sh),�[0m
�[36;1m# so CI and local can't drift. The checkout above is ref: main, so this is�[0m
�[36;1m# always the default-branch script. Dependabot's grouped-update titles�[0m
�[36;1m# routinely exceed the 72-char subject cap and the format isn't�[0m
�[36;1m# configurable, so Dependabot PRs are exempt from the length check�[0m
�[36;1m# (the format check still applies).�[0m
�[36;1mif [[ "$PR_AUTHOR" == "dependabot[bot]" || "$PR_AUTHOR" == "app/dependabot" ]]; then�[0m
�[36;1m export PR_TITLE_SKIP_LENGTH=1�[0m
�[36;1mfi�[0m
�[36;1m�[0m
�[36;1mif reason=$(bash scripts/lint-pr-title.sh "$PR_TITLE" 2>&1); then�[0m
�[36;1m echo "passed=true" >> "$GITHUB_OUTPUT"�[0m
�[36;1m echo "PR title OK: $PR_TITLE"�[0m
�[36;1melse�[0m
�[36;1m echo "passed=false" >> "$GITHUB_OUTPUT"�[0m
�[36;1m printf '%s\n' "$reason"�[0m
�[36;1m echo "::error::$(printf '%s' "$reason" | head -1)"�[0m
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{go,ts,tsx,js,jsx,md,mdx,yaml,yml,json}
📄 CodeRabbit inference engine (AGENTS.md)
Every code change updates its docs +
CHANGELOG.mdin the same PR
Files:
README.md
**/*.{md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
- Never hard-wrap prose. One paragraph is one line. No wrapping at 72/80 columns, no "semantic linefeeds" splitting a paragraph at sentence boundaries.
Files:
README.md
🧠 Learnings (1)
📚 Learning: 2026-06-10T15:01:09.027Z
Learnt from: EricAndrechek
Repo: Wave-RF/WaveHouse PR: 312
File: docs/src/content/docs/development.md:0-0
Timestamp: 2026-06-10T15:01:09.027Z
Learning: In this repo’s Markdown review (all .md files), do not flag capitalization/style issues for literal paths starting with ".github/" (or any substring that is a path beginning with ".github/"). Treat ".github" as the correct lowercase dotfile directory name, even when it appears inside prose or code spans; automated checks such as LanguageTool’s "(GITHUB)" rule commonly produce false positives for this literal filesystem path.
Applied to files:
README.md
🔇 Additional comments (4)
README.md (4)
10-22: LGTM!
35-38: LGTM!
49-67: LGTM!Also applies to: 79-81
121-129: LGTM!Also applies to: 139-151
github-project-automation
Bot
moved this from Backlog
to In review
in WaveHouse Task Board
EricAndrechek
approved these changes
Aug 20, 2026
|
📚 Docs preview is live → https://694fe9e4-wavehouse-docs.wave-rf.workers.dev
|
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
README.md (2)
105-105: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick winRepeat the local-only warning in this walkthrough.
This paragraph tells users that tokenless ingest is available, but it does not state that the permissive policy is for local development only or that users must not expose port 8080.
Makefile:254-259documents authentication as disabled by default. Add the explicit warning here, as in the Quick Start walkthrough.
96-130: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAdd start commands for the container and binary paths.
Lines 109-112 only pull the container image. Lines 126-128 only install the binary. Neither path starts WaveHouse or shows the required runtime configuration. Add tested start commands for both paths, or label these sections as download/install instructions and link to complete launch instructions.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 7ad3e920-a364-4a41-872a-5003fc5109af
📒 Files selected for processing (2)
README.mddocs/posthog-setup-report.md
💤 Files with no reviewable changes (1)
- docs/posthog-setup-report.md
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
- GitHub Check: Docs build
- GitHub Check: Analyze (go)
- GitHub Check: Analyze (go)
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{go,ts,tsx,js,jsx,md,mdx,yaml,yml,json}
📄 CodeRabbit inference engine (AGENTS.md)
Every code change updates its docs +
CHANGELOG.mdin the same PR
Files:
README.md
**/*.{md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
- Never hard-wrap prose. One paragraph is one line. No wrapping at 72/80 columns, no "semantic linefeeds" splitting a paragraph at sentence boundaries.
Files:
README.md
🔇 Additional comments (3)
README.md (3)
22-23: 📐 Maintainability & Code QualityConfirm the required
CHANGELOG.mdupdate.The provided cohort changes
README.md, but it does not include aCHANGELOG.mddiff. Confirm that the same PR adds the required changelog entry. If it does not, add one.As per coding guidelines: Every code change in a file matching
**/*.{go,ts,tsx,js,jsx,md,mdx,yaml,yml,json}updates its docs andCHANGELOG.mdin the same PR.Source: Coding guidelines
35-65: LGTM!
92-95: LGTM!Also applies to: 154-166
github-project-automation
Bot
moved this from In review
to In progress
in WaveHouse Task Board
github-project-automation
Bot
moved this from In progress
to Done
in WaveHouse Task Board
This was referenced Aug 21, 2026
EricAndrechek
added a commit
that referenced
this pull request
Aug 26, 2026
## Summary `#502` rewrote the README badge row and dropped the **Go Coverage** badge, but nothing removed what fed it. For the six days since, the non-gating `badge` job kept firing on every main push — holding `ci.yml`'s **only `contents: write`**, publishing `coverage-go.json` to the orphan `badges` branch — for a badge no page renders. Retired rather than restored (`#509`). This removes: - the `badge` job and its two producer steps in `coverage` (`cov badge` + the `go-coverage-badge` artifact) - `scripts/ci/publish-badge.sh` - the `cov badge` subcommand (`badgeData`, `badgeColor`, and the now-unused `encoding/json` import) - the stale comments in `ci.yml`, `.github/workflows/README.md`, `.testcoverage.yml`, and `AGENTS.md` that still described a badge the README hadn't had in weeks **The coverage gate is completely untouched.** `make cov`, `.testcoverage.yml`'s `threshold.total` and per-suite minima, and the GitHub Code Quality PR comments (the other half of `#133`) all still run. Only the published badge surface is gone. ### The reason to prefer retiring over restoring **`ci.yml` now declares no `contents: write` in any job.** The `badge` job was its only holder, so the workflow that executes PR-authored code can no longer write to the repository under any path. Verified by parsing the workflow: the only remaining `:write` scopes anywhere in `ci.yml` are `code-quality: write` on `coverage` and `issues`/`pull-requests: write` on `docs-preview`. Restoring a coverage badge later means restoring that permission *if it is done in this shape* — publishing into the repo. `.github/workflows/README.md` now says so explicitly, and points at the cheaper alternative: a shields endpoint hosted outside the repo costs no write scope at all. ### Latent break fixed in passing `timing`'s `needs` list still contained `badge`. A `needs` pointing at a job that no longer exists is a **workflow-level error**, so removing the job without this would have broken every CI run. Caught by a structural parse of the workflow, then confirmed by `actionlint`. ### Permission comments corrected Two claims in `ci.yml` were wrong and are fixed here, since this PR is about not leaving false permission statements lying around: - The "sole holder of `contents:write`" comments were repo-wide claims only ever true *within* `ci.yml` — `release.yml:9` and `publish-npm.yml:195` hold it too. - The workflow header said `docs-preview` was the only job holding a write scope. That undercounted `coverage`'s `code-quality: write` — which it holds while checking out and executing the **PR tree**. ### Go Report Card Also retired, per `#509` — but there is **no diff for it**: `#502` had already removed the repo's only reference. Recorded in the CHANGELOG so the decision is written down rather than rediscovered. It isn't coming back: goreportcard.com is deprecated upstream, and what it graded (gofmt, vet, lint, misspell) is gated far more strictly by `make lint-go` in CI. ## Test plan - `make lint-gha` (actionlint) ✅ — the load-bearing check here; catches dangling `needs` - `make lint-sh` ✅ (shellcheck, after the script deletion) - `make lint-md` / `lint-prose` / `test-md-rules` ✅ - `tidy`, `fmt-go`, `vulncheck`, `typecheck-ts`, `check-docs`, `test-classify-paths`, `test-release-channel` ✅ - `go vet ./scripts/cov/` ✅ and `go run ./scripts/cov threshold total` → `80` (config parsing intact after the surgery) - Structural parse of `ci.yml`: `badge` job absent, **zero dangling `needs`**, zero `contents: write` - `make ci` green end-to-end, and `make verify` green via the pre-commit hook (both run as `GOTOOLCHAIN=go1.26.6`, matching `go.mod` and CI exactly; the repo-pinned golangci-lint v2.11.4 panics against this machine's local Go 1.27, which is environmental and does not affect CI) - Two rounds of the pre-push code and docs reviewers; round 1 returned `iterate` on four documentation-accuracy findings, all fixed in the second commit ##⚠️ Required post-merge step The orphan **`badges` branch still exists** and must be deleted *after* this merges — the command is a `--delete` push of the `badges` ref to origin. It cannot be deleted before merge: while the `badge` job still exists on `main`, the next code push recreates it (`if: push && ref == main && changes.code == 'true'`). This is part of `#509`'s scope, so **the issue should not be closed until the branch is gone.** This PR therefore says `Refs`, not `Closes` — close `#509` by hand once the branch is deleted, so the last step keeps its tracker instead of relying on a CHANGELOG sentence to carry it. ## Related Issues Refs #509 (close manually after deleting the `badges` branch), #133, #502, #501 Spun out of review on this PR: **#521** — `WH001` (no-hard-wrapped-prose) is disabled under `.github/` and `.claude/`, contradicting `CONTRIBUTING.md`'s promise that it's enforced everywhere. That exclusion is why the hard-wrapped bullet in this PR reached review at all. Fixed here for this PR's own prose; the reflow (**53 hard-wrapped paragraphs**, which WH001 reports as 292 violation lines since it emits one per line) and the config removal are tracked there. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
EricAndrechek
added a commit
that referenced
this pull request
Aug 26, 2026
Unlike docs/posthog-setup-report.md — a real file deleted in #502 that left a stale reference behind — PERF-CLAIMS-REVIEW.md was never tracked at all (`git log --all` finds nothing) and isn't gitignored, so the entry guarded a document that has never existed in this repo. The denylist's other general cases are patterns (*.draft.md, *.old.md) that already cover a one-off review write-up. A literal filename for a hypothetical file, restated in four places, is the outlier — and this PR is about not leaving speculative claims lying around in comments. Removed from all four lockstep locations, per the header rule the previous commit corrected. `scripts/docs-prose.sh all` still resolves the same 27-file prose set. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MB4oPy9yfUHSe8FjnDmeZH
EricAndrechek
added a commit
that referenced
this pull request
Aug 26, 2026
Two path-scoped configs — `.github/.markdownlint.json` and `.claude/.markdownlint.json` — held nothing but `"WH001": false`, silently switching the no-hard-wrapped-prose rule off for CI docs and agent prompts ever since #489 introduced it. `CONTRIBUTING.md:97` tells contributors `make lint` enforces WH001 **everywhere**, while `AGENTS.md:342` and the `.markdownlint-cli2.jsonc` header wrote up the carve-out — three descriptions of one rule, disagreeing. That cost a round trip on #520: a reviewer correctly flagged a hard-wrapped bullet in `.github/workflows/README.md`, an agent pointed at `"WH001": false` for that path and pushed back, and the reviewer recorded a persistent *learning* never to flag WH001 there — the wrong invariant, learned off the wrong side of the contradiction. ## What changed - **Both configs deleted.** Each held only `extends` + the override, so the root `.markdownlint.json` (`"WH001": true`) governs again. The `ignores` array is untouched — there is now **no path-scoped carve-out of any kind**. - **51 hard-wrapped paragraphs reflowed** by `make fix`: 41 in `.github/workflows/README.md` (378 → 171 lines), 10 in `.claude/skills/pm-triage/references/routine.md`. Mechanical joins; no wording changed. - **The vendored PostHog skill is deleted** — `.claude/skills/integration-astro-view-transitions/`, 9 files / ~1,456 lines including an 809-line `EXAMPLE.md` copied wholesale from `PostHog/context-mill`. Its integration job finished in #277, nothing in the repo calls it, and the live docs-site setup is documented in `docs/src/components/PostHog.astro` and the CHANGELOG. Unowned third-party prose drifts silently on every upstream bump and nobody here reviews it — and it was the single file that would have needed a special-case exclusion, so removing it is what lets the rule apply with **no exception at all** rather than one documented one. - **Docs reconciled** so all four descriptions agree. `AGENTS.md:342` and the config header rewritten; `AGENTS.md:326` and `CONTRIBUTING.md:97` already said "everywhere" and are now true. `AGENTS.md:342` also tells future readers *not* to reintroduce a subtree override, pointing at an in-file `markdownlint-disable` as the visible escape hatch — verified to actually work, block form only. - **Two dead denylist entries swept.** `docs/posthog-setup-report.md` (the wizard's other artifact, deleted in #502) and `PERF-CLAIMS-REVIEW.md` — which was never tracked at all, so it guarded a file that has never existed. The list's other general cases are patterns (`*.draft.md`, `*.old.md`) that already cover a one-off review document. Removed from all four lockstep locations; `scripts/docs-prose.sh all` still resolves the same 27-file prose set. ## What review turned up None of this was in #521's scope. All of it is the same defect class — documentation asserting a state of the world that had moved on — which is what made a whole-file read worth doing. - **WH001 has a blind spot.** `no-hard-wrapped-prose.mjs:139` classifies any line indented four or more spaces as an indented code block, so a **nested** list item is never joined. Three hard-wrapped bullets sat in `.github/workflows/README.md` — in the very file this PR reflowed — invisible to the autofix. Unwrapped by hand; they were the last hard-wrapped prose paragraphs in the repo. - **That made a documented rule false.** `AGENTS.md:326` and `development.md:432` both promised "a list item is joined as a unit". Not for nested items — a contributor would expect `make fix` to unwrap one and it silently doesn't. Both now state the four-space caveat. - **`scripts/docs-prose.sh`'s header undercounted its own lockstep set**, naming two sibling copies of the denylist when there are three. The missed one is `.claude/agents/docs-reviewer.md` — the gating subagent's own system prompt — which `git log -S` shows had been out of sync for the entire life of the `posthog-setup-report.md` exclusion, and agreed only by accident of this branch removing it. - **The job graph contradicted itself.** `docs-deploy` was drawn without its `needs` edges from `unit`, `integration`, and `e2e`, and `ci`/`docs-preview` were missing `changes` — while the legend three lines below states "Solid arrows are `needs` edges" and `changes --> deploy` *was* drawn. Five edges added; the diagram now matches `ci.yml` edge-for-edge in both directions. - **`claude-code.md` deferred to work that had already shipped.** It told readers that "when #121 lands a SigNoz dev stack with `make dev-obs`" Grafana MCP would become useful. #121 closed as *completed* in May, `dev-obs` exists nowhere in the tree (the real targets are `obs-aspire` / `obs-grafana` / `obs-front`), and `deployment.md` states outright that no heavy multi-node cluster like SigNoz is maintained for local development. Now points at `make obs-grafana`. Filed rather than fixed here: **#523**, where `deployment.md` claims all three local observability stacks publish OTLP `4318`, but only `obs-front` does. ## Test plan - `make ci` green end to end on the final tree, marker matches HEAD. - `markdownlint-cli2` reports 0 issues over all 42 tracked `.md`, and `pnpm lint:md` 0 over all 48 tracked `.md` + `.mdx` — "every tracked Markdown file" is literally, not approximately, true. `make fix` is a fixpoint. - **Reflow safety proven, not eyeballed.** Reviewers reconstructed the pre-image files, re-ran the repo's own `markdownlint-cli2 --fix`, and diffed: the branch files are **byte-identical to the autofix output**, ruling out a hand-edit in the reflow. Independently, word-level diffs against `main` show `routine.md` is word-for-word identical and `.github/workflows/README.md`'s only content changes are the five graph edges and the past-tensed badges sentence. - **"Last hard-wrapped prose in the repo" was checked against WH001's own blind spot** rather than its 0-issue result: a scan of all 48 tracked files for nested list items with 4-space continuations found four hits, all YAML frontmatter. No prose. - Every drawn graph edge verified against `ci.yml`'s `needs`, both directions — nine into `ci`, seven into `docs-deploy`, two into `docs-preview`, none spurious. - `shellcheck` + `bash -n` clean on `docs-prose.sh`; the new `/deployment#local-observability-stack` anchor is validated by `starlight-links-validator` during `make ci`'s docs build. Closes #521 --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Updated README.md for general readability + reordering some sections.
Test plan
Related Issues