Skip to content

docs: align README with landing page#93

Merged
ian-pascoe merged 13 commits into
mainfrom
docs/align-readme-with-landing
May 28, 2026
Merged

docs: align README with landing page#93
ian-pascoe merged 13 commits into
mainfrom
docs/align-readme-with-landing

Conversation

@ian-pascoe
Copy link
Copy Markdown
Contributor

@ian-pascoe ian-pascoe commented May 28, 2026

Summary

  • Align README positioning with the landing page source of truth
  • Add the caplets.dev landing page link near the README header
  • Update quick start and trust/progressive-disclosure sections to match landing messaging

Test Plan

  • pnpm format:check -- README.md
  • pnpm verify

Summary by CodeRabbit

  • Documentation
    • Updated product messaging, hero tagline, Quick Start, onboarding flow, and expanded design model with trust/ error-handling guidance.
  • Chores
    • Adjusted changeset handling and removed an automated reminder workflow.
  • Developer Tooling
    • Added commit/check automation for local context and enhanced commit hooks.
  • Tests
    • Added tests validating the new commit/check automation behavior.

Review Change Stack

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 28, 2026

Warning

Review limit reached

@ian-pascoe, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 22 minutes and 10 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a676d003-f5c7-4449-908e-272e345917eb

📥 Commits

Reviewing files that changed from the base of the PR and between 947a9ec and e076c44.

⛔ Files ignored due to path filters (1)
  • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
📒 Files selected for processing (8)
  • .github/workflows/deploy.yml
  • .github/workflows/pr-preview-deploy.yml
  • .husky/pre-commit
  • .lintstagedrc.json
  • alchemy.run.ts
  • package.json
  • scripts/commit-byterover-context.test.ts
  • scripts/commit-byterover-context.ts
📝 Walkthrough

Walkthrough

Docs and landing copy rewritten to emphasize capability-first agent integration and Trust Before Invocation. Added an executable script to auto-commit .brv context with tests, and adjusted changeset config, CI job condition, and husky hooks to call the new script.

Changes

Marketing and Landing Copy

Layer / File(s) Summary
README: hero, Quick Start, onboarding, design
README.md
Hero tagline and Quick Start rewritten; onboarding/how agents use it reorganized; "Why It Matters" replaced with a choose/inspect/resolve/invoke progression; "Design Model" expanded with Trust Before Invocation and scoped error/redaction discussion.
Landing site copy
apps/landing/src/pages/index.astro
Hero and trace step text, trust mechanics, backendssources, section headings and footer updated to match capability-first framing.

Repository automation and hooks

Layer / File(s) Summary
Changeset/CI/hooks
.changeset/config.json, .github/workflows/ci.yml, .husky/post-commit, .husky/pre-push
.changeset/config.json now ignores @caplets/landing. CI changeset job condition updated to check for label [no changeset]. Husky post-commit and pre-push hooks call scripts/commit-byterover-context.ts (pre-push uses --check).
Auto-commit script and tests
scripts/commit-byterover-context.ts, scripts/commit-byterover-context.test.ts
Adds executable script to detect/stage/commit .brv changes with a recursion guard, exported helpers (checkByteRoverStatus, buildCommitArgs, formatCheckWarning, main), and Vitest tests covering parsing, messages, commit args, and shebang presence.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Poem

🐰 I hopped through docs with a tidy tap,

Changed hero lines and polished the map,
A script now tends .brv in the night,
Hooks call politely to keep commits right,
Caplets give agents capabilities—hop, delight!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs: align README with landing page' clearly and concisely summarizes the main objective of this changeset, which is to update documentation files to match the landing page as the source of truth.
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.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/align-readme-with-landing

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

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 28, 2026

🚀 Preview Deployed

Your changes have been deployed to a preview environment:

🌐 Landing Page: https://pr-93.preview.caplets.dev

Built from commit 6855638


🤖 This comment updates automatically with each push.

@greptile-apps
Copy link
Copy Markdown
Contributor

greptile-apps Bot commented May 28, 2026

Greptile Summary

