1. What is the SYMPTOM? (error message, behavior)
2. What is the IMMEDIATE cause? (the line that fails)
3. What is the ROOT cause? (why does that code exist/fail?)
4. Does this affect monorepo mode? npm mode? Both?
5. Will my fix work in BOTH modes?
6. Is this a DESIGN FLAW in core? (disconnected systems, missing abstraction, wrong assumptions)
7. Should we FIX THE DESIGN instead of patching the symptom?

// Just add a try-catch and fallback
try {
  return entityRegistry.get(slug)
} catch {
  return null // Hide the problem
}

Q: Why does this fail in npm mode?
A: There are TWO registry systems that don't sync.

Q: Why are there two systems?
A: Historical accident - one was added for client, one for server.

Q: Is this a design flaw?
A: YES - violates single source of truth.

SOLUTION: Unify into ONE system with FACADE pattern.

1. npm mode user experience (they can't debug our code)
2. Security (no exposed internals, no unsafe patterns)
3. Performance (bundle size, runtime efficiency)
4. Developer experience (clear errors, good types)
5. Monorepo convenience (last priority - we can work around issues)

Can I use dynamic imports? → NO in most cases (breaks npm mode)
Can I use require()? → ONLY in server-only files with 'import server-only'
Can I use webpack aliases in runtime code? → NO (won't resolve in npm packages)
Should I fix just the error? → NO, trace to root cause first
Should I question if this is a design flaw? → YES, ALWAYS

## Proposed Architectural Change

### Current State
[What exists now and why it's problematic]

### Root Cause
[The design decision that led to this problem]

### Proposed Solution
[New architecture that solves the root cause]

### Migration Path
[How to get from current to proposed]

### Validation
[How to verify in both monorepo and npm modes]

nextspark/
├── repo/                    # Monorepo (development)
│   ├── packages/
│   │   ├── core/            # @nextsparkjs/core
│   │   ├── cli/             # @nextsparkjs/cli
│   │   └── create-nextspark-app/
│   ├── themes/              # @nextsparkjs/theme-*
│   ├── plugins/             # @nextsparkjs/plugin-*
│   ├── apps/dev/            # Development app
│   └── .packages/           # Packed .tgz files
│
└── projects/
    └── my-app/              # npm mode test project
        ├── .packages/       # Local .tgz files
        └── package.json     # file: references to .packages/

cd repo

# Make changes to packages/core, packages/cli, themes/, plugins/
# ...

# Start dev server
pnpm dev

# Test at http://localhost:5173

# 1. TypeScript compiles
pnpm tsc --noEmit

# 2. Build succeeds
pnpm build

# 3. Manual testing checklist:
#    [ ] Server starts without errors
#    [ ] No console errors in browser
#    [ ] API endpoints respond correctly
#    [ ] Dashboard loads entities
#    [ ] CRUD operations work (after login)

# ONE COMMAND does everything:
pnpm setup:update-local

# This script:
# 1. Builds all packages
# 2. Creates .tgz files in repo/.packages/
# 3. Copies .tgz to my-app/.packages/
# 4. Updates my-app/package.json with file: references
# 5. Cleans .next cache
# 6. Runs pnpm install --force

pnpm setup:update-local                      # Full rebuild + update
pnpm setup:update-local -- --skip-build      # Skip rebuild (faster)
pnpm setup:update-local -- --target ../projects/other-app  # Different target

cd ../projects/my-app

# Start dev server
pnpm dev

# Test at http://localhost:3000

[ ] Server starts without errors
[ ] No "require is not defined" errors
[ ] No "Module not found" errors
[ ] API returns correct responses (not "Entity not found")
[ ] Dashboard sidebar shows entities
[ ] CRUD create/edit/delete works
[ ] No hydration mismatches in console

cd ../repo

# 1. Increment version
pnpm pkg:version -- patch   # or minor, major, beta

# 2. Package
pnpm pkg:pack

# 3. Publish
pnpm pkg:publish -- --tag latest   # or --tag beta

# 4. Commit
git add .
git commit -m "release: vX.Y.Z - description"
git push

cd ../projects
rm -rf my-app
npx --yes create-nextspark-app@latest my-app
cd my-app
pnpm nextspark add:theme @nextsparkjs/theme-default
pnpm dev

# Check what's different
diff repo/packages/core/src/file.ts projects/my-app/node_modules/@nextsparkjs/core/dist/file.js

# Check if using runtime aliases
grep -r "require.*@nextsparkjs" repo/packages/core/src/

# Check for 'use client' with server code
grep -l "'use client'" repo/packages/core/src/**/*.ts | xargs grep -l "require("

// API routes MUST initialize registry
import { setEntityRegistry, isRegistryInitialized } from '@nextsparkjs/core/lib/entities/queries'
import { ENTITY_REGISTRY, ENTITY_METADATA } from '@nextsparkjs/registries/entity-registry'

if (!isRegistryInitialized()) {
  setEntityRegistry(ENTITY_REGISTRY, ENTITY_METADATA)
}

# Compare installed versions
cat projects/my-app/node_modules/@nextsparkjs/core/package.json | grep version
cat repo/packages/core/package.json | grep version

# Check if local packages are being used
cat projects/my-app/package.json | grep "file:"

## Pre-Publish Checklist

### Monorepo (port 5173)
- [ ] `pnpm tsc --noEmit` passes
- [ ] `pnpm build` succeeds
- [ ] Server starts without errors
- [ ] API endpoints respond correctly
- [ ] Dashboard loads with entities
- [ ] CRUD operations work

### npm mode (port 3000)
- [ ] `pnpm setup:update-local` completed
- [ ] Server starts without errors
- [ ] No console errors in browser
- [ ] API endpoints respond correctly (not "Entity not found")
- [ ] Dashboard loads with entities
- [ ] CRUD operations work
- [ ] No hydration mismatches

### Ready to publish
- [ ] Both modes validated
- [ ] Version incremented: `pnpm pkg:version -- <type>`
- [ ] Changes committed to git

# Usage
./scripts/setup/update-local.sh [options]

# Options
--target <path>    # Target project (default: ../projects/my-app)
--skip-build       # Skip building packages
--skip-install     # Skip pnpm install

# What it does
1. Runs pack.sh --all (build + package)
2. Copies .tgz to target/.packages/
3. Updates package.json with file: references
4. Cleans .next cache
5. Runs pnpm install --force

# Package all
./scripts/packages/pack.sh --all

# Package specific
./scripts/packages/pack.sh --package core --package cli

# Skip rebuild
./scripts/packages/pack.sh --all --skip-build