feat(docs-v2): add GuideStepper checkpoint prompt-copy workflow#3465
feat(docs-v2): add GuideStepper checkpoint prompt-copy workflow#3465
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Summary by CodeRabbitRelease Notes
WalkthroughThis PR adds two new interactive MDX components—GuideStepper (with Step, Checkpoint, AtAGlance, and Prompt subcomponents) and VerticalProgressSteps (with Item subcomponent)—along with supporting utilities, a content preprocessor that injects raw content into GuideStepper blocks, and integration into the MDX rendering pipeline. The include system is updated to support optional leading whitespace. Changes
Sequence DiagramsequenceDiagram
participant User as User
participant MDX as MDX Parser
participant PP as Preprocessor
participant Renderer as MDX Renderer
participant GS as GuideStepper
participant Storage as LocalStorage
User->>MDX: Request page with guide
MDX->>PP: Pass raw markdown content
PP->>PP: Inject rawContent into<br/>GuideStepper blocks
PP-->>MDX: Return processed content
MDX->>Renderer: Parse & map components
Renderer->>GS: Render GuideStepper component
GS->>Storage: Load persisted completed steps
Storage-->>GS: Return completed state
GS->>GS: Calculate progress &<br/>default expanded steps
GS-->>User: Render interactive stepper<br/>with progress bar
User->>GS: Toggle step completion
GS->>Storage: Persist completed steps
GS-->>User: Update progress display
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
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 |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
Show resolved
Hide resolved
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🤖 Fix all issues with AI agents
In
`@apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx`:
- Around line 436-438: The docs use lowercase "markdown" twice within the
GuideStepper.AtAGlance section and the Copy Prompt description; update both
occurrences to the proper noun "Markdown" (e.g., in the sentences describing
Copy Prompt concatenating content into markdown and the instruction to write
regular markdown directly) so they read "Markdown" instead of "markdown" in the
GuideStepper.AtAGlance/Copy Prompt text.
In `@apps/framework-docs-v2/src/components/mdx-renderer.tsx`:
- Around line 89-94: The Object.assign call creating
GuideStepperWithSubcomponents is redundant because GuideStepper already has its
subcomponents attached; remove the duplicate block (the const
GuideStepperWithSubcomponents = Object.assign(GuideStepper, { Step:
GuideStepperStep, Checkpoint: GuideStepperCheckpoint, AtAGlance:
GuideStepperAtAGlance, Prompt: GuideStepperPrompt }) statement) and update any
usages to reference the existing GuideStepper export directly (or, if you want
to keep a named alias for consistency, export the already-assigned GuideStepper
as GuideStepperWithSubcomponents without re-calling Object.assign).
In
`@apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.ts`:
- Around line 68-77: The tests currently pass React children via the props
object to createElement which trips the Biome noChildrenProp rule; update each
createElement call in guide-stepper-utils.test (the ones creating nodes with
id/number/title/children) to pass children as the third argument instead of as a
children property in the props object (e.g., call createElement("div", { id:
"phase-1", number: 1, title: "Parity" }, "content")); keep usage of
isGuideStepperStepElement unchanged.
In
`@apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts`:
- Around line 147-182: The type-guard functions (isGuideStepperStepElement,
isGuideStepperCheckpointElement, isGuideStepperAtAGlanceElement) currently rely
on absence/presence of props.number which is fragile; add a stable discriminant
prop (e.g., __componentType) on the MDX wrapper components and update each guard
to check props.__componentType === "step" | "checkpoint" | "at-a-glance"
respectively (or, if you cannot add the prop everywhere yet, add a short
invariant comment above isGuideStepperCheckpointElement explaining why checking
typeof props.number === "undefined" is required and note the TODO to migrate to
a discriminant). Ensure the discriminant is included in the GuideStepLikeProps /
GuideCheckpointLikeProps / GuideAtAGlanceLikeProps types so the guards and
components remain consistent.
- Around line 100-121: Add an explicit return type to the public function
calculateProgress; update its signature to return a typed shape (e.g. {
completed: number; total: number; percentage: number }) instead of relying on
inference, reference the existing sanitizeCompletedStepIds and
stepIds/completedStepIds parameters when declaring the type so callers get a
stable API contract.
- Around line 46-76: sanitizeCompletedStepIds and getSanitizedOpenStepIds
contain identical logic; extract a shared helper like sanitizeStepIds(ids:
string[], validStepIds: string[]) that preserves input order, filters against a
Set of validStepIds, and tracks seen IDs using a Set (instead of
uniqueOrdered.includes) to avoid O(n) scans; then have sanitizeCompletedStepIds
and getSanitizedOpenStepIds simply call this helper (referencing functions
sanitizeCompletedStepIds, getSanitizedOpenStepIds, and the new sanitizeStepIds)
so behavior and order are preserved while improving performance and removing
duplication.
- Line 184: The current export aliases isGuideStepperPromptElement to
isGuideStepperAtAGlanceElement which is misleading; either remove the unused
isGuideStepperPromptElement export or implement a distinct validator that checks
for the specific shape of GuideStepperPromptProps (not just reusing
isGuideStepperAtAGlanceElement). To fix: locate the exported symbol
isGuideStepperPromptElement and either delete the export if it isn't referenced
anywhere, or replace the alias with a new function isGuideStepperPromptElement
that performs explicit runtime checks for the keys/structure defined by
GuideStepperPromptProps (compare against the properties that differentiate it
from GuideStepperAtAGlanceProps) and export that distinct validator instead.
Ensure the new validator name matches usages and keep
isGuideStepperAtAGlanceElement unchanged.
In `@apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx`:
- Around line 153-163: The useMemo wrapper around promptToCopy is ineffective
because atAGlanceBlocks and checkpoints are recreated each render; either remove
the useMemo around promptToCopy (so call buildGuideStepPromptMarkdown directly)
or memoize the upstream arrays (atAGlanceBlocks and checkpoints) where they are
created so their references are stable; update the code referencing
promptToCopy/buildGuideStepPromptMarkdown and atAGlanceBlocks/checkpoints
accordingly so the memoization becomes meaningful or is eliminated.
- Around line 364-369: The effect uses stepIds inside but only depends on
stepIdsKey, causing a stale-closure; memoize the stepIds array with
React.useMemo (e.g., const memoStepIds = useMemo(() => stepIds, [stepIdsKey, /*
or raw inputs that derive stepIds */])) and then use memoStepIds in the
useEffect (and in the related useMemo calls that depend on stepIds) so the
dependency arrays can include the stable memoized value instead of the raw array
reference; update references from stepIds to the memoized name in
setOpenStepIds/getSanitizedOpenStepIds/hasSameItems and the other useMemo usages
to eliminate the linter warning and ensure correct re-runs.
- Around line 250-253: The list is using checkpointTitle as the React key (in
the checkpointTitles.map and key={checkpointTitle}) which can collide; change
the mapping to use each checkpoint's unique id (e.g., checkpoint.props.id) as
the key — either map over the checkpoints collection (not checkpointTitles) or
ensure you have a parallel ids array and replace key={checkpointTitle} with
key={checkpoint.props.id} (or the unique id variable) so keys are stable and
unique.
In `@apps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.ts`:
- Around line 4-65: Add tests that cover GuideStepper.Prompt blocks and strings
containing multiple GuideStepper blocks so the preprocessor's behavior is fully
exercised; specifically, add a test case that passes a
<GuideStepper.Prompt>...</GuideStepper.Prompt> block into
processGuideStepperPrompts and asserts rawContent is injected, and add a test
that includes multiple identical blocks in one input string to ensure
processGuideStepperPrompts does not only replace the first occurrence (the
implementation that uses result.replace(fullBlock, ...) should be validated or
changed to replace all matches). Reference processGuideStepperPrompts,
GuideStepper.Prompt, GuideStepper.Checkpoint, GuideStepper.AtAGlance and the use
of result.replace(fullBlock, ...) when writing these tests.
In `@apps/framework-docs-v2/src/lib/includes.test.ts`:
- Around line 4-22: Add negative/edge-case tests for INCLUDE_REGEX in
includes.test.ts: add cases asserting it does NOT match when there is no path
after ":::include" (e.g., ":::include" or ":::include "), when the token is a
partial keyword like ":::included /foo.mdx", and when indentation uses tabs
instead of spaces (e.g., "\t:::include /shared/guides/foo.mdx"); for each new
test reset INCLUDE_REGEX.lastIndex = 0, run matchAll on the input and assert
matches length is 0 (or that no capture group contains a path) to ensure these
edge cases are rejected.
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (12)
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdxapps/framework-docs-v2/src/components/mdx-renderer.tsxapps/framework-docs-v2/src/components/mdx/index.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/src/lib/content.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.tsapps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/includes.ts
🧰 Additional context used
📓 Path-based instructions (5)
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Run linting checks before submitting PRs for TypeScript/JavaScript code
**/*.{ts,tsx,js,jsx}: Group imports by external dependencies, internal modules, and types; use named exports from barrel files (index.ts)
Use camelCase for variables and functions, PascalCase for types/classes/components, UPPER_SNAKE_CASE for constants in TypeScript/JavaScript
Prefix unused variables with underscore (e.g.,_unusedParam) to bypass linting errors in TypeScript/JavaScript
Format TypeScript/JavaScript code with Prettier usingexperimentalTernaries: true; auto-formats on commit via Husky + lint-staged
Files:
apps/framework-docs-v2/src/lib/includes.tsapps/framework-docs-v2/src/lib/content.tsapps/framework-docs-v2/src/components/mdx/index.tsapps/framework-docs-v2/src/components/mdx-renderer.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.tsapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.ts
apps/framework-docs-v2/src/**/*.{ts,tsx}
📄 CodeRabbit inference engine (apps/framework-docs-v2/CLAUDE.md)
Component library must use shadcn/ui components located in
src/components/ui/
Files:
apps/framework-docs-v2/src/lib/includes.tsapps/framework-docs-v2/src/lib/content.tsapps/framework-docs-v2/src/components/mdx/index.tsapps/framework-docs-v2/src/components/mdx-renderer.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.tsapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Prefer interfaces for objects, types for unions/intersections in TypeScript; explicit return types on public APIs
Files:
apps/framework-docs-v2/src/lib/includes.tsapps/framework-docs-v2/src/lib/content.tsapps/framework-docs-v2/src/components/mdx/index.tsapps/framework-docs-v2/src/components/mdx-renderer.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.tsapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.ts
apps/framework-docs-v2/content/**/*.mdx
📄 CodeRabbit inference engine (apps/framework-docs-v2/CLAUDE.md)
apps/framework-docs-v2/content/**/*.mdx: Use{{ include "shared/path.mdx" }}directives to reuse content fragments, which are processed viaprocessIncludes()during build
Validate code snippets in documentation with the@testdirective for TypeScript and Python code blocks
TypeScript code snippets in documentation should be validated for syntax with brace matching; Python snippets should be validated for indentation
Files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
apps/framework-docs-v2/content/guides/**/*.mdx
📄 CodeRabbit inference engine (apps/framework-docs-v2/CLAUDE.md)
Guide MDX files in
content/guides/must include frontmatter with title and description fields
Files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
🧠 Learnings (18)
📓 Common learnings
Learnt from: DatGuyJonathan
Repo: 514-labs/moosestack PR: 3400
File: apps/framework-cli/src/framework/core/infrastructure_map.rs:1238-1298
Timestamp: 2026-01-26T00:56:27.011Z
Learning: Repo 514-labs/moosestack — Workflows: The CLI’s workflow diff is intended to detect only Temporal schedule–affecting changes. In apps/framework-cli/src/framework/core/infrastructure_map.rs, workflows_config_equal should compare schedule, retries, and timeout only; it must not include tasks. Task code/config changes are picked up automatically when the orchestration worker restarts and should not trigger a WorkflowChange.
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Guide promotion workflow: start guides with `status: "draft"` in navigation config, then progress to `status: "beta"`, finally remove status field for public release
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Validate `{{ include }}` directives in content before build using `pnpm run validate:includes` with `scripts/validate-includes.ts`
Applied to files:
apps/framework-docs-v2/src/lib/includes.tsapps/framework-docs-v2/src/lib/content.tsapps/framework-docs-v2/src/lib/includes.test.ts
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : Use `{{ include "shared/path.mdx" }}` directives to reuse content fragments, which are processed via `processIncludes()` during build
Applied to files:
apps/framework-docs-v2/src/lib/includes.tsapps/framework-docs-v2/src/lib/content.tsapps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Content in the `shared/` folder must only be used via the `include` system (processed by `src/lib/includes.ts`), not directly as routes
Applied to files:
apps/framework-docs-v2/src/lib/includes.ts
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/guides/**/*.mdx : Guide MDX files in `content/guides/` must include frontmatter with title and description fields
Applied to files:
apps/framework-docs-v2/src/lib/content.tsapps/framework-docs-v2/src/components/mdx/index.tsapps/framework-docs-v2/src/components/mdx-renderer.tsxapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Add new guides to `guidesNavigationConfig` in `src/config/navigation.ts` with required fields: type, slug, title, icon, languages, and status (start as 'draft')
Applied to files:
apps/framework-docs-v2/src/components/mdx/index.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
📚 Learning: 2026-02-01T23:07:12.361Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-01T23:07:12.361Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Group imports by external dependencies, internal modules, and types; use named exports from barrel files (`index.ts`)
Applied to files:
apps/framework-docs-v2/src/components/mdx/index.tsapps/framework-docs-v2/src/components/mdx/interactive/index.ts
📚 Learning: 2026-01-08T18:32:03.114Z
Learnt from: DatGuyJonathan
Repo: 514-labs/moosestack PR: 3170
File: apps/framework-docs-v2/src/components/copy-page-button.tsx:36-38
Timestamp: 2026-01-08T18:32:03.114Z
Learning: Enforce the following multiline ternary formatting for conditional JSX without parentheses: place the condition and the '?' on the first line, place the true branch on the next indented line, and place the ':' plus the false branch on the third line. This pattern is commonly used for copy/check icon toggles in the moosestack repository (apps/framework-docs-v2). Apply this style to all TSX files under apps/framework-docs-v2/src/**/*.tsx to ensure consistency and readability.
Applied to files:
apps/framework-docs-v2/src/components/mdx-renderer.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : Validate code snippets in documentation with the `test` directive for TypeScript and Python code blocks
Applied to files:
apps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.tsapps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-02-01T23:07:12.361Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-01T23:07:12.361Z
Learning: Add E2E tests to `python-tests` and `typescript-tests` templates when changing user-facing features
Applied to files:
apps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.ts
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : TypeScript code snippets in documentation should be validated for syntax with brace matching; Python snippets should be validated for indentation
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Use Vercel Toolbar feature flags for visibility control: `show-draft-guides`, `show-beta-guides`, `show-hosting-section`, `show-ai-section`, `show-copy-as-markdown`, `show-linear-integration`
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-15T19:41:53.563Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: examples/cdp-analytics/CLAUDE.md:0-0
Timestamp: 2026-01-15T19:41:53.563Z
Learning: Applies to examples/cdp-analytics/web-app/src/features/dashboard/*.tsx : Dashboard components should follow React hooks patterns: use useState for local data, useEffect for data fetching, handle errors with fallback data, and wrap visualizations in Card/CardHeader/CardContent from Radix UI
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-28T14:50:00.978Z
Learnt from: cjus
Repo: 514-labs/moosestack PR: 3407
File: apps/framework-docs-v2/content/guides/static-report-generation.mdx:1402-1406
Timestamp: 2026-01-28T14:50:00.978Z
Learning: When reviewing WebApp implementations that run in a Node.js backend, prefer Node.js-specific types (e.g., Buffer) and avoid browser-focused cross-platform compatibility considerations. This guideline applies to MDX documentation and code examples across the repository where backend/runtime code is discussed; ensure reviewers distinguish server-side context from frontend/browser constraints and validate type usage accordingly.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-19T20:47:10.159Z
Learnt from: DatGuyJonathan
Repo: 514-labs/moosestack PR: 3365
File: apps/framework-docs-v2/src/proxy.ts:4-21
Timestamp: 2026-01-19T20:47:10.159Z
Learning: In Next.js 15/16+, middleware has been renamed to "proxy". A file named `proxy.ts` placed in the project root or `src/` directory with an exported `proxy` function and optional `config` object with `matcher` will be automatically loaded by Next.js without additional configuration. This is the correct pattern for route rewrites and does not require integration in next.config.js.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-27T17:36:29.854Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: examples/nextjs-moose/CLAUDE.md:0-0
Timestamp: 2026-01-27T17:36:29.854Z
Learning: Applies to examples/nextjs-moose/moose/src/query-examples/**/*.ts : Query example functions must use `eventsModel.toSql()` to generate SQL, ensuring consistent query construction through the defined model
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-27T17:36:29.854Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: examples/nextjs-moose/CLAUDE.md:0-0
Timestamp: 2026-01-27T17:36:29.854Z
Learning: Applies to examples/nextjs-moose/app/actions.ts : Server actions must import query functions from the moose package and wrap them, serving as the bridge between frontend React components and backend moose query functions
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-28T14:55:13.411Z
Learnt from: cjus
Repo: 514-labs/moosestack PR: 3407
File: apps/framework-docs-v2/content/guides/static-report-generation.mdx:1585-1616
Timestamp: 2026-01-28T14:55:13.411Z
Learning: In documentation and tutorial files under apps/framework-docs-v2/content/guides/, prefer explicit, self-contained code examples that may duplicate small snippets for clarity over abstracting with DRY helpers. Ensure examples are easy to understand in isolation, even if it means a bit of repetition, to aid learning and reduce cognitive load for readers.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
🧬 Code graph analysis (5)
apps/framework-docs-v2/src/lib/content.ts (2)
apps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.ts (1)
processGuideStepperPrompts(67-105)apps/framework-docs-v2/src/lib/includes.ts (1)
processIncludes(38-139)
apps/framework-docs-v2/src/components/mdx-renderer.tsx (3)
apps/framework-docs-v2/src/components/mdx/index.ts (5)
GuideStepper(63-63)GuideStepperStep(64-64)GuideStepperCheckpoint(65-65)GuideStepperAtAGlance(66-66)GuideStepperPrompt(67-67)apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx (1)
GuideStepper(461-466)apps/framework-docs-v2/src/components/mdx/interactive/index.ts (5)
GuideStepper(35-35)GuideStepperStep(36-36)GuideStepperCheckpoint(37-37)GuideStepperAtAGlance(38-38)GuideStepperPrompt(39-39)
apps/framework-docs-v2/src/lib/includes.test.ts (1)
apps/framework-docs-v2/src/lib/includes.ts (1)
INCLUDE_REGEX(11-11)
apps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.ts (1)
apps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.ts (1)
processGuideStepperPrompts(67-105)
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.ts (1)
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts (9)
calculateProgress(100-121)getDefaultExpandedValues(123-145)sanitizeCompletedStepIds(46-60)isGuideStepperStepElement(147-157)isGuideStepperCheckpointElement(159-169)isGuideStepperAtAGlanceElement(171-182)getOpenStepIdsAfterCompletionToggle(78-84)getSanitizedOpenStepIds(62-76)buildGuideStepPromptMarkdown(86-98)
🪛 Biome (2.3.13)
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx
[error] 364-364: This hook does not specify its dependency on stepIds.
This dependency is being used here, but is not specified in the hook dependency list.
React relies on hook dependencies to determine when to re-compute Effects.
Failing to specify dependencies can result in Effects not updating correctly when state changes.
These "stale closures" are a common source of surprising bugs.
Unsafe fix: Add the missing dependency to the list.
(lint/correctness/useExhaustiveDependencies)
[error] 364-364: This hook specifies more dependencies than necessary: stepIdsKey.
This dependency can be removed from the list.
React relies on hook dependencies to determine when to re-compute Effects.
Specifying more dependencies than required can lead to unnecessary re-rendering
and degraded performance.
Unsafe fix: Remove the extra dependencies from the list.
(lint/correctness/useExhaustiveDependencies)
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.ts
[error] 73-73: Avoid passing children using a prop
The canonical way to pass children in React is to use additional arguments to React.createElement
(lint/correctness/noChildrenProp)
[error] 83-83: Avoid passing children using a prop
The canonical way to pass children in React is to use additional arguments to React.createElement
(lint/correctness/noChildrenProp)
[error] 100-100: Avoid passing children using a prop
The canonical way to pass children in React is to use additional arguments to React.createElement
(lint/correctness/noChildrenProp)
[error] 110-110: Avoid passing children using a prop
The canonical way to pass children in React is to use additional arguments to React.createElement
(lint/correctness/noChildrenProp)
🪛 LanguageTool
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
[uncategorized] ~437-~437: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...ons and all checkpoint tab content into markdown. Inside GuideStepper.AtAGlance, write...
(MARKDOWN_NNP)
[uncategorized] ~438-~438: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...GuideStepper.AtAGlance, write regular markdown directly (no React tags required). <Gu...
(MARKDOWN_NNP)
🔇 Additional comments (13)
apps/framework-docs-v2/src/lib/includes.ts (1)
10-11: Indentation stripping on replacement.When an indented include like
:::include /shared/foo.mdxmatches,match[0]includes the leading whitespace, but the replacement content won't carry that indent. Inside JSX/MDX blocks this is typically fine, but if an include is ever used inside a fenced code block or indentation-sensitive context, the content will lose its indent.Unlikely to bite in practice given current usage, but worth a note.
apps/framework-docs-v2/src/lib/content.ts (1)
101-105: Pipeline ordering is correct.Includes are resolved first, then GuideStepper prompts are injected — this ensures included fragments with
<GuideStepper.Checkpoint>blocks also getrawContentprops. Clean composition.apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.ts (1)
143-160: Good coverage of the prompt markdown builder.Validates concatenation with double-newline separators. Clean.
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx (2)
440-477: GuideStepper demo section looks well-structured.Good coverage of
AtAGlance, nestedCheckpointblocks, and multi-step layout. The preprocessor will injectrawContentprops at build time.
534-534:⚠️ Potential issue | 🟡 MinorSyntax reference shows wrong include directive format.
The examples use
::: include(with a space), butINCLUDE_REGEXrequires:::include(no space). Anyone copying this syntax reference will get silent failures.🔧 Fix the include syntax in the example
- ::: include /shared/guides/<guide>/migration-intro.mdx + :::include /shared/guides/<guide>/migration-intro.mdxApply the same fix on lines 546 and 549.
Also applies to: 546-546, 549-549
⛔ Skipped due to learnings
Learnt from: CR Repo: 514-labs/moosestack PR: 0 File: apps/framework-docs-v2/CLAUDE.md:0-0 Timestamp: 2026-01-22T19:02:52.316Z Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : Use `{{ include "shared/path.mdx" }}` directives to reuse content fragments, which are processed via `processIncludes()` during buildLearnt from: CR Repo: 514-labs/moosestack PR: 0 File: apps/framework-docs-v2/CLAUDE.md:0-0 Timestamp: 2026-01-22T19:02:52.316Z Learning: Applies to apps/framework-docs-v2/content/guides/**/*.mdx : Guide MDX files in `content/guides/` must include frontmatter with title and description fieldsLearnt from: CR Repo: 514-labs/moosestack PR: 0 File: apps/framework-docs-v2/CLAUDE.md:0-0 Timestamp: 2026-01-22T19:02:52.316Z Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : Validate code snippets in documentation with the `test` directive for TypeScript and Python code blocksLearnt from: CR Repo: 514-labs/moosestack PR: 0 File: apps/framework-docs-v2/CLAUDE.md:0-0 Timestamp: 2026-01-22T19:02:52.316Z Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : TypeScript code snippets in documentation should be validated for syntax with brace matching; Python snippets should be validated for indentationLearnt from: CR Repo: 514-labs/moosestack PR: 0 File: apps/framework-docs-v2/CLAUDE.md:0-0 Timestamp: 2026-01-22T19:02:52.316Z Learning: Guide promotion workflow: start guides with `status: "draft"` in navigation config, then progress to `status: "beta"`, finally remove status field for public releaseLearnt from: CR Repo: 514-labs/moosestack PR: 0 File: apps/framework-docs-v2/CLAUDE.md:0-0 Timestamp: 2026-01-22T19:02:52.316Z Learning: Add new guides to `guidesNavigationConfig` in `src/config/navigation.ts` with required fields: type, slug, title, icon, languages, and status (start as 'draft')apps/framework-docs-v2/src/components/mdx/interactive/index.ts (1)
34-45: All exports verified fromguide-stepper.tsx.All 10 items in the barrel file (components and type definitions) correctly exist in the source module. Follows guidelines for named exports and PascalCase naming.
apps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.ts (2)
12-13: Regex handles non-nested same-type blocks correctly but will break on nesting.The lazy
[\s\S]*?with the\1backreference works for flat, non-nested blocks. If a<GuideStepper.Checkpoint>is ever nested inside another<GuideStepper.Checkpoint>, the inner closing tag will terminate the outer match early. Fine for current MDX usage — just document the constraint or add a comment.
67-104: Solid preprocessor logic.Code fence skipping, existing
rawContentdetection, and safe string replacement via() => rebuiltBlockare all handled correctly.apps/framework-docs-v2/src/components/mdx/index.ts (1)
63-67: LGTM. Follows the established barrel re-export pattern.apps/framework-docs-v2/src/components/mdx-renderer.tsx (1)
187-191: LGTM. Dot-notation wiring follows the established pattern.apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx (3)
95-106:GuideStepperCheckpointComponentacceptsidbut prefixes it as unused (_id) — fine, butrawContentis also silently dropped.
rawContentis declared inGuideStepperCheckpointProps(line 61) and injected by the preprocessor, but the component destructures onlyid,title,children. TherawContentprop is consumed externally viacheckpoint.props.rawContentinGuideStepperStepComponent(line 160), so this is correct — just noting the indirection is intentional.
445-458: Suspense fallback is a nice touch for client hydration.Clean skeleton structure.
1-48: Imports and interfaces look clean. Uses shadcn/ui components from@/components/ui/as required.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
Outdated
Show resolved
Hide resolved
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.ts
Outdated
Show resolved
Hide resolved
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
Show resolved
Hide resolved
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
Show resolved
Hide resolved
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx
Outdated
Show resolved
Hide resolved
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx
Outdated
Show resolved
Hide resolved
apps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.ts
Show resolved
Hide resolved
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Fix all issues with AI agents
In `@apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx`:
- Around line 316-317: The array stepIds is recreated each render which breaks
memoization downstream; compute a stable stepIdsKey first (as already present)
and then memoize stepIds via useMemo(() => steps.map(s => s.props.id),
[stepIdsKey]); update any other derived arrays created from steps to use that
same pattern so completedStepIds, defaultExpandedValues, progress and
toggleStepComplete (and any other hooks that list stepIds as a dependency)
receive a stable stepIds reference derived from stepIdsKey.
- Around line 42-48: Add the missing export to the GuideStepperProps interface
declaration so it reads as an exported interface (matching other exported
interfaces like GuideStepperStepProps and GuideStepperCheckpointProps) and
remove the redundant export type { GuideStepperProps } declaration later in the
file (the separate type-only export) to avoid duplication; update the symbol
GuideStepperProps accordingly so consumers import the interface directly.
In
`@apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.test.ts`:
- Around line 22-26: The test constructs React elements using createElement with
a children prop which violates the noChildrenProp lint; change the createElement
calls (e.g., the one assigned to node) to pass the children as the third
argument instead of as a children property (also update the other occurrence
around lines 31-32) so createElement("div", { id: "checkpoint-1", title:
"Collect context files" }, "content") pattern is used rather than providing
children inside the props object.
In
`@apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.test.tsx`:
- Around line 1-23: Current tests read the component source and regex-match
className strings (in vertical-progress-steps.test.tsx) which is brittle;
instead import and render the VerticalProgressSteps component (from
vertical-progress-steps.tsx) using `@testing-library/react`, then assert against
the DOM: render the component, find the numbered badge element (e.g., by role,
text, or test-id) and assert it has the expected centered class or computed
style (justify-center), and find the list element (ListTag) and assert it
suppresses native markers (has class list-none or style listStyleType ===
'none'); replace the fs/path/readFileSync + regex expectations with these
render-based assertions so the tests validate runtime output rather than source
text.
In
`@apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx`:
- Around line 30-39: The code redundantly calls getProgressStepsVariant inside
VerticalProgressStepsRoot even though the prop variant is already typed and
defaulted; remove the resolvedVariant variable and use the incoming variant
directly to determine ListTag (replace resolvedVariant === "bulleted" with
variant === "bulleted") and any other usages, and delete the
getProgressStepsVariant call from VerticalProgressStepsRoot (leave
getProgressStepsVariant function alone if used elsewhere) so the component
relies on the typed/ defaulted prop.
- Around line 24-28: VerticalProgressStepItemComponent currently only
destructures children and thus appears to drop id and title even though the
parent reads item.props.title and item.props.id; add a brief inline comment
above VerticalProgressStepItemComponent stating that id and title are
intentionally not consumed by this render component because the parent accesses
them via the React element's props (item.props.title / item.props.id), and keep
the function signature as-is to preserve the pattern.
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (11)
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdxapps/framework-docs-v2/src/components/mdx-renderer.tsxapps/framework-docs-v2/src/components/mdx/index.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.test.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.test.tsxapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx
🧰 Additional context used
📓 Path-based instructions (5)
apps/framework-docs-v2/content/**/*.mdx
📄 CodeRabbit inference engine (apps/framework-docs-v2/CLAUDE.md)
apps/framework-docs-v2/content/**/*.mdx: Use{{ include "shared/path.mdx" }}directives to reuse content fragments, which are processed viaprocessIncludes()during build
Validate code snippets in documentation with the@testdirective for TypeScript and Python code blocks
TypeScript code snippets in documentation should be validated for syntax with brace matching; Python snippets should be validated for indentation
Files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
apps/framework-docs-v2/content/guides/**/*.mdx
📄 CodeRabbit inference engine (apps/framework-docs-v2/CLAUDE.md)
Guide MDX files in
content/guides/must include frontmatter with title and description fields
Files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Run linting checks before submitting PRs for TypeScript/JavaScript code
**/*.{ts,tsx,js,jsx}: Group imports by external dependencies, internal modules, and types; use named exports from barrel files (index.ts)
Use camelCase for variables and functions, PascalCase for types/classes/components, UPPER_SNAKE_CASE for constants in TypeScript/JavaScript
Prefix unused variables with underscore (e.g.,_unusedParam) to bypass linting errors in TypeScript/JavaScript
Format TypeScript/JavaScript code with Prettier usingexperimentalTernaries: true; auto-formats on commit via Husky + lint-staged
Files:
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.test.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.tsapps/framework-docs-v2/src/components/mdx-renderer.tsxapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.test.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/src/components/mdx/index.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
apps/framework-docs-v2/src/**/*.{ts,tsx}
📄 CodeRabbit inference engine (apps/framework-docs-v2/CLAUDE.md)
Component library must use shadcn/ui components located in
src/components/ui/
Files:
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.test.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.tsapps/framework-docs-v2/src/components/mdx-renderer.tsxapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.test.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/src/components/mdx/index.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Prefer interfaces for objects, types for unions/intersections in TypeScript; explicit return types on public APIs
Files:
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.test.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.tsapps/framework-docs-v2/src/components/mdx-renderer.tsxapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.test.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/src/components/mdx/index.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
🧠 Learnings (20)
📓 Common learnings
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : Use `{{ include "shared/path.mdx" }}` directives to reuse content fragments, which are processed via `processIncludes()` during build
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/guides/**/*.mdx : Guide MDX files in `content/guides/` must include frontmatter with title and description fields
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdxapps/framework-docs-v2/src/components/mdx-renderer.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/index.ts
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : Validate code snippets in documentation with the `test` directive for TypeScript and Python code blocks
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.test.tsx
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : Use `{{ include "shared/path.mdx" }}` directives to reuse content fragments, which are processed via `processIncludes()` during build
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdxapps/framework-docs-v2/src/components/mdx-renderer.tsx
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : TypeScript code snippets in documentation should be validated for syntax with brace matching; Python snippets should be validated for indentation
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2025-12-17T23:59:22.807Z
Learnt from: callicles
Repo: 514-labs/moosestack PR: 3143
File: apps/framework-docs/llm-docs/python/table-setup.md:331-336
Timestamp: 2025-12-17T23:59:22.807Z
Learning: In apps/framework-docs/llm-docs/**/*.md (LLM documentation), prefer exact class and type names (e.g., "MaterializedView", "OlapTable") over lowercase prose variants (e.g., "materialized view") to help LLMs generate correct code with proper imports and syntax.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Use Vercel Toolbar feature flags for visibility control: `show-draft-guides`, `show-beta-guides`, `show-hosting-section`, `show-ai-section`, `show-copy-as-markdown`, `show-linear-integration`
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-15T19:41:53.563Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: examples/cdp-analytics/CLAUDE.md:0-0
Timestamp: 2026-01-15T19:41:53.563Z
Learning: Applies to examples/cdp-analytics/web-app/src/features/dashboard/*.tsx : Dashboard components should follow React hooks patterns: use useState for local data, useEffect for data fetching, handle errors with fallback data, and wrap visualizations in Card/CardHeader/CardContent from Radix UI
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdxapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx
📚 Learning: 2026-01-28T14:50:00.978Z
Learnt from: cjus
Repo: 514-labs/moosestack PR: 3407
File: apps/framework-docs-v2/content/guides/static-report-generation.mdx:1402-1406
Timestamp: 2026-01-28T14:50:00.978Z
Learning: When reviewing WebApp implementations that run in a Node.js backend, prefer Node.js-specific types (e.g., Buffer) and avoid browser-focused cross-platform compatibility considerations. This guideline applies to MDX documentation and code examples across the repository where backend/runtime code is discussed; ensure reviewers distinguish server-side context from frontend/browser constraints and validate type usage accordingly.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-19T20:47:10.159Z
Learnt from: DatGuyJonathan
Repo: 514-labs/moosestack PR: 3365
File: apps/framework-docs-v2/src/proxy.ts:4-21
Timestamp: 2026-01-19T20:47:10.159Z
Learning: In Next.js 15/16+, middleware has been renamed to "proxy". A file named `proxy.ts` placed in the project root or `src/` directory with an exported `proxy` function and optional `config` object with `matcher` will be automatically loaded by Next.js without additional configuration. This is the correct pattern for route rewrites and does not require integration in next.config.js.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-27T17:36:29.854Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: examples/nextjs-moose/CLAUDE.md:0-0
Timestamp: 2026-01-27T17:36:29.854Z
Learning: Applies to examples/nextjs-moose/moose/src/query-examples/**/*.ts : Query example functions must use `eventsModel.toSql()` to generate SQL, ensuring consistent query construction through the defined model
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-27T17:36:29.854Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: examples/nextjs-moose/CLAUDE.md:0-0
Timestamp: 2026-01-27T17:36:29.854Z
Learning: Applies to examples/nextjs-moose/app/actions.ts : Server actions must import query functions from the moose package and wrap them, serving as the bridge between frontend React components and backend moose query functions
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-08T18:32:10.998Z
Learnt from: DatGuyJonathan
Repo: 514-labs/moosestack PR: 3170
File: apps/framework-docs-v2/src/components/copy-page-button.tsx:36-38
Timestamp: 2026-01-08T18:32:10.998Z
Learning: In the moosestack repository (apps/framework-docs-v2), ternary expressions for conditional JSX rendering follow a specific formatting style where the condition and `?` are on the first line, the true branch is indented on the next line, and the `:` and false branch are on the third line without parentheses. This pattern is especially common for copy/check icon toggles.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-28T14:55:13.411Z
Learnt from: cjus
Repo: 514-labs/moosestack PR: 3407
File: apps/framework-docs-v2/content/guides/static-report-generation.mdx:1585-1616
Timestamp: 2026-01-28T14:55:13.411Z
Learning: In documentation and tutorial files under apps/framework-docs-v2/content/guides/, prefer explicit, self-contained code examples that may duplicate small snippets for clarity over abstracting with DRY helpers. Ensure examples are easy to understand in isolation, even if it means a bit of repetition, to aid learning and reduce cognitive load for readers.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-02-01T23:07:12.361Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-01T23:07:12.361Z
Learning: Add E2E tests to `python-tests` and `typescript-tests` templates when changing user-facing features
Applied to files:
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.test.tsx
📚 Learning: 2026-01-08T18:32:03.114Z
Learnt from: DatGuyJonathan
Repo: 514-labs/moosestack PR: 3170
File: apps/framework-docs-v2/src/components/copy-page-button.tsx:36-38
Timestamp: 2026-01-08T18:32:03.114Z
Learning: Enforce the following multiline ternary formatting for conditional JSX without parentheses: place the condition and the '?' on the first line, place the true branch on the next indented line, and place the ':' plus the false branch on the third line. This pattern is commonly used for copy/check icon toggles in the moosestack repository (apps/framework-docs-v2). Apply this style to all TSX files under apps/framework-docs-v2/src/**/*.tsx to ensure consistency and readability.
Applied to files:
apps/framework-docs-v2/src/components/mdx-renderer.tsxapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.test.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx
📚 Learning: 2025-12-16T23:08:31.521Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-16T23:08:31.521Z
Learning: Ensure all tests pass: `cargo test` for Rust components and appropriate test commands for TS/JS
Applied to files:
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.test.tsx
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Add new guides to `guidesNavigationConfig` in `src/config/navigation.ts` with required fields: type, slug, title, icon, languages, and status (start as 'draft')
Applied to files:
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/src/components/mdx/index.ts
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/src/**/*.{ts,tsx} : Component library must use shadcn/ui components located in `src/components/ui/`
Applied to files:
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx
📚 Learning: 2026-02-01T23:07:12.361Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-01T23:07:12.361Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Group imports by external dependencies, internal modules, and types; use named exports from barrel files (`index.ts`)
Applied to files:
apps/framework-docs-v2/src/components/mdx/interactive/index.tsapps/framework-docs-v2/src/components/mdx/index.ts
🧬 Code graph analysis (6)
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.test.ts (1)
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.ts (2)
getProgressStepsVariant(10-12)isVerticalProgressStepItemElement(14-23)
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.ts (1)
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts (10)
calculateProgress(100-121)getDefaultExpandedValues(123-145)sanitizeCompletedStepIds(46-51)sanitizeStepIds(60-76)isGuideStepperStepElement(147-157)isGuideStepperCheckpointElement(159-169)isGuideStepperAtAGlanceElement(171-182)getOpenStepIdsAfterCompletionToggle(78-84)getSanitizedOpenStepIds(53-58)buildGuideStepPromptMarkdown(86-98)
apps/framework-docs-v2/src/components/mdx-renderer.tsx (4)
apps/framework-docs-v2/src/components/mdx/index.ts (7)
GuideStepper(63-63)GuideStepperStep(64-64)GuideStepperCheckpoint(65-65)GuideStepperAtAGlance(66-66)GuideStepperPrompt(67-67)VerticalProgressSteps(68-68)VerticalProgressStepItem(69-69)apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx (1)
GuideStepper(447-452)apps/framework-docs-v2/src/components/mdx/interactive/index.ts (7)
GuideStepper(35-35)GuideStepperStep(36-36)GuideStepperCheckpoint(37-37)GuideStepperAtAGlance(38-38)GuideStepperPrompt(39-39)VerticalProgressSteps(47-47)VerticalProgressStepItem(48-48)apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx (1)
VerticalProgressSteps(86-88)
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.ts (1)
apps/framework-docs-v2/src/components/mdx/interactive/index.ts (1)
ProgressStepsVariant(52-52)
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx (5)
apps/framework-docs-v2/src/components/mdx/interactive/index.ts (7)
GuideStepperProps(40-40)GuideStepperStepProps(41-41)GuideStepperCheckpointProps(42-42)GuideStepperPromptProps(44-44)GuideStepperAtAGlanceProps(43-43)VerticalProgressSteps(47-47)GuideStepper(35-35)apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts (9)
isGuideStepperCheckpointElement(159-169)isGuideStepperAtAGlanceElement(171-182)buildGuideStepPromptMarkdown(86-98)isGuideStepperStepElement(147-157)sanitizeCompletedStepIds(46-51)getDefaultExpandedValues(123-145)getSanitizedOpenStepIds(53-58)calculateProgress(100-121)getOpenStepIdsAfterCompletionToggle(78-84)apps/framework-docs-v2/src/components/ui/checkbox.tsx (1)
Checkbox(30-30)apps/framework-docs-v2/src/components/mdx/index.ts (2)
VerticalProgressSteps(68-68)GuideStepper(63-63)apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx (1)
VerticalProgressSteps(86-88)
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx (1)
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.ts (3)
ProgressStepsVariant(3-3)getProgressStepsVariant(10-12)isVerticalProgressStepItemElement(14-23)
🪛 Biome (2.3.13)
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.test.ts
[error] 25-25: Avoid passing children using a prop
The canonical way to pass children in React is to use additional arguments to React.createElement
(lint/correctness/noChildrenProp)
[error] 32-32: Avoid passing children using a prop
The canonical way to pass children in React is to use additional arguments to React.createElement
(lint/correctness/noChildrenProp)
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.ts
[error] 83-83: Avoid passing children using a prop
The canonical way to pass children in React is to use additional arguments to React.createElement
(lint/correctness/noChildrenProp)
[error] 93-93: Avoid passing children using a prop
The canonical way to pass children in React is to use additional arguments to React.createElement
(lint/correctness/noChildrenProp)
[error] 110-110: Avoid passing children using a prop
The canonical way to pass children in React is to use additional arguments to React.createElement
(lint/correctness/noChildrenProp)
[error] 120-120: Avoid passing children using a prop
The canonical way to pass children in React is to use additional arguments to React.createElement
(lint/correctness/noChildrenProp)
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx
[error] 350-350: This hook does not specify its dependency on stepIds.
This dependency is being used here, but is not specified in the hook dependency list.
React relies on hook dependencies to determine when to re-compute Effects.
Failing to specify dependencies can result in Effects not updating correctly when state changes.
These "stale closures" are a common source of surprising bugs.
Unsafe fix: Add the missing dependency to the list.
(lint/correctness/useExhaustiveDependencies)
[error] 350-350: This hook specifies more dependencies than necessary: stepIdsKey.
This dependency can be removed from the list.
React relies on hook dependencies to determine when to re-compute Effects.
Specifying more dependencies than required can lead to unnecessary re-rendering
and degraded performance.
Unsafe fix: Remove the extra dependencies from the list.
(lint/correctness/useExhaustiveDependencies)
🪛 LanguageTool
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
[uncategorized] ~437-~437: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...uctions and all checkpoint content into markdown. Inside GuideStepper.AtAGlance, write...
(MARKDOWN_NNP)
[uncategorized] ~438-~438: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...GuideStepper.AtAGlance, write regular markdown directly (no React tags required). Chec...
(MARKDOWN_NNP)
🔇 Additional comments (11)
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.test.ts (1)
16-170: Solid test coverage across all utility functions.Good breadth: progress calculation, expanded-value defaults with fallback paths, sanitization, element type guards, completion toggle, and prompt markdown assembly.
apps/framework-docs-v2/src/components/mdx/interactive/index.ts (1)
34-52: LGTM. Follows the established barrel export pattern consistently.apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx (1)
441-493: GuideStepper demo usage looks well-structured. Phases, checkpoints, at-a-glance, and nested code blocks are all demonstrated clearly.apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.ts (1)
1-23: Clean utility module. Type guard follows the same duck-typing pattern asguide-stepper-utils.ts. No issues.apps/framework-docs-v2/src/components/mdx-renderer.tsx (1)
195-201: LGTM. MDX component map entries follow the established dot-notation pattern.apps/framework-docs-v2/src/components/mdx/index.ts (1)
63-69: LGTM!New interactive component exports are cleanly added to the barrel.
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx (3)
96-107:idis destructured but unused (prefixed correctly as_id).Clean.
197-303:GuideStepperStepComponentrender logic is solid.Good use of shadcn/ui components, proper accessibility labels, clean composition of checkpoints/body/at-a-glance sections.
431-444: Suspense fallback is a nice touch for the persisted-state hydration boundary.apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts (2)
46-76: SharedsanitizeStepIdsextraction looks good.Clean deduplication with
Set-based lookups.
86-98:buildGuideStepPromptMarkdownis clean and well-structured.Trims, filters empties, joins with double newline. Straightforward.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx
Outdated
Show resolved
Hide resolved
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx
Outdated
Show resolved
Hide resolved
| const node = createElement("div", { | ||
| id: "checkpoint-1", | ||
| title: "Collect context files", | ||
| children: "content", | ||
| }); |
There was a problem hiding this comment.
Biome lint: pass children as createElement's third argument, not as a prop.
Will fail noChildrenProp lint rule.
🔧 Fix
- const node = createElement("div", {
- id: "checkpoint-1",
- title: "Collect context files",
- children: "content",
- });
+ const node = createElement(
+ "div",
+ { id: "checkpoint-1", title: "Collect context files" },
+ "content",
+ );- const node = createElement("div", { children: "content only" });
+ const node = createElement("div", null, "content only");Also applies to: 31-32
🧰 Tools
🪛 Biome (2.3.13)
[error] 25-25: Avoid passing children using a prop
The canonical way to pass children in React is to use additional arguments to React.createElement
(lint/correctness/noChildrenProp)
🤖 Prompt for AI Agents
In
`@apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps-utils.test.ts`
around lines 22 - 26, The test constructs React elements using createElement
with a children prop which violates the noChildrenProp lint; change the
createElement calls (e.g., the one assigned to node) to pass the children as the
third argument instead of as a children property (also update the other
occurrence around lines 31-32) so createElement("div", { id: "checkpoint-1",
title: "Collect context files" }, "content") pattern is used rather than
providing children inside the props object.
| import fs from "fs"; | ||
| import path from "path"; | ||
| import { describe, expect, it } from "vitest"; | ||
|
|
||
| describe("VerticalProgressSteps", () => { | ||
| it("centers numbered badges", () => { | ||
| const source = fs.readFileSync( | ||
| path.join(__dirname, "vertical-progress-steps.tsx"), | ||
| "utf8", | ||
| ); | ||
|
|
||
| expect(source).toMatch(/<Badge[\s\S]*className="[^"]*justify-center[^"]*"/); | ||
| }); | ||
|
|
||
| it("suppresses native list markers to avoid duplicate bullets", () => { | ||
| const source = fs.readFileSync( | ||
| path.join(__dirname, "vertical-progress-steps.tsx"), | ||
| "utf8", | ||
| ); | ||
|
|
||
| expect(source).toMatch(/<ListTag className="[^"]*list-none[^"]*"/); | ||
| }); | ||
| }); |
There was a problem hiding this comment.
These tests assert against source text, not behavior — extremely brittle.
Reading the .tsx file as a string and regex-matching className values will break on any refactor (extracting to cn(), reordering props, renaming variables) without any actual regression. They verify nothing about runtime rendering.
Replace with render-based tests (e.g., @testing-library/react) that mount the component and assert on the rendered DOM.
🤖 Prompt for AI Agents
In
`@apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.test.tsx`
around lines 1 - 23, Current tests read the component source and regex-match
className strings (in vertical-progress-steps.test.tsx) which is brittle;
instead import and render the VerticalProgressSteps component (from
vertical-progress-steps.tsx) using `@testing-library/react`, then assert against
the DOM: render the component, find the numbered badge element (e.g., by role,
text, or test-id) and assert it has the expected centered class or computed
style (justify-center), and find the list element (ListTag) and assert it
suppresses native markers (has class list-none or style listStyleType ===
'none'); replace the fs/path/readFileSync + regex expectations with these
render-based assertions so the tests validate runtime output rather than source
text.
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx
Show resolved
Hide resolved
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx`:
- Around line 155-162: The useMemo for promptToCopy is ineffective because
checkpoints is a new array each render; update the code so the dependency is
stable or remove the memo: either drop useMemo and call
buildGuideStepPromptMarkdown(...) directly for promptToCopy, or create a stable
dependency (e.g. memoize raw contents with useMemo into checkpointsRawContents =
useMemo(() => checkpoints.map(c => c.props.rawContent ?? ""), [/* stable deps or
upstream */]) and then call buildGuideStepPromptMarkdown({
checkpointRawContents: checkpointsRawContents }) with [checkpointsRawContents]
as the dependency. Reference: promptToCopy, buildGuideStepPromptMarkdown,
checkpoints, useMemo.
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (7)
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsxapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/includes.ts
🧰 Additional context used
📓 Path-based instructions (5)
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Run linting checks before submitting PRs for TypeScript/JavaScript code
**/*.{ts,tsx,js,jsx}: Group imports by external dependencies, internal modules, and types; use named exports from barrel files (index.ts)
Use camelCase for variables and functions, PascalCase for types/classes/components, UPPER_SNAKE_CASE for constants in TypeScript/JavaScript
Prefix unused variables with underscore (e.g.,_unusedParam) to bypass linting errors in TypeScript/JavaScript
Format TypeScript/JavaScript code with Prettier usingexperimentalTernaries: true; auto-formats on commit via Husky + lint-staged
Files:
apps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/lib/includes.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
apps/framework-docs-v2/src/**/*.{ts,tsx}
📄 CodeRabbit inference engine (apps/framework-docs-v2/CLAUDE.md)
Component library must use shadcn/ui components located in
src/components/ui/
Files:
apps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/lib/includes.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Prefer interfaces for objects, types for unions/intersections in TypeScript; explicit return types on public APIs
Files:
apps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/lib/includes.tsapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
apps/framework-docs-v2/content/**/*.mdx
📄 CodeRabbit inference engine (apps/framework-docs-v2/CLAUDE.md)
apps/framework-docs-v2/content/**/*.mdx: Use{{ include "shared/path.mdx" }}directives to reuse content fragments, which are processed viaprocessIncludes()during build
Validate code snippets in documentation with the@testdirective for TypeScript and Python code blocks
TypeScript code snippets in documentation should be validated for syntax with brace matching; Python snippets should be validated for indentation
Files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
apps/framework-docs-v2/content/guides/**/*.mdx
📄 CodeRabbit inference engine (apps/framework-docs-v2/CLAUDE.md)
Guide MDX files in
content/guides/must include frontmatter with title and description fields
Files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
🧠 Learnings (28)
📓 Common learnings
Learnt from: okane16
Repo: 514-labs/moosestack PR: 3465
File: apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx:32-41
Timestamp: 2026-02-07T03:51:52.784Z
Learning: In apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx and similar MDX components: Retain runtime normalization helpers like getProgressStepsVariant even when props are typed, because MDX-authored content can pass arbitrary strings at runtime that bypass TypeScript type checking. These helpers provide safe fallbacks for unsupported values.
Learnt from: okane16
Repo: 514-labs/moosestack PR: 3465
File: apps/framework-docs-v2/src/components/mdx-renderer.tsx:91-96
Timestamp: 2026-02-07T03:51:57.720Z
Learning: In apps/framework-docs-v2/src/components/mdx-renderer.tsx, the Object.assign pattern for creating component wrappers with subcomponents (e.g., `GuideStepperWithSubcomponents = Object.assign(GuideStepper, { Step, Checkpoint, AtAGlance, Prompt })`) is required for MDX prerendering to resolve dotted component access like `GuideStepper.AtAGlance`, even when the source component export already has subcomponents attached. Removing these wrappers causes build failures during prerender.
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : Use `{{ include "shared/path.mdx" }}` directives to reuse content fragments, which are processed via `processIncludes()` during build
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Validate `{{ include }}` directives in content before build using `pnpm run validate:includes` with `scripts/validate-includes.ts`
Applied to files:
apps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/includes.ts
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : Validate code snippets in documentation with the `test` directive for TypeScript and Python code blocks
Applied to files:
apps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : Use `{{ include "shared/path.mdx" }}` directives to reuse content fragments, which are processed via `processIncludes()` during build
Applied to files:
apps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/includes.tsapps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-02-01T23:07:12.361Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-01T23:07:12.361Z
Learning: Add E2E tests to `python-tests` and `typescript-tests` templates when changing user-facing features
Applied to files:
apps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.ts
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : TypeScript code snippets in documentation should be validated for syntax with brace matching; Python snippets should be validated for indentation
Applied to files:
apps/framework-docs-v2/src/lib/includes.test.tsapps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
📚 Learning: 2025-12-16T23:09:10.917Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-cli/AGENTS.md:0-0
Timestamp: 2025-12-16T23:09:10.917Z
Learning: Applies to apps/framework-cli/**/*.rs : Test error conditions and edge cases
Applied to files:
apps/framework-docs-v2/src/lib/includes.test.ts
📚 Learning: 2026-02-07T03:51:52.784Z
Learnt from: okane16
Repo: 514-labs/moosestack PR: 3465
File: apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx:32-41
Timestamp: 2026-02-07T03:51:52.784Z
Learning: In apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx and similar MDX components: Retain runtime normalization helpers like getProgressStepsVariant even when props are typed, because MDX-authored content can pass arbitrary strings at runtime that bypass TypeScript type checking. These helpers provide safe fallbacks for unsupported values.
Applied to files:
apps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
📚 Learning: 2026-02-07T03:51:57.720Z
Learnt from: okane16
Repo: 514-labs/moosestack PR: 3465
File: apps/framework-docs-v2/src/components/mdx-renderer.tsx:91-96
Timestamp: 2026-02-07T03:51:57.720Z
Learning: In apps/framework-docs-v2/src/components/mdx-renderer.tsx, the Object.assign pattern for creating component wrappers with subcomponents (e.g., `GuideStepperWithSubcomponents = Object.assign(GuideStepper, { Step, Checkpoint, AtAGlance, Prompt })`) is required for MDX prerendering to resolve dotted component access like `GuideStepper.AtAGlance`, even when the source component export already has subcomponents attached. Removing these wrappers causes build failures during prerender.
Applied to files:
apps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.tsapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsxapps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
📚 Learning: 2026-01-19T22:37:05.393Z
Learnt from: DatGuyJonathan
Repo: 514-labs/moosestack PR: 3282
File: apps/framework-cli-e2e/test/utils/llm-agent-utils.ts:613-742
Timestamp: 2026-01-19T22:37:05.393Z
Learning: In the LLM Documentation Automation test (`apps/framework-cli-e2e/test/llm-docs-automation.test.ts` and `apps/framework-cli-e2e/test/utils/llm-agent-utils.ts`), token limit failures are intentional. The test should fail if the agent exceeds Claude's context window, as this signals that documentation or task complexity needs improvement and represents what a real user would experience.
Applied to files:
apps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.ts
📚 Learning: 2026-02-07T03:51:52.784Z
Learnt from: okane16
Repo: 514-labs/moosestack PR: 3465
File: apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx:32-41
Timestamp: 2026-02-07T03:51:52.784Z
Learning: In apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx and similar MDX components, retain runtime normalization helpers like getProgressStepsVariant even when props are typed. MDX-authored content can pass arbitrary strings at runtime that bypass TypeScript type checking, so these helpers provide safe fallbacks for unsupported values and prevent runtime errors. Apply to all TSX files in the mdx/interactive directory so downstream MDX content remains robust against unexpected inputs.
Applied to files:
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Add new guides to `guidesNavigationConfig` in `src/config/navigation.ts` with required fields: type, slug, title, icon, languages, and status (start as 'draft')
Applied to files:
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/src/**/*.{ts,tsx} : Component library must use shadcn/ui components located in `src/components/ui/`
Applied to files:
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsxapps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Applies to apps/framework-docs-v2/content/guides/**/*.mdx : Guide MDX files in `content/guides/` must include frontmatter with title and description fields
Applied to files:
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-02-01T23:07:12.361Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-01T23:07:12.361Z
Learning: Applies to **/*.{ts,tsx} : Prefer interfaces for objects, types for unions/intersections in TypeScript; explicit return types on public APIs
Applied to files:
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx
📚 Learning: 2026-01-08T18:32:03.114Z
Learnt from: DatGuyJonathan
Repo: 514-labs/moosestack PR: 3170
File: apps/framework-docs-v2/src/components/copy-page-button.tsx:36-38
Timestamp: 2026-01-08T18:32:03.114Z
Learning: Enforce the following multiline ternary formatting for conditional JSX without parentheses: place the condition and the '?' on the first line, place the true branch on the next indented line, and place the ':' plus the false branch on the third line. This pattern is commonly used for copy/check icon toggles in the moosestack repository (apps/framework-docs-v2). Apply this style to all TSX files under apps/framework-docs-v2/src/**/*.tsx to ensure consistency and readability.
Applied to files:
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsxapps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Content in the `shared/` folder must only be used via the `include` system (processed by `src/lib/includes.ts`), not directly as routes
Applied to files:
apps/framework-docs-v2/src/lib/includes.ts
📚 Learning: 2026-01-15T19:41:53.563Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: examples/cdp-analytics/CLAUDE.md:0-0
Timestamp: 2026-01-15T19:41:53.563Z
Learning: Applies to examples/cdp-analytics/web-app/src/features/dashboard/*.tsx : Dashboard components should follow React hooks patterns: use useState for local data, useEffect for data fetching, handle errors with fallback data, and wrap visualizations in Card/CardHeader/CardContent from Radix UI
Applied to files:
apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsxapps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2025-12-16T23:09:10.917Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-cli/AGENTS.md:0-0
Timestamp: 2025-12-16T23:09:10.917Z
Learning: Applies to apps/framework-cli/**/*.rs : Document all public APIs and breaking changes
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2025-12-17T23:59:22.807Z
Learnt from: callicles
Repo: 514-labs/moosestack PR: 3143
File: apps/framework-docs/llm-docs/python/table-setup.md:331-336
Timestamp: 2025-12-17T23:59:22.807Z
Learning: In apps/framework-docs/llm-docs/**/*.md (LLM documentation), prefer exact class and type names (e.g., "MaterializedView", "OlapTable") over lowercase prose variants (e.g., "materialized view") to help LLMs generate correct code with proper imports and syntax.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Use Vercel Toolbar feature flags for visibility control: `show-draft-guides`, `show-beta-guides`, `show-hosting-section`, `show-ai-section`, `show-copy-as-markdown`, `show-linear-integration`
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-28T14:50:00.978Z
Learnt from: cjus
Repo: 514-labs/moosestack PR: 3407
File: apps/framework-docs-v2/content/guides/static-report-generation.mdx:1402-1406
Timestamp: 2026-01-28T14:50:00.978Z
Learning: When reviewing WebApp implementations that run in a Node.js backend, prefer Node.js-specific types (e.g., Buffer) and avoid browser-focused cross-platform compatibility considerations. This guideline applies to MDX documentation and code examples across the repository where backend/runtime code is discussed; ensure reviewers distinguish server-side context from frontend/browser constraints and validate type usage accordingly.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-19T20:47:10.159Z
Learnt from: DatGuyJonathan
Repo: 514-labs/moosestack PR: 3365
File: apps/framework-docs-v2/src/proxy.ts:4-21
Timestamp: 2026-01-19T20:47:10.159Z
Learning: In Next.js 15/16+, middleware has been renamed to "proxy". A file named `proxy.ts` placed in the project root or `src/` directory with an exported `proxy` function and optional `config` object with `matcher` will be automatically loaded by Next.js without additional configuration. This is the correct pattern for route rewrites and does not require integration in next.config.js.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-27T17:36:29.854Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: examples/nextjs-moose/CLAUDE.md:0-0
Timestamp: 2026-01-27T17:36:29.854Z
Learning: Applies to examples/nextjs-moose/moose/src/query-examples/**/*.ts : Query example functions must use `eventsModel.toSql()` to generate SQL, ensuring consistent query construction through the defined model
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-27T17:36:29.854Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: examples/nextjs-moose/CLAUDE.md:0-0
Timestamp: 2026-01-27T17:36:29.854Z
Learning: Applies to examples/nextjs-moose/app/actions.ts : Server actions must import query functions from the moose package and wrap them, serving as the bridge between frontend React components and backend moose query functions
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-08T18:32:10.998Z
Learnt from: DatGuyJonathan
Repo: 514-labs/moosestack PR: 3170
File: apps/framework-docs-v2/src/components/copy-page-button.tsx:36-38
Timestamp: 2026-01-08T18:32:10.998Z
Learning: In the moosestack repository (apps/framework-docs-v2), ternary expressions for conditional JSX rendering follow a specific formatting style where the condition and `?` are on the first line, the true branch is indented on the next line, and the `:` and false branch are on the third line without parentheses. This pattern is especially common for copy/check icon toggles.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-22T19:02:52.316Z
Learnt from: CR
Repo: 514-labs/moosestack PR: 0
File: apps/framework-docs-v2/CLAUDE.md:0-0
Timestamp: 2026-01-22T19:02:52.316Z
Learning: Guide promotion workflow: start guides with `status: "draft"` in navigation config, then progress to `status: "beta"`, finally remove status field for public release
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
📚 Learning: 2026-01-28T14:55:13.411Z
Learnt from: cjus
Repo: 514-labs/moosestack PR: 3407
File: apps/framework-docs-v2/content/guides/static-report-generation.mdx:1585-1616
Timestamp: 2026-01-28T14:55:13.411Z
Learning: In documentation and tutorial files under apps/framework-docs-v2/content/guides/, prefer explicit, self-contained code examples that may duplicate small snippets for clarity over abstracting with DRY helpers. Ensure examples are easy to understand in isolation, even if it means a bit of repetition, to aid learning and reduce cognitive load for readers.
Applied to files:
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
🧬 Code graph analysis (3)
apps/framework-docs-v2/src/lib/includes.test.ts (1)
apps/framework-docs-v2/src/lib/includes.ts (1)
INCLUDE_REGEX(11-11)
apps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.ts (1)
apps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.ts (1)
processGuideStepperPrompts(67-105)
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx (2)
apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts (9)
isGuideStepperCheckpointElement(147-159)isGuideStepperAtAGlanceElement(161-172)buildGuideStepPromptMarkdown(78-86)isGuideStepperStepElement(135-145)sanitizeCompletedStepIds(38-43)getDefaultExpandedValues(111-133)getSanitizedOpenStepIds(45-50)calculateProgress(88-109)getOpenStepIdsAfterCompletionToggle(70-76)apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx (1)
VerticalProgressSteps(88-90)
🪛 LanguageTool
apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx
[uncategorized] ~437-~437: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...at concatenates checkpoint content into markdown. GuideStepper.AtAGlance remains visib...
(MARKDOWN_NNP)
[uncategorized] ~439-~439: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...GuideStepper.AtAGlance, write regular markdown directly (no React tags required). Chec...
(MARKDOWN_NNP)
🔇 Additional comments (11)
apps/framework-docs-v2/src/lib/includes.ts (1)
10-11: Clean regex tightening.Leading-space allowance for JSX-nested includes,
\S+capture to avoid trailing whitespace in paths, and explicit tab exclusion all make sense.apps/framework-docs-v2/src/lib/includes.test.ts (1)
1-51: Solid edge-case coverage.All five cases exercise the regex boundary conditions well.
lastIndexresets are correct for the global flag.apps/framework-docs-v2/src/lib/guide-stepper-prompt-preprocessor.test.ts (1)
1-96: Good coverage including the previously requested Prompt and repeated-block cases.apps/framework-docs-v2/src/components/mdx/interactive/vertical-progress-steps.tsx (1)
1-92: Clean component with proper defensive patterns for MDX runtime.Accessible markup, shadcn/ui usage, and the
Object.assignsubcomponent pattern are all correct.apps/framework-docs-v2/content/guides/test-guides/interactive-guide-demo.mdx (3)
442-494: GuideStepper demo section looks correct.Component usage matches the defined props interface (
id,persist,Stepwithid/number/title/summary, nestedAtAGlanceandCheckpointblocks).
502-512: VerticalProgressSteps standalone demo is clean.Bulleted variant with
.Itemsubcomponents — matches the component API.
564-589:⚠️ Potential issue | 🟡 MinorSyntax reference for include-fragment orchestration uses
:::with a space beforeinclude.The example on lines 569, 581, 584 shows
::: include(with a space between:::andinclude), but the actual regex expects:::include(no space). Since this is inside a fenced code block it won't be processed, but it's misleading documentation — readers copying the pattern will get broken includes.✏️ Fix — remove the space
-::: include /shared/guides/<guide>/migration-intro.mdx +:::include /shared/guides/<guide>/migration-intro.mdxApply the same to lines 581 and 584.
⛔ Skipped due to learnings
Learnt from: CR Repo: 514-labs/moosestack PR: 0 File: apps/framework-docs-v2/CLAUDE.md:0-0 Timestamp: 2026-01-22T19:02:52.316Z Learning: Applies to apps/framework-docs-v2/content/**/*.mdx : Use `{{ include "shared/path.mdx" }}` directives to reuse content fragments, which are processed via `processIncludes()` during buildLearnt from: CR Repo: 514-labs/moosestack PR: 0 File: apps/framework-docs-v2/CLAUDE.md:0-0 Timestamp: 2026-01-22T19:02:52.316Z Learning: Guide promotion workflow: start guides with `status: "draft"` in navigation config, then progress to `status: "beta"`, finally remove status field for public releaseLearnt from: CR Repo: 514-labs/moosestack PR: 0 File: apps/framework-docs-v2/CLAUDE.md:0-0 Timestamp: 2026-01-22T19:02:52.316Z Learning: Applies to apps/framework-docs-v2/content/guides/**/*.mdx : Guide MDX files in `content/guides/` must include frontmatter with title and description fieldsLearnt from: okane16 Repo: 514-labs/moosestack PR: 3465 File: apps/framework-docs-v2/src/components/mdx-renderer.tsx:91-96 Timestamp: 2026-02-07T03:51:57.720Z Learning: In apps/framework-docs-v2/src/components/mdx-renderer.tsx, the Object.assign pattern for creating component wrappers with subcomponents (e.g., `GuideStepperWithSubcomponents = Object.assign(GuideStepper, { Step, Checkpoint, AtAGlance, Prompt })`) is required for MDX prerendering to resolve dotted component access like `GuideStepper.AtAGlance`, even when the source component export already has subcomponents attached. Removing these wrappers causes build failures during prerender.apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx (2)
303-389: State management inGuideStepperInneris well-structured.
stepIdsmemoized fromsteps, sanitization effects, progress computation, and the toggle callback all have correct and stable dependency arrays. Persistence sync logic is sound.
431-452: Suspense wrapper andObject.assigncomposition pattern look good.Skeleton fallback is appropriate. The
Object.assignpattern is required for MDX prerendering per established learnings.apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper-utils.ts (2)
1-68: Utilities are clean and well-factored.
sanitizeStepIdsshared helper withSet-based deduplication addresses the prior duplication concern. Type guard invariant comments are present.
161-172: Pipeline guaranteesrawContentinjection before guard evaluation.
processGuideStepperPromptsis always called first incontent.ts(lines 103-105) as the mandatory preprocessing step before any content reaches MDX rendering. The guard correctly relies onrawContentpresence as a type discriminator—if preprocessing is skipped, the element is correctly rejected, which is intentional behavior. No alternate codepaths bypass this pipeline.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
| const promptToCopy = useMemo( | ||
| () => | ||
| buildGuideStepPromptMarkdown({ | ||
| checkpointRawContents: checkpoints.map( | ||
| (checkpoint) => checkpoint.props.rawContent ?? "", | ||
| ), | ||
| }), | ||
| [checkpoints], |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
useMemo on promptToCopy has an unstable dependency.
checkpoints is a new array every render (line 141–143), so [checkpoints] always triggers recomputation. The memo is a no-op. Either memoize checkpoints upstream or drop the useMemo wrapper since buildGuideStepPromptMarkdown is cheap.
🤖 Prompt for AI Agents
In `@apps/framework-docs-v2/src/components/mdx/interactive/guide-stepper.tsx`
around lines 155 - 162, The useMemo for promptToCopy is ineffective because
checkpoints is a new array each render; update the code so the dependency is
stable or remove the memo: either drop useMemo and call
buildGuideStepPromptMarkdown(...) directly for promptToCopy, or create a stable
dependency (e.g. memoize raw contents with useMemo into checkpointsRawContents =
useMemo(() => checkpoints.map(c => c.props.rawContent ?? ""), [/* stable deps or
upstream */]) and then call buildGuideStepPromptMarkdown({
checkpointRawContents: checkpointsRawContents }) with [checkpointsRawContents]
as the dependency. Reference: promptToCopy, buildGuideStepPromptMarkdown,
checkpoints, useMemo.
1 participant
Note
Medium Risk
Introduces new client-side interactive components and a regex-based MDX preprocessor in the content pipeline, which could affect rendering/persistence behavior across docs pages if edge cases aren’t covered.
Overview
Adds new interactive MDX UI primitives:
GuideStepper(multi-step accordion with progress, per-step completion persistence, nested checkpoints, and a Copy Prompt action that concatenates checkpoint markdown) andVerticalProgressSteps(standalone vertical checklist UI).Wires these components into the MDX renderer/export surface and extends content processing to (1) allow indented
:::includedirectives and (2) preprocess MDX to injectrawContentintoGuideStepper.*blocks (skipping code fences) so prompt-copy works without authors manually duplicating text; includes unit tests for both preprocessors and updates the interactive demo guide to showcase the new components.Written by Cursor Bugbot for commit 46a788f. This will update automatically on new commits. Configure here.