Skip to content

docs: add GitHub workflow guide for AI docs#252

Merged
eluce2 merged 4 commits intomainfrom
docs/ai-github-workflow
May 8, 2026
Merged

docs: add GitHub workflow guide for AI docs#252
eluce2 merged 4 commits intomainfrom
docs/ai-github-workflow

Conversation

@eluce2
Copy link
Copy Markdown
Collaborator

@eluce2 eluce2 commented May 7, 2026

Summary

  • New AI docs guide at /docs/ai/github-workflow aimed at FileMaker devs new to Git, anchored to the shared-user model they know.
  • Reusable ThemedImage MDX component renders light/dark SVG variants via Tailwind dark: classes (no JS toggle, no hydration flicker).
  • Two new themed diagrams in public/diagrams/: shared-user-model and github-flow.

Test plan

  • pnpm run ci passes
  • Visit /docs/ai/github-workflow locally; verify both diagrams render
  • Toggle theme; verify correct SVG variant shows in each mode with no background chrome
  • Confirm page appears as the last entry under "Guides" in the AI docs sidebar

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Theme-aware images that switch for light/dark modes.
    • New platform-aware download flow: unified download button/dialog that collects email and shows confirmation.
    • New standardized UI primitives (dialog, select, button) for consistent interactions.
  • Documentation

    • New "GitHub Workflow" guide covering Git basics, publishing, branching, pull requests, and AI-assisted Git prompts.
    • Install/update guides updated to use the new download component.
  • Analytics

    • Download requests now capture submitted email for tracking.

Adds a friendly Git/GitHub intro for FileMaker devs anchored to the
shared user model they know, with light/dark themed diagrams via a new
ThemedImage MDX component.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@vercel
Copy link
Copy Markdown

vercel Bot commented May 7, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
proofkit-docs Ready Ready Preview, Comment May 8, 2026 8:22pm

Request Review

@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented May 7, 2026

⚠️ No Changeset found

Latest commit: 880c26a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new Bot commented May 7, 2026

Open in StackBlitz

@proofkit/better-auth

pnpm add https://pkg.pr.new/proofsh/proofkit/@proofkit/better-auth@252

@proofkit/cli

pnpm add https://pkg.pr.new/proofsh/proofkit/@proofkit/cli@252

create-proofkit

pnpm add https://pkg.pr.new/proofsh/proofkit/create-proofkit@252

@proofkit/fmdapi

pnpm add https://pkg.pr.new/proofsh/proofkit/@proofkit/fmdapi@252

@proofkit/fmodata

pnpm add https://pkg.pr.new/proofsh/proofkit/@proofkit/fmodata@252

@proofkit/typegen

pnpm add https://pkg.pr.new/proofsh/proofkit/@proofkit/typegen@252

@proofkit/webviewer

pnpm add https://pkg.pr.new/proofsh/proofkit/@proofkit/webviewer@252

commit: 880c26a

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 7, 2026

Review Change Stack

📝 Walkthrough

Walkthrough

This PR adds a "GitHub Workflow" MDX guide and registers it in docs metadata; introduces a theme-aware ThemedImage component and registers it for MDX; adds typed env schema and generated env.d.ts, applies varlock Next integration and pnpm overrides; switches PostHog reads to typed ENV and adds download tracking; implements UI primitives (Button/Dialog/Select) and a dialog-driven download flow.

Changes

GitHub Workflow Guide, ThemedImage, Env/Varlock, UI, and Analytics