This PR aligns the README with the landing page's updated messaging and bundles several developer-tooling improvements: lint-staged for faster pre-commit checks, a post-commit hook that auto-commits .brv ByteRover context files, PR preview environment cleanup on close, and a www. subdomain added to the Cloudflare landing page registration.

  • README / landing copy: Hero tagline, Quick Start flow, Design Model, and Trust sections are rewritten to match the landing page; the skillify framing is replaced throughout with "capability" language.
  • PR preview lifecycle: pr-preview-deploy.yml now handles the closed event with a dedicated Destroy step that tears down the Cloudflare preview environment using alchemy:destroy.
  • Local dev hooks: Pre-commit is streamlined to lint-staged (only staged files checked), and a new post-commit hook commits any pending .brv context changes using a recursion-guarded script.

Confidence Score: 5/5

Safe to merge; changes are mostly copy alignment and developer tooling with no impact on published library code.

The core library packages are untouched. README and landing copy are straightforward text changes. The new post-commit hook is guarded against re-entrancy and fails safely without blocking commits. The preview lifecycle additions in the workflow are logically correct: deploy and destroy are mutually exclusive steps conditioned on the event action, and alchemy:destroy was already a defined script.

No files require special attention beyond what was already flagged in prior review threads on ci.yml and deploy.yml.

Important Files Changed

Filename Overview
README.md Documentation-only update aligning product copy with the landing page; hero tagline, Quick Start, and Design Model sections revised.
apps/landing/src/pages/index.astro Copy and label updates: renamed variables (skillifyFramework → capabilityFramework, backends → sources), updated section headings and microcopy throughout.
.github/workflows/pr-preview-deploy.yml Adds path filtering, restricted PR event types, and a new Destroy preview step that tears down Cloudflare resources when a PR is closed.
.github/workflows/deploy.yml Trigger changed from release:published to push:main with a paths filter; production CD now fires on every matching push without a required approval gate.
.github/workflows/ci.yml Label bypass string changed from 'no changeset' to '[no changeset]', which may silently break the bypass for PRs carrying the old label.
alchemy.run.ts Refactored domain variables, added www subdomain registration, exported landingPage, and replaced landingPage.url with a locally constructed URL string.
scripts/commit-byterover-context.ts New post-commit helper that stages and commits .brv context changes; uses a recursion guard env var to prevent re-entrancy from the post-commit hook.
scripts/commit-byterover-context.test.ts Unit tests for the three pure helper functions (checkByteRoverStatus, formatCheckWarning, buildCommitArgs); main() flow not directly covered.
.husky/pre-commit Replaced full format:check + lint + typecheck with lint-staged so only staged files are checked at commit time; typecheck deferred to pre-push verify.
.husky/post-commit New hook that runs commit-byterover-context.ts after every commit to auto-commit .brv context changes.
.lintstagedrc.json New lint-staged config running oxfmt --check and oxlint on all staged source and config file types.
.changeset/config.json Added @caplets/landing to the changeset ignore list so landing page changes don't require a changeset file.

Reviews (7): Last reviewed commit: "ci: fix preview URL" | Re-trigger Greptile

Comment thread README.md
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Line 247: The README contains a lowercase platform name "github" which should
be capitalized for consistency; replace the token "github" at the capabilities
list entry (the line containing "1. **Choose** a capability, such as `github`.")
with "GitHub" so it reads "such as `GitHub`" to match official naming and the
rest of the document.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6596450a-9f0b-4b1a-8cd9-3e9587677216

📥 Commits

Reviewing files that changed from the base of the PR and between 3b381da and b37a94c.

📒 Files selected for processing (1)
  • README.md

Comment thread README.md Outdated
@ian-pascoe
Copy link
Copy Markdown
Contributor Author

Addressed the review feedback, including the outside-summary Quick Start note: the optional Context7 backend add command is no longer in the minimal Quick Start, and the GitHub example casing is fixed. Verification: pnpm verify passed.

