creator-core-kit

Imported from itsNintu/creator-core-kit (AGENTS.md). Install upstream with npx skills add itsNintu/creator-core-kit. Copyright stays with the author.

Creator Core

Repository UI skills

Use the relevant repo skill when building or changing UI. These skills travel with the template and link to the maintained docs and implementation:

Read only the skills relevant to the task; multiple may apply. For React Bits imports, read docs/REACT_BITS.md and the vendor guidance installed directly for the product under its developer’s own license. Code and the linked docs remain authoritative; update affected skill guidance when changing a workflow or public component API. Skills guide implementation and do not expand the user's requested scope.

Mode / fresh-sandbox autosetup

Read docs/MODEINSPECT.md before setting up Modeinspect or any fresh preview sandbox. Ask the user for missing service environment variables; setup is incomplete until they are supplied. Required: NEXT_PUBLIC_HEXCLAVE_PROJECT_ID, HEXCLAVE_SECRET_SERVER_KEY, NEXT_PUBLIC_CONVEX_URL, and a development CONVEX_DEPLOY_KEY for that same Convex deployment. NEXT_PUBLIC_HEXCLAVE_PROJECT_ID is the only project-ID input; startup copies it to Convex as HEXCLAVE_PROJECT_ID. Backend sync is always required: dev:mode configures backend auth and runs persistent Convex sync, starting Next after the first successful push. Request secure entry, never log secret values. Do not provision anonymous/local substitute services, invent values, or bypass auth unless the user explicitly requests a separate local setup. Install with bun install --frozen-lockfile; register bun run dev:mode as the persistent dev-server command (default port 3000). Preserve .env.local. Verify browser connectivity and signed-in pages; HTTP 200 alone is insufficient.

Project rules

• Use Bun and commit bun.lock with dependency changes.
• Stack: Next.js App Router, TypeScript, shadcn/ui Base UI, Convex, Hexclave.
• Colors: keep complete, independently editable primary, accent, and neutral scales in src/app/globals.css. Use semantic primary for ordinary actions and selected controls, neutrals for surfaces, and brand accent only for deliberate highlights. Primary starts with the same palette as neutral. Follow the ui-colors skill; do not default to accent-colored actions or icons.
• React Bits setup: read docs/REACT_BITS.md. Install licensed source and vendor skills directly into the derived product with its developer’s own credentials; do not redistribute vendor source or proprietary guidance through this kit. Use Bun, free -TS-TW or Pro component -tw variants. Preserve Base UI, the --rb-* theme mappings, and client boundaries. Keep animations enabled; do not add system reduced-motion overrides. Registry installs may rewrite theme variables: inspect their CSS diff.
• Hexclave owns identity, teams, permissions, and enabled user services. Convex owns application data.
• Enforce access inside every Convex function. Never trust a browser-supplied owner or team ID as authorization.
• The example notes are personal, not team-owned. Team switching must never broaden access to them.
• Keep service credentials in ignored environment files and CI secrets. Each derived product needs its own service projects.
• Preserve the selected products and settings in hexclave.config.ts. Inspect the cloud override before replacing it.
• Run bun run check and bun run build:cloudflare before pushing.

Distribution and product setup

• Read docs/DISTRIBUTION.md before changing package exports, registry items, release scripts, or product initialization. The private canonical repository maintains the source and publishes verified releases to the public kit repository and npm.
• New template copies run bun run init:product --name <product-slug> before installing dependencies or editing files. The initializer requires the matching published runtime and preserves environment files. Never run it against the canonical repository.
• Keep runtime behavior in @nintu/creator-core-runtime, editable visual source in src/components, and project services/schema local. Preserve client boundaries and catalog coverage. Record kit changes with Changesets; release verification includes check:distribution --sealed, check:portable, and check:consumer.
• Publish only from the private canonical repository after verification. A package release must not deploy downstream applications. Never expand repository visibility/access or rewrite historical vendor source as a packaging side effect.

Component source of truth

• /components is the canonical catalog of this template's UI. Read docs/COMPONENTS.md and search src/lib/component-catalog.ts before adding or changing UI.
• Implementation lives in src/components; pages and compositions import it. Use src/components/ui for Base UI/shadcn controls. Do not copy controls into pages or create a second set of account widgets.
• Every reusable visual component must have a catalog entry with its real source path, an example loader, and a preview that imports the actual implementation. Update these in the same change. Gallery infrastructure and service providers are the only catalog exclusions.
• For connected UI, keep service hooks and authorization in the existing connected component. Export a view with resolved data and callbacks for previews. Production and previews must render that same view. Fixtures stay in src/components/gallery; production code must never import them. Do not add mock providers, alternate auth clients, or preview branches to authentication.
• Use AuthButtons for login/signup/dashboard entry, UserMenu, TeamSwitcher, and the registered account settings components. React Bits authentication and billing blocks are alternative design examples, not the template's connected account controls.
• Hexclave-hosted authentication, signup, recovery, verification, MFA challenges, and onboarding remain hosted. Stripe card entry and hosted payment pages remain provider-owned. Build the surrounding interface from our registered components.
• Run bun run check:components during UI work. bun run check includes it and CI runs the same check. Do not bypass coverage by adding visual components to the infrastructure exclusion.

Loading and motion

• Read docs/LOADING_MOTION.md before adding loading feedback or motion. Incoming content uses the registered ContentSkeleton (or its shared Skeleton primitive for a new shape). A user-initiated pending action uses PendingButton or PendingIndicator on the affected control. Keep existing content visible during updates; never reuse another user's or team's data as a placeholder.
• Reuse useAsyncAction for action state and the existing account form/action wrappers. Prevent duplicate submissions immediately, report success only after the operation succeeds, and keep error details and retry guidance near the action. Do not add alternate auth clients, fake service providers, or auth callback delays for loading UI.
• @nintu/creator-core-runtime/motion owns timing, easing, and distance; src/lib/motion.ts re-exports it. src/app/globals.css imports the runtime's shared motion stylesheet. In the maintained kit, edit packages/runtime/src; in derived products, upgrade the package. Do not add independent loaders, hardcoded loading animation timings, or new pulse/spin classes in owned application components or native UI controls. Preserve stable control dimensions and accessible status labels. Do not delay ready content to finish an animation.
• New owned application entrances and animated content changes use the registered src/components/motion/primitives.tsx components, powered by motion/react. Use shared presets and bounded staggering; keep stable page and data identities so refreshes do not replay a whole entrance. /components/motion-dashboard is the representative preview. Application pages and account collections use this baseline. Native controls use shared duration/easing tokens while retaining Base UI lifecycles; ordinary transitions inherit the shared defaults. Keep the persistent shell and page identity stable during updates. Authored React Bits effects require a deliberate product-level integration.
• Use the registered AnimatedNumber for key metrics, and Progress with ProgressValue for a synchronized fill and label. Both use the shared value motion preset and retarget from their current visible value. Keep ordinary numbers static, preserve real accessible targets, and never invent progress percentages for an operation of unknown duration.
• Update the Loading & motion previews alongside shared state changes. Local simulation belongs only in gallery fixtures. Run bun run check:components; its loading checks are part of CI. Do not exempt new connected UI to bypass them.

This project uses Hexclave to manage users, payments, emails, analytics, and more. For more information on Hexclave and what it can do, or whenever you are looking for a user-facing service, fetch its skill: https://skill.hexclave.com

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.