Layer / File(s) Summary
Env schema & generated types
apps/docs/.env.schema, apps/docs/env.d.ts, biome.json
Adds @env-spec entries for PostHog keys, generates env.d.ts types and global typings, and disables formatter/linter for the generated file.
Varlock integration & deps
apps/docs/next.config.ts, apps/docs/package.json, package.json
Adds @varlock/nextjs-integration/varlock, wraps Next config with withVarlock(withMDX(...)), and adds a pnpm override mapping @next/env to the varlock package.
Instrumentation / Analytics
apps/docs/src/instrumentation-client.ts, apps/docs/src/lib/analytics.ts
Reads PostHog config from typed ENV (varlock) and adds trackDownloadRequest helper that identifies and captures proofkit_download_request.
ThemedImage Props
apps/docs/src/components/ThemedImage.tsx
Defines ThemedImageProps (lightSrc, darkSrc, alt, width, height, optional className).
ThemedImage Implementation
apps/docs/src/components/ThemedImage.tsx
Renders two next/image elements with theme-specific utility classes to display correct image per theme.
MDX Registration
apps/docs/src/mdx-components.tsx
Imports and registers ThemedImage in getMDXComponents for MDX rendering.
Documentation Structure
apps/docs/content/docs/ai/github-workflow.mdx
Adds new MDX page with frontmatter, Step/Steps import, callouts, and introductory guidance on Git workflows.
Core Guide Content
apps/docs/content/docs/ai/github-workflow.mdx
Adds sections on FileMaker vs code repos, how code projects work, Git terminology, and hosted repo benefits.
Workflow & Publish Guidance
apps/docs/content/docs/ai/github-workflow.mdx
Provides AI agent delegation prompts and GitHub CLI-based publishing steps.
Docs Metadata Registration
apps/docs/content/docs/ai/meta.json
Adds github-workflow to the Guides pages array.
Button primitive
apps/docs/src/components/ui/button.tsx
Refactors buttonVariants to an internal constant and exports Button, buttonVariants, and ButtonProps via consolidated export; adds typed Button component.
Dialog primitives
apps/docs/src/components/ui/dialog.tsx
Adds client-side dialog wrappers and standardized styling around Base UI dialog primitives.
Select primitives
apps/docs/src/components/ui/select.tsx
Adds Select wrapper components (Select, SelectValue, SelectTrigger, SelectPopup, SelectItem) with styling, icons, and portaling.
DownloadDialog
apps/docs/src/components/DownloadDialog.tsx
Implements dialog that collects and validates email, calls trackDownloadRequest, and shows a confirmation UI.
DownloadButton
apps/docs/src/components/DownloadButton.tsx
Switches download UX from Link navigation to dialog-driven flow, removing per-platform hrefs and adding dialog control state.
DownloadLink
apps/docs/src/components/DownloadLink.tsx
Adds client component that detects platform and opens DownloadDialog.

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs:

  • proofsh/proofkit#246: Modifies the install/connect docs (same MDX page) and updates the installation flow; strongly related to the download-link changes.
  • proofsh/proofkit#233: Adds an MDX component to getMDXComponents (similar registration change); related to ThemedImage registration.
  • proofsh/proofkit#249: Adds Steps/Step UI used by the new GitHub Workflow doc; related to the doc content and UI usage.
🚥 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 accurately summarizes the primary change: adding a new GitHub workflow documentation guide for AI docs. It is concise, specific, and clearly related to the main file addition (github-workflow.mdx) and supporting infrastructure.
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 docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/ai-github-workflow

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

- replace direct download links with email capture
- wire docs to varlock env loading
- add shared dialog and select primitives
Copy link
Copy Markdown

@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: 4

🧹 Nitpick comments (1)
apps/docs/src/components/DownloadButton.tsx (1)

17-63: ⚡ Quick win

Use const assertions on immutable config maps.

These objects are static lookup tables; as const + satisfies will preserve literal types and prevent accidental widening/mutation.

♻️ Proposed type-tightening
-const platformOptions: Record<Platform, { label: string; icon: React.ReactNode }> = {
+const platformOptions = {
   mac: {
     label: "Download for macOS",
     icon: <Download className="size-5" />,
   },
   win: {
     label: "Download for Windows",
     icon: (
       <svg aria-hidden="true" className="size-5" fill="none" viewBox="0 0 24 24">
         <path d="M4 5.5h7v6H4zM13 5.5h7v6h-7zM4 13h7v5.5H4zM13 13h7v5.5h-7z" stroke="currentColor" strokeWidth="1.8" />
       </svg>
     ),
   },
-};
+} as const satisfies Record<Platform, { label: string; icon: React.ReactNode }>;
 
