SonicJs-Org
diff --git a/‎.claude/commands/sonicjs-release-engineer.md‎
Lines changed: 26 additions & 15 deletions b/‎.claude/commands/sonicjs-release-engineer.md‎
Lines changed: 26 additions & 15 deletions
diff --git a/‎.claude/settings.local.json‎
Lines changed: 2 additions & 1 deletion b/‎.claude/settings.local.json‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎.github/workflows/deploy-stats.yml‎
Lines changed: 49 additions & 0 deletions b/‎.github/workflows/deploy-stats.yml‎
Lines changed: 49 additions & 0 deletions
diff --git a/‎.github/workflows/pr-tests.yml‎
Lines changed: 1 addition & 1 deletion b/‎.github/workflows/pr-tests.yml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.gitignore‎
Lines changed: 3 additions & 0 deletions b/‎.gitignore‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 6 additions & 12 deletions b/‎CLAUDE.md‎
Lines changed: 6 additions & 12 deletions
diff --git a/‎README.md‎
Lines changed: 55 additions & 32 deletions b/‎README.md‎
Lines changed: 55 additions & 32 deletions
@@ -1,5 +1,14 @@
 # Release Engineer Agent
 
+## Critical Rules (NEVER violate without explicit instruction)
+
+- **ALL releases use `npm run version:beta` (`3.x.x-beta.N` → `3.x.x-beta.N+1`) until the user explicitly says "we are out of beta" or "release stable".** NEVER use `version:patch`, `version:minor`, or `version:major` for routine releases — those drop the pre-release suffix and publish a stable version.
+- **NEVER add `--tag beta` (or alpha/rc) when publishing** — all publishes go to `latest` dist-tag regardless of the version string containing `-beta.N`.
+- **The `beta` dist-tag MUST always point to the same version as `latest`.** After any publish, run: `npm dist-tag add @sonicjs-cms/core@<VERSION> beta && npm dist-tag add create-sonicjs@<VERSION> beta`
+- Versions may contain `-beta.N` in the version string — that is fine and expected. The dist-tag (`latest`) is what matters for `npm install` behavior.
+
+---
+
 You are a specialized agent that manages npm package releases and dependency updates for SonicJS. Your primary responsibilities are:
 
 1. **Updating npm dependencies** - Keep dependencies current and secure
@@ -110,22 +119,24 @@ npm run build:core
 
 ### Step 2: Determine Version Bump Type
 
-Ask the user for the release type if not specified:
-- **patch** (2.3.12 → 2.3.13): Bug fixes only
-- **minor** (2.3.12 → 2.4.0): New features, backwards compatible
-- **major** (2.3.12 → 3.0.0): Breaking changes
+**DEFAULT: use `version:beta` for ALL routine releases (bug fixes, features, improvements) until the user explicitly declares "out of beta" or "release stable".**
+
+Only use patch/minor/major when the user explicitly requests a stable release:
+- **beta** (3.0.0-beta.17 → 3.0.0-beta.18): DEFAULT — all bug fixes and features during beta period
+- **patch** (3.0.0 → 3.0.1): Stable releases only — bug fixes (user must confirm out-of-beta first)
+- **minor** (3.0.0 → 3.1.0): Stable releases only — new features (user must confirm out-of-beta first)
+- **major** (3.0.0 → 4.0.0): Stable releases only — breaking changes (user must confirm out-of-beta first)
 
 ### Step 3: Bump Version
 
 ```bash
-# For patch release
-npm run version:patch
-
-# For minor release
-npm run version:minor
+# DEFAULT: beta prerelease bump (3.x.x-beta.N → 3.x.x-beta.N+1)
+npm run version:beta
 
-# For major release
-npm run version:major
+# Only for stable releases (user must explicitly request):
+# npm run version:patch
+# npm run version:minor
+# npm run version:major
 ```
 
 This automatically:
@@ -401,11 +412,11 @@ npm publish --workspace=create-sonicjs --tag rc
 ## Usage Examples
 
 ```
+/release-engineer              # DEFAULT: publish next beta (X.X.X-beta.N+1) → latest dist-tag
 /release-engineer update       # Update npm dependencies
-/release-engineer patch        # Publish patch release
-/release-engineer minor        # Publish minor release
-/release-engineer major        # Publish major release
-/release-engineer beta         # Publish beta pre-release
+/release-engineer patch        # Publish stable patch (only after user declares out-of-beta)
+/release-engineer minor        # Publish stable minor (only after user declares out-of-beta)
+/release-engineer major        # Publish stable major (only after user declares out-of-beta)
 /release-engineer status       # Check current version and npm status
 ```
 
 
