refactor: restore root-level development workflow with enhanced tooling

- Add root package.json with development scripts and dependencies
- Move scripts/ from lib back to root for intuitive developer experience
- Clean lib/package.json to contain only runtime dependencies
- Add comprehensive justfile with cross-platform command shortcuts
- Update README.md with new development workflow instructions
- Maintain lib as clean, publishable package while enabling root-level commands

.gitignore

@@ -73,4 +73,4 @@ insertr-cli/build-errors.log
 .local/
 
 # Demo site generated files
-demo-site/insertr.js
+demo-site/insertr.js# Node.js root dependencies

README.md

@@ -63,28 +63,55 @@ Containers with `class="insertr"` automatically make their viable children edita
 
 ## 🛠️ Quick Start
 
-### **Development Setup**
+### **Using Just (Recommended)**
+```bash
+# Clone and setup
+git clone <repository-url>
+cd insertr
+
+# Install dependencies and start development
+just dev-setup
+
+# Or step by step:
+just install       # Install all dependencies
+just build-lib     # Build the JavaScript library
+just dev           # Start development server
+```
+
+### **Using NPM directly**
 ```bash
 # Clone repository
 git clone <repository-url>
 cd insertr
 
+# Install dependencies
+npm run install:all
+
 # Start development server with live reload
-cd insertr-cli
-air
+npm run dev
 ```
 
 Visit **http://localhost:3000** to see enhanced demo site with live reload.
 
+### **Available Commands**
+```bash
+just --list        # Show all available commands
+just dev           # Start development server
+just build         # Build library + CLI  
+just air           # Start Air hot-reload for CLI
+just check         # Validate project setup
+just clean         # Clean build artifacts
+```
+
 ### **Parse Existing Site**
 ```bash
-cd insertr-cli
-
 # Analyze HTML for editable elements
-go run main.go parse ../demo-site/
+just parse
+# or: cd insertr-cli && go run main.go parse ../demo-site/
 
 # Development server with parsing
-go run main.go servedev -i ../demo-site -p 3000
+just servedev
+# or: cd insertr-cli && go run main.go servedev -i ../demo-site -p 3000
 ```
 
 ## 📊 Parser Output Example
