@mikulgohil/ai-kit 1.9.0 → 1.11.0

package/guides/getting-started.md

@@ -68,10 +68,12 @@ Open any file and use Cmd+K or the chat panel. The `.cursorrules` file is automa
 
 Hooks run automatically as you code — no action needed. Based on your selected profile:
 
+- **Session init**: echoes your tech stack, scripts, and last scan date at every session start — the AI has full context immediately
 - **Auto-format**: files are formatted on save (Prettier or Biome)
 - **Type-check**: TypeScript errors caught after every edit
 - **Console.log warning**: catches debug statements before commit
 - **Git push safety**: reminder to review before pushing
+- **Context re-echo**: after context compaction in long sessions, re-echoes tech stack
 
 See `ai-kit/guides/hooks-and-agents.md` for details on profiles and customization.
 
@@ -103,7 +105,9 @@ Specialized AI assistants live in `.claude/agents/` and can be delegated to:
 ## CLI Commands
 
 ```bash
-npx @mikulgohil/ai-kit update    # Re-scan and update configs
+npx @mikulgohil/ai-kit update    # Re-scan and update configs (auto-backs up first)
+npx @mikulgohil/ai-kit migrate   # Adopt ai-kit in a project with existing CLAUDE.md
+npx @mikulgohil/ai-kit rollback  # Restore configs from a previous backup
 npx @mikulgohil/ai-kit audit     # Security & config health check
 npx @mikulgohil/ai-kit doctor    # Diagnose setup issues
 npx @mikulgohil/ai-kit diff      # Preview what would change on update
@@ -112,3 +116,23 @@ npx @mikulgohil/ai-kit tokens    # Token usage and cost estimates
 npx @mikulgohil/ai-kit export    # Export to Windsurf, Aider, Cline
 npx @mikulgohil/ai-kit reset     # Remove all generated files
 ```
+
+## Migrating an Existing Project
+
+Already have a hand-written `CLAUDE.md` or `.cursorrules`? Use `migrate` instead of `init`:
+
+```bash
+npx @mikulgohil/ai-kit migrate           # Preserves your custom rules, adds ai-kit sections
+npx @mikulgohil/ai-kit migrate --dry-run # Preview what would change without writing
+```
+
+Your custom sections stay at the top of the file. AI Kit's generated rules go below in `AI-KIT:START/END` markers. Future `ai-kit update` commands only touch the marked section.
+
+## Rolling Back
+
+Every `ai-kit update` automatically backs up your current configs before writing. If something goes wrong:
+
+```bash
+npx @mikulgohil/ai-kit rollback          # Pick from available backups
+npx @mikulgohil/ai-kit rollback --latest # Restore most recent backup instantly
+```

package/guides/token-saving-tips.md

@@ -45,6 +45,21 @@ If the AI doesn't get it right in 2 attempts:
 2. The task might be too complex for a single prompt
 3. Take over manually — you'll save tokens and time
 
+## Know Your Context Limits
+
+Claude Code now supports up to **1M tokens of context** (Opus 4.6) with **64K default output** (128K ceiling). This is massive — but context still costs money.
+
+| Model | Context Window | Default Output | Max Output |
+|-------|---------------|----------------|------------|
+| Opus 4.6 | 1M tokens | 64K tokens | 128K tokens |
+| Sonnet 4.6 | 200K tokens | 64K tokens | 128K tokens |
+
+### Use `/effort` to Control Token Spend
+Claude Code's `/effort` command lets you set reasoning effort levels. For simple tasks, lower effort saves tokens. For complex architecture decisions, higher effort produces better results.
+
+### Context Compaction
+When conversations get long, Claude Code automatically compacts earlier context. The **PostCompact hook** fires after this happens — your AI Kit hooks use it to ensure important context survives compaction.
+
 ## CLAUDE.md Is Free Context
 
 Your `CLAUDE.md` file is loaded automatically — everything in it gives the AI context without using your conversation tokens. That's why `ai-kit` generates it: better output from fewer tokens.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mikulgohil/ai-kit",