-const variantStyles: Record<DownloadButtonVariant, { primary: string; chevron: string }> = {
+const variantStyles = {
   dark: {
     primary:
       "h-12 border border-white/15 bg-white/[0.06] px-6 text-white shadow-[inset_0_1px_0_rgba(255,255,255,0.08),0_0_36px_rgba(255,255,255,0.08)] backdrop-blur-md transition hover:border-white/25 hover:bg-white/[0.1]",
     chevron:
       "h-12 border border-white/15 border-l-0 bg-white/[0.06] px-3 text-white shadow-[inset_0_1px_0_rgba(255,255,255,0.08),0_0_36px_rgba(255,255,255,0.08)] backdrop-blur-md transition hover:border-white/25 hover:bg-white/[0.1]",
   },
   light: {
     primary:
       "h-12 border border-gray-900 bg-gray-900 px-6 text-white shadow-lg transition hover:bg-gray-800 dark:border-white/15 dark:bg-white/[0.06] dark:shadow-[inset_0_1px_0_rgba(255,255,255,0.08),0_0_36px_rgba(255,255,255,0.08)] dark:hover:border-white/25 dark:hover:bg-white/[0.1]",
     chevron:
       "h-12 border border-gray-900 border-l-0 bg-gray-900 px-3 text-white shadow-lg transition hover:bg-gray-800 dark:border-white/15 dark:border-l-0 dark:bg-white/[0.06] dark:shadow-[inset_0_1px_0_rgba(255,255,255,0.08),0_0_36px_rgba(255,255,255,0.08)] dark:hover:border-white/25 dark:hover:bg-white/[0.1]",
   },
-};
+} as const satisfies Record<DownloadButtonVariant, { primary: string; chevron: string }>;

As per coding guidelines, "Use const assertions (as const) for immutable values and literal types".

🤖 Prompt for 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.

In `@apps/docs/src/components/DownloadButton.tsx` around lines 17 - 63, The
platformOptions and variantStyles lookup objects should be made immutable and
have tightened literal types: change their declarations to use const assertions
and the satisfies operator (e.g., declare platformOptions as `const
platformOptions = { ... } as const satisfies Record<Platform, { label: string;
icon: React.ReactNode }>` and variantStyles as `const variantStyles = { ... } as
const satisfies Record<DownloadButtonVariant, { primary: string; chevron: string
}>`), which preserves literal strings, prevents widening/mutation, and still
checks the shape against the existing Record types; no runtime behavior changes
required.
🤖 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 `@apps/docs/.env.schema`:
- Line 8: Remove the concrete analytics token from the schema and replace the
hardcoded value for NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN with a placeholder or
empty value (e.g. NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN=) so the key remains defined
but no real secret is committed; ensure the real token is provided via
deployment environment or CI secrets and update any README/deployment docs to
instruct developers to set NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN in their
environment.

In `@apps/docs/src/components/ui/button.tsx`:
- Around line 31-33: Button currently destructures { className, variant, size,
...props } so the ButtonProps.color ends up in ...props and is passed to the DOM
instead of being used by buttonVariants; update the Button component to also
destructure color from props, pass color into buttonVariants (e.g.
buttonVariants({ variant, size, color, className })), and keep color out of the
remaining ...props so it is not rendered as a raw DOM attribute; reference the
Button function, ButtonProps, and buttonVariants (as SearchToggle already uses
color correctly) when making the change.

In `@apps/docs/src/lib/analytics.ts`:
- Around line 33-37: trackDownloadRequest currently sends raw email to PostHog
(posthog.identify) and as an event property (captureEvent) without consent;
change trackDownloadRequest to accept an explicit consent flag (or read a
consent getter) and only call posthog.identify when that consent is true, and
never include the email in captureEvent payload—send only non-PII like {
platform }; also update the caller (DownloadDialog.tsx) to pass the user’s
explicit analytics consent into trackDownloadRequest.