Comment thread .github/workflows/ci.yml
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/commit-byterover-context.ts`:
- Line 1: The shebang in commit-byterover-context.ts is misleading because Node
cannot run TypeScript files directly; update the shebang to reference the tsx
runtime used by the hooks (e.g. change "#!/usr/bin/env node" to use "tsx") so
the script header matches how it's executed, or alternatively convert
commit-byterover-context.ts to a compiled JavaScript file and keep the original
Node shebang; ensure the runtime indicated in the shebang aligns with the script
format so execution via pnpm exec tsx remains correct.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: fe28fd1f-f51f-490d-879c-0900ce1c50f3

📥 Commits

Reviewing files that changed from the base of the PR and between b37a94c and 947a9ec.

⛔ Files ignored due to path filters (23)
  • .brv/context-tree/design/caplets/caplets_module_findings.md is excluded by !.brv/**
  • .brv/context-tree/design/caplets/formatting_check.md is excluded by !.brv/**
  • .brv/context-tree/design/caplets/hero_copy.md is excluded by !.brv/**
  • .brv/context-tree/design/caplets/landing_positioning.md is excluded by !.brv/**
  • .brv/context-tree/design/caplets/quick_start.md is excluded by !.brv/**
  • .brv/context-tree/design/caplets/readme_header_badges.md is excluded by !.brv/**
  • .brv/context-tree/design/caplets/readme_md.md is excluded by !.brv/**
  • .brv/context-tree/design/caplets/readme_section.md is excluded by !.brv/**
  • .brv/context-tree/facts/ci/ci.md is excluded by !.brv/**
  • .brv/context-tree/facts/extracted_facts/extracted_facts.md is excluded by !.brv/**
  • .brv/context-tree/facts/mcp_example/mcp_example.md is excluded by !.brv/**
  • .brv/context-tree/facts/minimal_quick_start/minimal_quick_start.md is excluded by !.brv/**
  • .brv/context-tree/facts/pnpm_format_check/pnpm_format_check.md is excluded by !.brv/**
  • .brv/context-tree/facts/pnpm_verify/pnpm_verify.md is excluded by !.brv/**
  • .brv/context-tree/facts/pr_93/pr_93.md is excluded by !.brv/**
  • .brv/context-tree/facts/project/179803b.md is excluded by !.brv/**
  • .brv/context-tree/facts/project/ab9efe5.md is excluded by !.brv/**
  • .brv/context-tree/facts/project/extracted_facts.md is excluded by !.brv/**
  • .brv/context-tree/facts/project/post_commit_hook_brv.md is excluded by !.brv/**
  • .brv/context-tree/facts/project/uncategorized.md is excluded by !.brv/**
  • .brv/context-tree/facts/review_threads/review_threads.md is excluded by !.brv/**
  • .brv/context-tree/facts/staged_path_example/staged_path_example.md is excluded by !.brv/**
  • .brv/context-tree/src/caplets/caplets_module_findings.md is excluded by !.brv/**
📒 Files selected for processing (9)
  • .changeset/config.json
  • .github/workflows/changeset-reminder.yml
  • .github/workflows/ci.yml
  • .husky/post-commit
  • .husky/pre-push
  • README.md
  • apps/landing/src/pages/index.astro
  • scripts/commit-byterover-context.test.ts
  • scripts/commit-byterover-context.ts
💤 Files with no reviewable changes (1)
  • .github/workflows/changeset-reminder.yml
✅ Files skipped from review due to trivial changes (3)
  • .husky/post-commit
  • .changeset/config.json
  • README.md

Comment thread scripts/commit-byterover-context.ts Outdated
Comment on lines 3 to 15
on:
release:
types: [published]
push:
branches:
- main
paths:
- .github/workflows/deploy.yml
- alchemy.run.ts
- apps/**
- package.json
- pnpm-lock.yaml
- pnpm-workspace.yaml
- scripts/alchemy-*.ts
workflow_dispatch:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Production deploys now trigger on every matching push to main

The trigger was changed from release: published (gated) to push: main with a paths filter, with no environment: protection gate in the job. This PR itself touches alchemy.run.ts and apps/**, so merging it will immediately fire a production deployment. Any future commit touching those paths will do the same. If the intent is continuous deployment, an environment: production protection rule is the standard mechanism to require approval before prod deploys run.

Fix in Codex

@socket-security
Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Addedrolldown@​1.0.3991007898100
Addedlint-staged@​17.0.510010010097100

View full report

@ian-pascoe ian-pascoe merged commit 800b008 into main May 28, 2026
7 of 8 checks passed
@ian-pascoe ian-pascoe deleted the docs/align-readme-with-landing branch May 28, 2026 18:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant