Repository navigation
docs: add the top README preview, badges and contributor guide - #407
Merged
Merged
Conversation
what changed: The README opens with an original accessible SVG workflow overview, followed by linked Shields badges for tests/CI, PolyForm Shield 1.0.0, last commit and stars. Added contributor setup, verification, issue-label and PR guidance, quick links and the requested closing star note. why: Make the repository easier to understand and contribute to from its first screen. The user requested a professional preview at the top, like SmartRouter's workflow graphic, plus useful badges and contribution documentation. The current Research-Kit name and research-first tagline remain the presentation identity; no behavior decision or alternative was set aside. what it touched: README.md, CONTRIBUTING.md, docs/assets/research-overview.svg and CHANGELOG.md. No declared code path changed, so no architecture-map or test-inventory change is owed. Existing GitHub Actions supply the CI status; the project is distributed as source and has no npm/PyPI download badge. what you verified: verified - SVG rendered and inspected at full and 830-pixel README width; its XML parses and its accessible labels and self-contained assets were checked. All 40 relative file links in README/CONTRIBUTING resolve. Every badge endpoint returned usable SVG, the workflow badge reported passing and the license label matches LICENSE. Preview is the first README block and the support note is the last. Handoff OK, preflight PASS (28 passing, one existing unstamped-brief warning), doctor READY collector/firecrawl-cli with existing deployment/edit-registration warnings, and git diff --check clean. A docs-only commit uses the normal commit gate; GitHub PR CI remains untested until publication. what you got wrong and fixed: mistake - the first preview badge label slightly clipped, the contribution draft guessed ADR-0117's filename, and the external-badge verifier assumed every SVG had a title. where - draft SVG badge, contribution freeze link and local verification helper. impact - visual clipping, one broken draft link, and a false refusal of Shields' valid stars SVG; no delivered change affected. cause - width and the exact slug were not checked before drafting, and the stars response shape was assumed. fix - widen the badge, adjust a long caption, use the actual ADR filename, and verify the stars response's linked label and numeric count; its README image has alt text. verified - the revised preview was inspected at README width, all local targets resolve and all four badge responses pass validation.
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
1 participant
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.
The README now opens with a polished, accessible workflow preview, making the research path and authored brief handoff visible before the title and setup guide.
what changed: Added an original navy/teal SVG hero at the very top, linked Shields badges for tests/CI, PolyForm Shield 1.0.0, last commit and stars, quick links, CONTRIBUTING.md, and the requested closing star note.
why: Help visitors understand the project quickly and give contributors a concrete setup, verification and PR workflow. The preview follows the diagram approach used in SmartRouter and describes this kit's actual workflow.
what it touched: README.md, CONTRIBUTING.md, docs/assets/research-overview.svg and CHANGELOG.md. Existing GitHub Actions provide the real CI status. The guide follows AGENTS.md's feature freeze, map, regression, commit-report and one-task-per-commit rules.
what you verified: verified — preview rendered and inspected at full and normal README width; SVG XML, accessibility labels and self-contained assets checked; all 40 local file-link targets exist; all four badge endpoints validated; preview is the first README block and the star note is last. Handoff OK, preflight PASS (28 checks and one existing warning), doctor READY collector/firecrawl-cli with existing deployment/edit-registration warnings, and the normal docs commit gate passed. All seven GitHub CI jobs passed on 8c93a99: offline-suite run.
what you got wrong and fixed: mistake — the first draft clipped a badge label, guessed an ADR filename and assumed every external badge SVG had a title. where — unpublished preview/contribution drafts and the local verification helper. impact — visual clipping, one broken draft link and a false refusal of the valid stars badge; no delivered product change was affected. cause — draft layout, slug and response shape assumptions. fix — adjust label spacing, use the actual ADR filename and validate the stars label/count with README alt text. verified — final visual, link and badge checks passed.