In `@package.json`:
- Line 59: The root-level overrides entry "@next/env":
"npm:`@varlock/nextjs-integration`" is too broad; remove this override from the
monorepo root package.json and instead add the override only to the
`@proofkit/docs` workspace package.json (or the docs workspace manifest) so only
the docs package uses the npm:`@varlock/nextjs-integration` replacement; update
the docs workspace's package.json overrides to include the "@next/env":
"npm:`@varlock/nextjs-integration`" mapping and run a fresh install to verify only
`@proofkit/docs` is affected.

---

Nitpick comments:
In `@apps/docs/src/components/DownloadButton.tsx`:
- Around line 17-63: The platformOptions and variantStyles lookup objects should
be made immutable and have tightened literal types: change their declarations to
use const assertions and the satisfies operator (e.g., declare platformOptions
as `const platformOptions = { ... } as const satisfies Record<Platform, { label:
string; icon: React.ReactNode }>` and variantStyles as `const variantStyles = {
... } as const satisfies Record<DownloadButtonVariant, { primary: string;
chevron: string }>`), which preserves literal strings, prevents
widening/mutation, and still checks the shape against the existing Record types;
no runtime behavior changes required.
🪄 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

Run ID: b7041659-a7c7-48ec-91ee-d7c9f4c21cb2

📥 Commits

Reviewing files that changed from the base of the PR and between e660420 and 214b8c3.

⛔ Files ignored due to path filters (1)
  • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
📒 Files selected for processing (13)
  • apps/docs/.env.schema
  • apps/docs/env.d.ts
  • apps/docs/next.config.ts
  • apps/docs/package.json
  • apps/docs/src/components/DownloadButton.tsx
  • apps/docs/src/components/DownloadDialog.tsx
  • apps/docs/src/components/ui/button.tsx
  • apps/docs/src/components/ui/dialog.tsx
  • apps/docs/src/components/ui/select.tsx
  • apps/docs/src/instrumentation-client.ts
  • apps/docs/src/lib/analytics.ts
  • biome.json
  • package.json
✅ Files skipped from review due to trivial changes (2)
  • apps/docs/src/components/DownloadDialog.tsx
  • apps/docs/env.d.ts

Comment thread apps/docs/.env.schema
# ---

# type=string @required @public
NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN=phc_CRjEA3E6xegbZegA9ZjsCREfuuR8XdTJ72CkBeukd5hQ
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Do not commit a live analytics token in the schema file.

Line 8 contains a concrete token value. Keep the key definition in source, but inject the actual value via deployment environment to avoid accidental exposure/misuse and cross-env coupling.

Suggested change
 # type=string `@required` `@public`
-NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN=phc_CRjEA3E6xegbZegA9ZjsCREfuuR8XdTJ72CkBeukd5hQ
+NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN=
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN=phc_CRjEA3E6xegbZegA9ZjsCREfuuR8XdTJ72CkBeukd5hQ
NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN=
🧰 Tools
🪛 Betterleaks (1.1.2)

[high] 8-8: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.

(generic-api-key)

🤖 Prompt for 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.

In `@apps/docs/.env.schema` at line 8, Remove the concrete analytics token from
the schema and replace the hardcoded value for NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN
with a placeholder or empty value (e.g. NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN=) so
the key remains defined but no real secret is committed; ensure the real token
is provided via deployment environment or CI secrets and update any
README/deployment docs to instruct developers to set
NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN in their environment.

Comment on lines +31 to +33
function Button({ className, variant, size, ...props }: React.ComponentProps<"button"> & ButtonProps) {
return <button className={cn(buttonVariants({ variant, size, className }))} {...props} />;
}
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify impact: locate Button call sites passing `color=`
rg -n --type=tsx '<Button[^>]*\bcolor\s*='