@@ -105,7 +105,8 @@
       "WebFetch(domain:raw.githubusercontent.com)",
       "WebFetch(domain:stackoverflow.com)",
       "WebFetch(domain:developer.mozilla.org)",
-      "mcp__*",
+      "mcp__memory__*",
+      "mcp__graphiti__*",
       "Bash(vercel:*)",
       "Bash(git add:*)",
       "Bash(git commit:*)",
 
@@ -0,0 +1,49 @@
+name: Deploy Stats
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'packages/stats/**'
+      - 'packages/core/src/**'
+      - '.github/workflows/deploy-stats.yml'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build core package
+        run: npm run build:core
+
+      - name: Type check stats
+        run: cd packages/stats && npx tsc --noEmit
+
+      - name: Apply D1 migrations
+        # stats.sonicjs.com is bound to the default sonicjs-stats worker (no --env flag)
+        run: cd packages/stats && npx wrangler d1 migrations apply DB --remote
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+      - name: Deploy stats to Cloudflare Workers
+        # Deploy to default worker (sonicjs-stats) — that is what stats.sonicjs.com is bound to
+        run: cd packages/stats && npx wrangler deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
@@ -41,7 +41,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
 
       - name: Install dependencies
 
@@ -44,6 +44,9 @@ pids
 coverage/
 *.lcov
 
+# Claude Code — local settings are per-developer, not shared
+.claude/settings.local.json
+
 # IDE
 .vscode/settings.json
 .idea/
 
@@ -143,7 +143,7 @@ Base grants only match `public` + `role`, so the `role` principal is mandatory f
 5. **Public exposure**: set `settings.baseGrants.public = ['read']` only if the data is non-PII.
 6. **PII**: set `settings.pii = true` and ensure the erase path covers it.
 7. **Tests**: add at least one `*.sqlite.test.ts` or `*.integration.test.ts` case. Mock tests prove nothing about SQL (R10).
-8. **E2E**: add a Playwright spec (numbered 68+).
+8. **E2E**: add a Playwright spec (numbered 68+). Write it; do NOT run it locally — CI validates it.
 
 ### Status snapshot (avoid re-investigating)
 
@@ -166,15 +166,14 @@ Repo indexed by **codegraph**. Bash auto-proxied by **rtk**. Default reply mode
 
 Anti-patterns: `grep -r` across repo when codegraph answers; reading 5+ files to learn a flow; spawning a subagent for a known file; verbose narration.
 
-## E2E Testing is Mandatory
+## E2E Testing
 
-Every feature/fix ships with a Playwright spec in `tests/e2e/`. Workflow:
+Every feature/fix ships with a Playwright spec in `tests/e2e/`. Write the spec, but **do NOT run E2E tests locally** — they require a running wrangler dev server, consume excessive memory, and are validated by CI on PR. Running them locally is too expensive.
 
+Workflow:
 1. Implement
 2. Add `tests/e2e/<NN>-<slug>.spec.ts` (NN = next sequential; current floor 68 — R11)
-3. `npx playwright test tests/e2e/<NN>-<slug>.spec.ts` (add `--headed` to debug)
-4. Fix any failures
-5. Commit implementation + tests together
+3. Commit implementation + tests together — CI runs E2E
 
 Spec skeleton:
 
@@ -205,15 +204,10 @@ cd packages/core && npm run type-check
 npm test
 npm test -- <pattern>            # single test by name/path
 
-# E2E (root)
-npm run e2e
-npx playwright test tests/e2e/68-x.spec.ts            # one spec
-npx playwright test tests/e2e/68-x.spec.ts --headed   # debug
-
 # Local D1 — reset + migrate + seed
 cd my-sonicjs-app && npm run setup:db
 
-# Dev server (wrangler :8787)
+# Dev server (wrangler :8787) — use only when explicitly needed, not for testing
 cd my-sonicjs-app && npm run dev
 
 # Migration bundle regen (after any packages/core/migrations/*.sql edit)
 
@@ -241,8 +241,7 @@ sonicjs-ai/
 │                          # Used for testing the published package
 │
 ├── www/                   # 🌐 Marketing website