@@ -180,10 +207,13 @@ Static Site Build → Insertr CLI Enhancement → Enhanced Deployment
 
 ### **Live Development with Hot Reload**
 ```bash
-cd insertr-cli
-
 # 🔥 Hot Reload: watches BOTH library AND CLI
-air
+just air
+# or: cd insertr-cli && air
+
+# Alternative: Watch library only
+just watch
+# or: cd lib && npm run dev
 
 # Library changes: lib/src/**/*.js → Auto rebuild library + CLI
 # CLI changes: cmd/**/*.go → Auto rebuild CLI  

justfile

@@ -0,0 +1,93 @@
+# Insertr Development Commands
+# Use `just <command>` to run any of these tasks
+
+# Default recipe - show available commands
+default:
+    @just --list
+
+# Install all dependencies (root + lib)
+install:
+    npm install
+    cd lib && npm install
+
+# Start development server with live reload
+dev:
+    npm run dev
+
+# Start development server for about page
+dev-about:
+    npm run dev:about
+
+# Check project status and validate setup
+check:
+    npm run dev:check
+
+# Show demo instructions
+demo:
+    npm run dev:demo
+
+# Build the entire project (library + CLI)
+build:
+    npm run build
+
+# Build only the JavaScript library
+build-lib:
+    npm run build:lib
+
+# Watch library files for changes (auto-rebuild)
+watch:
+    cd lib && npm run dev
+
+# Start Air hot-reload for Go CLI development
+air:
+    cd insertr-cli && air
+
+# Build Go CLI only
+build-cli:
+    cd insertr-cli && go build -o insertr
+
+# Run CLI help
+cli-help:
+    cd insertr-cli && go run main.go --help
+
+# Parse demo site with CLI
+parse:
+    cd insertr-cli && go run main.go parse ../demo-site/
+
+# Start CLI development server
+servedev:
+    cd insertr-cli && go run main.go servedev -i ../demo-site -p 3000
+
+# Clean all build artifacts
+clean:
+    rm -rf lib/dist
+    rm -rf insertr-cli/insertr
+    rm -rf node_modules
+    rm -rf lib/node_modules
+
+# Lint code (placeholder for now)
+lint:
+    npm run lint
+
+# Run tests (placeholder for now)
+test:
+    npm run test
+
+# Development workflow: install deps, build lib, start dev server
+dev-setup: install build-lib dev
+
+# Production workflow: install deps, build everything
+prod-build: install build
+
+# Show project status
+status:
+    @echo "🏗️  Insertr Project Status"
+    @echo "========================="
+    @echo "📁 Root files:"
+    @ls -la package.json justfile 2>/dev/null || echo "   Missing files"
+    @echo "\n📚 Library files:"
+    @ls -la lib/package.json lib/src lib/dist 2>/dev/null || echo "   Missing library components"
+    @echo "\n🔧 CLI files:"
+    @ls -la insertr-cli/main.go insertr-cli/insertr 2>/dev/null || echo "   Missing CLI components"
+    @echo "\n🌐 Demo site:"
+    @ls -la demo-site/index.html demo-site/about.html 2>/dev/null || echo "   Missing demo files"

lib/package.json

@@ -14,12 +14,7 @@
     "build:only": "rollup -c",
     "copy:demo": "cp dist/insertr.js ../demo-site/insertr.js",
     "watch": "rollup -c -w",
-    "dev": "rollup -c -w",
-    "serve": "node scripts/dev.js serve",
-    "serve:about": "live-server ../demo-site --port=3000 --open=/about.html",
-    "check": "node scripts/dev.js check",
-    "demo": "node scripts/dev.js demo",
-    "build:all": "node scripts/build.js"
+    "dev": "rollup -c -w"
   },
   "keywords": [
     "cms",
@@ -32,7 +27,6 @@
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^15.0.0",
     "@rollup/plugin-terser": "^0.4.0",
-    "live-server": "^1.2.2",
     "rollup": "^3.0.0"
   },
   "dependencies": {

package.json

@@ -0,0 +1,49 @@
+{
+  "name": "insertr",
+  "version": "0.1.0",
+  "description": "The Tailwind of CMS - Zero-configuration content editing for any static site",
+  "main": "lib/dist/insertr.js",
+  "type": "module",
+  "scripts": {
+    "dev": "node scripts/dev.js serve",
+    "dev:about": "live-server demo-site --port=3000 --open=/about.html",
+    "dev:check": "node scripts/dev.js check",
+    "dev:demo": "node scripts/dev.js demo",
+    "dev:help": "node scripts/dev.js help",
+    "build": "node scripts/build.js",
+    "build:lib": "cd lib && npm run build",
+    "test": "echo 'Test script placeholder - will add tests for insertr.js'",
+    "lint": "echo 'Linting placeholder - will add ESLint'",
+    "serve": "npm run dev",
+    "start": "npm run dev",
+    "install:all": "npm install && cd lib && npm install"
+  },
+  "keywords": [
+    "cms",
+    "headless-cms",
+    "static-site-generator",
+    "content-management",
+    "build-time-enhancement",
+    "zero-config",
+    "go",
+    "javascript"
+  ],
+  "author": "Insertr Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourusername/insertr.git"
+  },
+  "devDependencies": {
+    "live-server": "^1.2.2"
+  },
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=8.0.0"
+  },
+  "browserslist": [
+    "defaults",
+    "not IE 11"
+  ],
+  "dependencies": {}
+}

scripts/build.js

@@ -14,7 +14,7 @@ console.log('🔨 Building Insertr library and CLI...\n');
 // 1. Build the library
 console.log('📦 Building JavaScript library...');
 try {
-    execSync('npm run build', { stdio: 'inherit' });
+    execSync('npm run build', { cwd: 'lib', stdio: 'inherit' });
     console.log('✅ Library built successfully\n');
 } catch (error) {
     console.error('❌ Library build failed:', error.message);
@@ -23,8 +23,8 @@ try {
 
 // 2. Copy built library to CLI assets
 console.log('📁 Copying library to CLI assets...');
-const srcDir = './dist';
-const destDir = '../insertr-cli/pkg/content/assets';
+const srcDir = './lib/dist';
+const destDir = './insertr-cli/pkg/content/assets';
 
 // Ensure destination directory exists
 fs.mkdirSync(destDir, { recursive: true });
@@ -43,7 +43,7 @@ console.log('📁 Assets copied successfully\n');
 // 3. Build the CLI
 console.log('🔧 Building Go CLI...');
 try {
-    execSync('go build -o insertr', { cwd: '../insertr-cli', stdio: 'inherit' });
+    execSync('go build -o insertr', { cwd: './insertr-cli', stdio: 'inherit' });
     console.log('✅ CLI built successfully\n');
 } catch (error) {
     console.error('❌ CLI build failed:', error.message);
@@ -55,4 +55,4 @@ console.log('📋 What was built:');
 console.log('  • JavaScript library (lib/dist/)');
 console.log('  • Go CLI with embedded library (insertr-cli/insertr)');
 console.log('\n🚀 Ready to use:');
-console.log('  cd ../insertr-cli && ./insertr --help');
+console.log('  cd insertr-cli && ./insertr --help');

scripts/dev.js

@@ -21,7 +21,7 @@ const commands = {
       console.log('   ✏️  Client: Click "Login as Client" → "Edit Mode: On"');
       console.log('   🔧 Developer: View source to see integration\n');
       
-       spawn('npx', ['live-server', '../demo-site', '--port=3000', '--open=/index.html'], {
+      spawn('npx', ['live-server', 'demo-site', '--port=3000', '--open=/index.html'], {
         stdio: 'inherit'
       });
     }
@@ -34,10 +34,10 @@ const commands = {
       
       // Check files exist
       const requiredFiles = [
-         '../demo-site/index.html',
-         '../demo-site/about.html', 
-         'dist/insertr.js',
-         'dist/insertr.min.js',
+        'demo-site/index.html',
+        'demo-site/about.html', 
+        'lib/dist/insertr.js',
+        'lib/dist/insertr.min.js',
         'package.json'
       ];
       
@@ -57,13 +57,13 @@ const commands = {
         console.log('\n📊 Project stats:');
         
         // Count editable elements
-         const indexContent = fs.readFileSync('../demo-site/index.html', 'utf8');
-         const aboutContent = fs.readFileSync('../demo-site/about.html', 'utf8');
+        const indexContent = fs.readFileSync('demo-site/index.html', 'utf8');
+        const aboutContent = fs.readFileSync('demo-site/about.html', 'utf8');
         const insertrMatches = (indexContent + aboutContent).match(/class="insertr"/g) || [];
         console.log(`   📝 Editable elements: ${insertrMatches.length}`);
         
         // Check library size
-         const libSize = fs.statSync('dist/insertr.js').size;
+        const libSize = fs.statSync('lib/dist/insertr.js').size;
         console.log(`   📦 Library size: ${(libSize / 1024).toFixed(1)}KB`);
         
          console.log('\n🚀 Ready to develop! Run: npm run serve');