Repository: proofsh/proofkit

Length of output: 1955


🏁 Script executed:

find . -name "button.tsx" -path "*/docs/*" 2>/dev/null | head -5

Repository: proofsh/proofkit

Length of output: 101


🏁 Script executed:

cat -n ./apps/docs/src/components/ui/button.tsx

Repository: proofsh/proofkit

Length of output: 1606


🏁 Script executed:

rg -n "Button[^>]*\bcolor\s*=" --type=tsx --type=jsx

Repository: proofsh/proofkit

Length of output: 88


🏁 Script executed:

rg "Button.*color\s*=" -A 2 -B 2

Repository: proofsh/proofkit

Length of output: 42


🏁 Script executed:

rg "<Button" -t ts -t js -A 1 -B 1 | head -50

Repository: proofsh/proofkit

Length of output: 4012


🏁 Script executed:

rg "import.*Button" apps/docs -A 1 -B 1

Repository: proofsh/proofkit

Length of output: 2524


🏁 Script executed:

rg "color=" apps/docs/src -A 2 -B 2 | head -80

Repository: proofsh/proofkit

Length of output: 42


🏁 Script executed:

rg "Button" apps/docs/src/components -A 3 | grep -A 3 "Button"

Repository: proofsh/proofkit

Length of output: 13594


🏁 Script executed:

cat -n ./apps/docs/src/components/search-toggle.tsx

Repository: proofsh/proofkit

Length of output: 2570


color prop is exposed but never applied to variants.

ButtonProps exposes color as a variant option, but the Button component does not pass it to buttonVariants(...). The color prop becomes a raw DOM attribute instead of applying the intended styling. This is inconsistent with how SearchToggle correctly uses color directly with buttonVariants.