-├── tests/e2e/             # End-to-end test suites
-└── drizzle/               # Database migrations
+└── tests/e2e/             # End-to-end test suites
 ```
 
 ### Important Notes
@@ -256,32 +255,52 @@ sonicjs-ai/
 ## 🔧 Content Management
 
 ### Creating Collections
-SonicJS uses a dynamic field system. Create collections through the admin interface or define them in the database:
-
-```sql
--- Example: Blog Posts collection with custom fields
-INSERT INTO collections (id, name, display_name, description, schema) VALUES (
-  'blog-posts', 'blog_posts', 'Blog Posts', 'Article content collection',
-  '{"type":"object","properties":{"title":{"type":"string","required":true}}}'
-);
-
--- Add dynamic fields
-INSERT INTO content_fields (collection_id, field_name, field_type, field_label, field_options) VALUES
-  ('blog-posts', 'title', 'text', 'Title', '{"maxLength": 200, "required": true}'),
-  ('blog-posts', 'content', 'richtext', 'Content', '{"toolbar": "full", "height": 400}'),
-  ('blog-posts', 'excerpt', 'text', 'Excerpt', '{"maxLength": 500, "rows": 3}'),
-  ('blog-posts', 'featured_image', 'media', 'Featured Image', '{"accept": "image/*"}'),
-  ('blog-posts', 'publish_date', 'date', 'Publish Date', '{"defaultToday": true}'),
-  ('blog-posts', 'is_featured', 'boolean', 'Featured Post', '{"default": false}');
+
+Collections are TypeScript config objects registered at app startup — no database table required.
+
+```typescript
+// src/collections/blog-posts.collection.ts
+import type { CollectionConfig } from '@sonicjs-cms/core'
+
+export default {
+  name: 'blog_post',
+  displayName: 'Blog Post',
+  slug: 'blog-posts',
+  description: 'Article content collection',
+
+  schema: {
+    type: 'object',
+    properties: {
+      title: { type: 'string', title: 'Title', required: true, maxLength: 200 },
+      content: { type: 'lexical', title: 'Content', required: true },
+      publishedAt: { type: 'datetime', title: 'Published Date' },
+    },
+    required: ['title', 'content'],
+  },
+
+  managed: true,
+  isActive: true,
+} satisfies CollectionConfig
+```
+
+```typescript
+// src/index.ts — register before createSonicJSApp
+import { registerCollections, createSonicJSApp } from '@sonicjs-cms/core'
+import blogPostsCollection from './collections/blog-posts.collection'
+
+registerCollections([blogPostsCollection])
+export default createSonicJSApp({ plugins: { register: [] } })
 ```
 
 ### Field Types
-- **text**: Single-line text with validation
-- **richtext**: WYSIWYG editor with TinyMCE
+- **string**: Single-line text with validation
+- **lexical**: Rich text editor
 - **number**: Numeric input with min/max constraints
 - **boolean**: Checkbox with custom labels
-- **date**: Date picker with format options
+- **datetime**: Date/time picker
 - **select**: Dropdown with single/multi-select
+- **slug**: URL slug with auto-generation
+- **user**: User reference picker
 - **media**: File picker with preview
 
 ## 🌐 API Endpoints
@@ -373,17 +392,21 @@ Create plugins for extending SonicJS functionality:
 
 ```typescript
 // src/plugins/my-plugin/index.ts
-import { Plugin } from '@sonicjs-cms/core'
+import type { Plugin, PluginContext } from '@sonicjs-cms/core'
 
 export default {
   name: 'my-plugin',
-  hooks: {
-    'content:beforeCreate': async (content) => {
-      // Plugin logic here
-      return content
-    }
-  }
-} as Plugin
+  version: '1.0.0',
+  description: 'My custom plugin',
+
+  async activate(context: PluginContext) {
+    // Runs when the plugin is activated
+  },
+
+  async install(context: PluginContext) {
+    // Runs once on install — migrations, seed data, etc.
+  },
+} satisfies Plugin
 ```
 
 ## 📄 License
@@ -411,9 +434,9 @@ SonicJS is 100% open source and free forever. If you find it useful, please cons
 
 ## 📞 Support
 
-- [GitHub Issues](https://github.com/lane711/sonicjs-ai/issues)
+- [GitHub Issues](https://github.com/lane711/sonicjs/issues)
 - [Documentation](docs/)
-- [Community Discussions](https://github.com/lane711/sonicjs-ai/discussions)
+- [Community Discussions](https://github.com/lane711/sonicjs/discussions)
 
 ---