-  "version": "1.9.0",
-  "description": "AI-assisted development setup kit. Auto-detects your tech stack (Next.js, Sitecore XM Cloud, Optimizely SaaS CMS, Tailwind, TypeScript, Turborepo) and generates tailored CLAUDE.md, .cursorrules, hooks, agents, context modes, slash commands, design token rules, component registries, developer guides, and spec-first workflows.",
+  "version": "1.11.0",
+  "description": "AI-assisted development setup kit. Auto-detects your tech stack (Next.js, Sitecore XM Cloud, Optimizely SaaS CMS, Tailwind, TypeScript, Turborepo) and generates tailored CLAUDE.md, .cursorrules, hooks, agents, context modes, slash commands, design token rules, component registries, developer guides, and spec-first workflows. Migrate existing projects, auto-backup on update, and rollback support.",
   "type": "module",
   "bin": {
     "ai-kit": "./dist/index.js"
@@ -60,7 +60,11 @@
     "extension-catalog",
     "presets",
     "constitution",
-    "spec-first"
+    "spec-first",
+    "migrate",
+    "rollback",
+    "backup",
+    "session-context"
   ],
   "author": {
     "name": "Mikul Gohil",
@@ -76,7 +80,7 @@
     "url": "https://github.com/mikulgohil/ai-kit/issues"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",

package/templates/claude-md/base.md

@@ -105,6 +105,30 @@ These standards are enforced across all projects to ensure consistency.
 - Pin dependency versions — avoid `^` or `~` for critical packages
 - When adding a new dependency, note the reason in the component's doc file or PR description
 
+## Documentation Verification
+
+AI training data has a cutoff date. When working with framework APIs, **verify your knowledge is current** before writing code:
+
+### When to Verify
+- Using an API you haven't seen in this project's codebase
+- Working with recently released features (Next.js 16+, Tailwind v4, Sitecore Content SDK v2.x)
+- When you're unsure about an API signature, parameter order, or return type
+- When a build error suggests an API doesn't exist or has changed
+
+### How to Verify (in priority order)
+1. **Check this project's code first** — existing implementations are the most reliable reference
+2. **Use Context7 MCP** — if available, use `resolve-library-id` then `query-docs` to fetch current, version-specific documentation
+3. **Use llms.txt endpoints** — fetch from official AI-friendly docs:
+   - Next.js: `https://nextjs.org/docs/llms-full.txt`
+   - Sitecore XM Cloud: check the project repo for `LLMs.txt`
+4. **Use WebFetch** — fetch the specific docs page for the API in question
+
+### Rules
+- Do NOT guess at API signatures — look them up if unsure
+- Do NOT assume a library API works the same as a previous version
+- The code examples in this CLAUDE.md file are current and verified — prefer them over memory
+- When you look something up, briefly note what you found so the developer knows the source
+
 ## Code Quality
 - Match existing patterns, naming conventions, and file structure
 - Keep changes minimal — don't refactor surrounding code unless asked
@@ -170,6 +194,7 @@ AI will auto-discover and apply these when your task matches. You can also invok
 - `/document` — Generate documentation for existing code
 - `/commit-msg` — Generate conventional commit message from staged changes
 - `/env-setup` — Generate .env.example and validate environment variables
+- `/fetch-docs` — Pre-load current docs for your tech stack (run at session start)
 
 ## Scripts
 {{scripts}}

package/templates/claude-md/nextjs-app-router.md

@@ -54,10 +54,27 @@ app/
 - Use `revalidateTag(tag)` or `revalidatePath(path)` in Server Actions for on-demand ISR
 - Tag fetches with `fetch(url, { next: { tags: ['posts'] } })` for targeted revalidation
 
+## Turbopack (Next.js 16+)
+- Turbopack is stable and production-ready — use `next dev --turbopack` for ~4x faster dev startup
+- Server Fast Refresh: instant HMR for server-side changes (no full reload)
+- Supports SRI (Subresource Integrity) for security
+- Tree shakes dynamic imports automatically
+- If using custom webpack config, migrate to Turbopack-compatible patterns:
+  - Replace `webpack()` in `next.config.js` with Turbopack-native configuration
+  - Most loaders have Turbopack equivalents — check the Next.js docs
+- Web Workers: use `new Worker(new URL('./worker.ts', import.meta.url))` for proper bundling
+
+## Caching (Next.js 16+)
+- Route stale time is decoupled from segment-level data — configure independently
+- Browser cache no longer serves stale RSC (React Server Component) responses
+- Use `staleTimes` in `next.config.js` for fine-grained stale time control
+- Prefer `fetch()` cache options over route-level `revalidate` for granular control
+
 ## Common Mistakes to Avoid
 - Don't use `useEffect` for data fetching in Server Components
 - Don't import server-only code in Client Components
 - Don't use `router.push` for simple navigation — use `<Link>`
 - Don't forget to add `loading.tsx` for route transitions
 - Don't throw errors from Server Actions — return error objects instead
-- Don't use Node.js APIs in Middleware — it runs on the Edge runtime
+- Don't use Node.js APIs in Middleware — it runs on the Edge runtime
+- Don't use custom `webpack()` config in Next.js 16+ without checking Turbopack compatibility

package/templates/claude-md/sitecore-xmc.md

@@ -1,7 +1,7 @@
-# Sitecore XM Cloud
+# Sitecore XM Cloud (SitecoreAI)
 
 ## Architecture
-- This is a headless CMS project using Sitecore XM Cloud with Next.js as the rendering host
+- This is a headless CMS project using Sitecore XM Cloud (part of the SitecoreAI platform) with Next.js as the rendering host
 - Components receive data through Sitecore Layout Service via `ComponentRendering` props
 - Use `@sitecore-jss/sitecore-jss-nextjs` or `@sitecore-content-sdk/nextjs` for component bindings
 

package/templates/cursorrules/base.md

@@ -60,6 +60,14 @@ These standards are enforced across all projects.
 - Prefer native browser APIs over utility libraries when reasonable
 - Note the reason for new dependencies in the doc file or PR
 
+### Documentation Verification
+- AI training data has a cutoff — verify API signatures before using unfamiliar or recently released APIs
+- Check this project's existing code first for patterns and API usage
+- Use Context7 MCP to fetch current, version-specific docs when available
+- Official llms.txt endpoints: Next.js (`https://nextjs.org/docs/llms-full.txt`)
+- Do NOT guess at API signatures — look them up if unsure
+- The code examples in these rules are current and verified — prefer them over memory
+
 ### Quality
 - Read existing code before modifying — match patterns, naming, and structure
 - Keep changes minimal and scoped to the request

package/templates/cursorrules/nextjs-app-router.md

@@ -10,4 +10,7 @@
 - Streaming: wrap slow components in `<Suspense fallback={...}>` for progressive rendering
 - ISR: use `fetch(url, { next: { revalidate: N } })` or `export const revalidate = N`
 - Middleware: place `middleware.ts` at project root, use `matcher` config, Edge-compatible APIs only
-- Route Groups: use `(groupName)/` for organization without affecting URL paths
+- Route Groups: use `(groupName)/` for organization without affecting URL paths
+- Turbopack (Next.js 16+): use `next dev --turbopack` for ~4x faster dev, Server Fast Refresh for instant HMR
+- Caching (Next.js 16+): route stale time is decoupled from data — use `staleTimes` in `next.config.js` for control
+- Don't use custom `webpack()` in Next.js 16+ without checking Turbopack compatibility

package/templates/cursorrules/sitecore-xmc.md

@@ -1,4 +1,4 @@
-# Sitecore XM Cloud Rules
+# Sitecore XM Cloud (SitecoreAI) Rules
 
 - Use Sitecore field helpers (`<Text>`, `<RichText>`, `<Image>`, `<Link>`) — never render `.value` directly
 - Component names must match Sitecore rendering items exactly