💡 Suggested fix
-function Button({ className, variant, size, ...props }: React.ComponentProps<"button"> & ButtonProps) {
-  return <button className={cn(buttonVariants({ variant, size, className }))} {...props} />;
+function Button({ className, variant, size, color, ...props }: React.ComponentProps<"button"> & ButtonProps) {
+  return <button className={cn(buttonVariants({ variant, size, color, className }))} {...props} />;
 }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
function Button({ className, variant, size, ...props }: React.ComponentProps<"button"> & ButtonProps) {
return <button className={cn(buttonVariants({ variant, size, className }))} {...props} />;
}
function Button({ className, variant, size, color, ...props }: React.ComponentProps<"button"> & ButtonProps) {
return <button className={cn(buttonVariants({ variant, size, color, className }))} {...props} />;
}
🤖 Prompt for 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.

In `@apps/docs/src/components/ui/button.tsx` around lines 31 - 33, Button
currently destructures { className, variant, size, ...props } so the
ButtonProps.color ends up in ...props and is passed to the DOM instead of being
used by buttonVariants; update the Button component to also destructure color
from props, pass color into buttonVariants (e.g. buttonVariants({ variant, size,
color, className })), and keep color out of the remaining ...props so it is not
rendered as a raw DOM attribute; reference the Button function, ButtonProps, and
buttonVariants (as SearchToggle already uses color correctly) when making the
change.

Comment on lines +33 to +37
export function trackDownloadRequest(properties: { email: string; platform: string }) {
if (isPostHogEnabled) {
posthog.identify(properties.email);
}
captureEvent("proofkit_download_request", properties);
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Verify where trackDownloadRequest is called and whether consent is checked upstream.
rg -n -C3 --type=ts --type=tsx '\btrackDownloadRequest\s*\(' apps/docs/src

# Verify all places where raw email is sent to PostHog.
rg -n -C3 --type=ts --type=tsx 'posthog\.identify\s*\(|captureEvent\s*\(.*email|proofkit_download_request' apps/docs/src

Repository: proofsh/proofkit

Length of output: 88


🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Search for trackDownloadRequest calls and usage (using ts for both ts and tsx files)
echo "=== Searching for trackDownloadRequest calls ==="
rg -n -C3 'trackDownloadRequest\s*\(' apps/docs/src -t ts

echo ""
echo "=== Searching for posthog.identify calls ==="
rg -n -C3 'posthog\.identify' apps/docs/src -t ts

echo ""
echo "=== Searching for captureEvent calls ==="
rg -n -C3 'captureEvent' apps/docs/src -t ts

echo ""
echo "=== Checking analytics.ts for full context ==="
cat -n apps/docs/src/lib/analytics.ts

Repository: proofsh/proofkit

Length of output: 4944


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "=== Full DownloadDialog.tsx content ==="
cat -n apps/docs/src/components/DownloadDialog.tsx

echo ""
echo "=== Search for consent-related code ==="
rg -n -i 'consent' apps/docs/src -t ts

echo ""
echo "=== Search for analytics consent or user agreement ==="
rg -n -i 'agree|permission|opt.?in' apps/docs/src -t ts

Repository: proofsh/proofkit

Length of output: 4452


Avoid sending raw email to analytics without explicit consent gating.

Lines 35 and 37 transmit email to PostHog in two ways—as user identity and as event property—without any consent check. This is a privacy and compliance risk. Add a consent gate and minimize the event payload to exclude PII:

  • Check for analytics consent before identifying the user and capturing the event
  • Send only non-PII data (e.g., platform) in the event properties

No consent mechanism exists in the codebase or call site (DownloadDialog.tsx). The email must be gated on explicit user consent before transmission.

🤖 Prompt for 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.

In `@apps/docs/src/lib/analytics.ts` around lines 33 - 37, trackDownloadRequest
currently sends raw email to PostHog (posthog.identify) and as an event property
(captureEvent) without consent; change trackDownloadRequest to accept an
explicit consent flag (or read a consent getter) and only call posthog.identify
when that consent is true, and never include the email in captureEvent
payload—send only non-PII like { platform }; also update the caller
(DownloadDialog.tsx) to pass the user’s explicit analytics consent into
trackDownloadRequest.

Comment thread package.json
},
"pnpm": {
"overrides": {
"@next/env": "npm:@varlock/nextjs-integration",
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Verify whether workspaces besides `@proofkit/docs` depend on next / `@next/env`.
fd -HI '^package\.json$' -E node_modules | while read -r file; do
  jq -r --arg file "$file" '
    .name as $name |
    (.dependencies.next // .devDependencies.next // "") as $next |
    (.dependencies["@next/env"] // .devDependencies["@next/env"] // "") as $nextEnv |
    if ($next != "" or $nextEnv != "") then
      "\($name)\t\($file)\tnext=\($next)\t@next/env=\($nextEnv)"
    else empty end
  ' "$file"
done

Repository: proofsh/proofkit

Length of output: 509


Scope the @next/env override to docs instead of the whole monorepo.

Line 59 sets a root-level override that affects every workspace depending on Next.js, not just @proofkit/docs. The verification found 6 workspaces with Next.js dependencies (@proofkit/docs, @proofkit/cli, @proofkit/cli-old, plus multiple template packages), so this override creates an unnecessary broad blast radius.

Suggested change
   "pnpm": {
     "overrides": {
-      "@next/env": "npm:`@varlock/nextjs-integration`",
+      "@proofkit/docs>@next/env": "npm:`@varlock/nextjs-integration`",
       "shiki": "3.13.0",
       "@shikijs/types": "3.13.0",
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
"@next/env": "npm:@varlock/nextjs-integration",
"@proofkit/docs>@next/env": "npm:`@varlock/nextjs-integration`",
🤖 Prompt for 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.

In `@package.json` at line 59, The root-level overrides entry "@next/env":
"npm:`@varlock/nextjs-integration`" is too broad; remove this override from the
monorepo root package.json and instead add the override only to the
`@proofkit/docs` workspace package.json (or the docs workspace manifest) so only
the docs package uses the npm:`@varlock/nextjs-integration` replacement; update
the docs workspace's package.json overrides to include the "@next/env":
"npm:`@varlock/nextjs-integration`" mapping and run a fresh install to verify only
`@proofkit/docs` is affected.

Copy link
Copy Markdown

@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 `@apps/docs/src/components/DownloadLink.tsx`:
- Around line 20-22: Currently platform is set asynchronously in useEffect via
setPlatform(detectPlatform()), which can be stale on immediate clicks; remove
the detectPlatform call from useEffect and instead call detectPlatform()
synchronously inside the button click handler (e.g., the onClick/handleOpen
function that opens the dialog), assign that result to a local variable and pass
it into state setters and into trackDownloadRequest so the platform used is the
freshly-detected value; update usages that relied on the platform state
(setPlatform, trackDownloadRequest) to use this detectedPlatform variable to
ensure the correct platform is recorded at click time.
🪄 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

Run ID: f5a86fe3-281e-4c4a-8ba4-a3adfec5f48c

📥 Commits

Reviewing files that changed from the base of the PR and between 214b8c3 and 880c26a.

⛔ Files ignored due to path filters (1)
  • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
📒 Files selected for processing (5)
  • apps/docs/content/docs/ai/install-and-connect.mdx
  • apps/docs/content/docs/ai/updating-proofkit.mdx
  • apps/docs/package.json
  • apps/docs/src/components/DownloadLink.tsx
  • apps/docs/src/mdx-components.tsx
✅ Files skipped from review due to trivial changes (2)
  • apps/docs/content/docs/ai/install-and-connect.mdx
  • apps/docs/content/docs/ai/updating-proofkit.mdx

Comment on lines +20 to +22
useEffect(() => {
setPlatform(detectPlatform());
}, []);
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

cat -n apps/docs/src/components/DownloadLink.tsx

Repository: proofsh/proofkit

Length of output: 1373


🏁 Script executed:

find . -name "DownloadDialog*" -type f

Repository: proofsh/proofkit

Length of output: 106


🏁 Script executed:

cat -n apps/docs/src/components/DownloadDialog.tsx

Repository: proofsh/proofkit

Length of output: 4371


Move platform detection to the click handler to ensure correct platform is captured.

The platform state initializes to "mac" and is updated asynchronously in a useEffect with an empty dependency array. A user who clicks the button immediately after first paint—before the effect runs—will open the dialog with the default platform value. When they submit the form, trackDownloadRequest will receive the wrong platform.

Moving detectPlatform() to the click handler ensures the correct platform is detected synchronously at the moment of user interaction.

Proposed fix
-import { useEffect, useState } from "react";
+import { useState } from "react";
@@
-  useEffect(() => {
-    setPlatform(detectPlatform());
-  }, []);
@@
-        onClick={() => setOpen(true)}
+        onClick={() => {
+          setPlatform(detectPlatform());
+          setOpen(true);
+        }}
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
useEffect(() => {
setPlatform(detectPlatform());
}, []);
import { useState } from "react";
Suggested change
useEffect(() => {
setPlatform(detectPlatform());
}, []);
onClick={() => {
setPlatform(detectPlatform());
setOpen(true);
}}
🤖 Prompt for 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.

In `@apps/docs/src/components/DownloadLink.tsx` around lines 20 - 22, Currently
platform is set asynchronously in useEffect via setPlatform(detectPlatform()),
which can be stale on immediate clicks; remove the detectPlatform call from
useEffect and instead call detectPlatform() synchronously inside the button
click handler (e.g., the onClick/handleOpen function that opens the dialog),
assign that result to a local variable and pass it into state setters and into
trackDownloadRequest so the platform used is the freshly-detected value; update
usages that relied on the platform state (setPlatform, trackDownloadRequest) to
use this detectedPlatform variable to ensure the correct platform is recorded at
click time.

@eluce2 eluce2 merged commit 4da5596 into main May 8, 2026
14 checks passed
@eluce2 eluce2 deleted the docs/ai-github-workflow branch May 8, 2026 20:32
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