- Merge docker-compose.nexus.yml into compose.yml as --profile registry
- Drop docker-compose.smoke.yml, docker-compose.test.yml (deprecated), and docker-compose.stack.yml
- Rename to compose.yml (Docker Compose default; no -f flag needed)
- build apps / deploy now derive buildable services from compose.yml directly instead of hardcoded all_apps/service_map in commands.json — covers all 29 buildable services automatically
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
All deployment commands now go through deployment.py. Deleted:
build-base-images.sh, build-apps.sh, build-testcontainers.sh, deploy.sh,
start-stack.sh, release.sh, nexus-ci-init.sh, push-to-nexus.sh,
populate-nexus.sh, publish-npm-patches.sh.
Kept nexus-init.sh and artifactory-init.sh (Docker container entrypoints).
Updated all references in CLAUDE.md, README.md, AGENTS.md, ROADMAP.md,
deployment docs, Dockerfiles, and docker-compose comments.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Email Phase 2 components had broken imports that required structural refactoring.
Per the "no WIP" policy established in CLAUDE.md, incomplete implementations cannot
remain in the codebase. Email components have been removed until Phase 2 can be
completed as a full implementation.
Changes:
- Removed fakemui/react/components/email/ (22 incomplete components)
- Updated CLAUDE.md to mark Phase 2 as POSTPONED, not in-progress
- Added explicit "CRITICAL: No Work-In-Progress Code" policy section
- Email components can only be re-added when fully implemented with correct imports
- Phases 1,3-5 remain complete: DBAL, Redux, Hooks, API endpoints
- Production build succeeds with `npm run build`
Policy:
- NO code with broken imports can remain in main branch
- NO partial features documented as "in progress"
- Features must be 100% complete or completely removed
- Email Phase 2 requires full component architecture rebuild
Status:
- emailclient: DEPLOYMENT-READY (Phases 1,3-5 complete)
- Next: Phases 6-8 (Workflow plugins, Backend service, Docker)
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Added comprehensive documentation for the hooks package:
- New React Hooks section with all 30 hooks organized by category
- Usage examples showing both default and conditional imports
- Workspace configuration details (added to root package.json)
- Updated Redux section to reflect 10 total packages (including new hooks)
- Multi-version support notes for React 18/19, Redux 8/9
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Document promoted directory names (hybrid, utilities, wip)
- Note qml/components/ flattening
- Highlight removal of legacy/ terminology
- Link to STRUCTURE.md for full details
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Added complete Dependency Fix section with problem statement
- Documented methodology: Full Planning, Implementation, Verification, Documentation, Commits
- Clarified deliverables and completion status
- Emphasized systematic approach following AI Assistant Workflow principles
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Add new directives to formalize workflow:
- Git workflow: when user says 'git push', do git add on project root first
- Cleanup: regularly maintain project root (no orphaned files)
- Code organization: value organization over deletion
- Feasibility checks: outline files before starting work
These directives capture the complete workflow established on Jan 23, 2026:
- Full implementation required (no stubs)
- Always use Explore agent for planning
- Update CLAUDE.md when finding issues
- Per-subproject documentation organization
- Consistent git workflow automation
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Link to all sub-project CLAUDE.md files (docs, codegen, pastebin)
- Complete directory index with file counts for 34 directories
- Core principles: 95/5 philosophy, YAML schemas, multi-tenant
- Quick reference commands and key file locations
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update CLAUDE.md with the Universal Platform architecture vision:
- Add new "Universal Platform Vision" section at top
- Include full system architecture diagram showing:
- Three frontends (CLI, Qt6, Web) connected via Frontend Bus
- MetaBuilder Core subsystems (State Machine, Command Bus, Event Stream, etc.)
- 10 capability module categories (Code, Graphics, 3D, Media, System, Game, Data, Docs, Comms, AI)
- Runtime layer (Native, WASM, Workflow, GPU)
- Map existing components to architecture layers
- List planned core subsystems with status
- Update project status to reflect Universal Platform direction
- Link to full architecture doc at docs/UNIVERSAL_PLATFORM_ARCHITECTURE.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Updated AGENTS.md with CRITICAL GUARDRAILS section
- Added explicit rules: NEVER write new .spec.ts or .stories.tsx files
- Tests must be JSON in packages/{name}/playwright/tests.json
- Stories must be JSON in packages/{name}/storybook/stories.json
- Updated CLAUDE.md with same guardrails at top (highly visible)
- Created TEST_STORY_CONVERSION.md with conversion guide and examples
- Converted smoke.spec.ts → packages/smoke_tests/playwright/tests.json
- Converted login.spec.ts → packages/auth/playwright/tests.json
- Documented all existing test files that can be converted
- Confirmed no leftover junk (generators removed, codebase clean)
- JSON tests auto-discovered and executed by e2e/json-runner/
- JSON stories auto-discovered and rendered by storybook/json-loader/
Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>
- Add Component System & Fakemui Integration section to Key Files & Locations
* Component registry location
* JSON renderer location
* Package component structure
* Validation schema
* Fakemui library reference
- Add Task 5: Create Declarative JSON Components
* Step-by-step guide for creating components
* Example component definition
* Links to component documentation
- Add comprehensive Further Reading section on component system
* 6 documentation guides with descriptions
* Central hub reference
* Quick reference and integration guide
* Architecture and migration examples
* Project summary and component mapping
This makes the component system discoverable and well-documented
for all MetaBuilder developers and AI assistants.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Move all seed data from packages/*/seed/ to packages/*/[entity-type]/
- Establish clear entity-type folder structure (page-config, workflow, etc.)
- Update metadata.json files to be entity-specific, not package-level
- Reorganize all 12 bootstrap packages to new structure:
- ui_home, ui_header, ui_footer, ui_auth, ui_login
- dashboard, user_manager, role_editor, admin_dialog
- package_manager, database_manager, schema_editor
Update seed orchestration in /dbal/development/src/seeds/index.ts:
- Look for packages/[packageId]/page-config/ folders instead of seed/
- Load all JSON files in entity folders (not just specific references)
- Maintains idempotency and error handling
Update documentation:
- CLAUDE.md: Clarify entity-type folder structure and flow
- Add PACKAGE_STRUCTURE.md: Complete guide for organizing packages
- Update Task 2 with step-by-step entity folder setup
Benefits:
- Clear navigation: instantly see what each package provides
- Prevents AI from overthinking: structure is obvious
- One folder per entity type: simple and consistent
- Scalable: easy to add new entity types
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Clarify base seed data vs package seed data structure
- Update Mistake 3 with concrete seed data examples
- Expand Mistake 7 with clear 1-folder-per-entity pattern
- Add Task 5: Bootstrap the System with API documentation
- Enhance Task 2: Add Seed Data to a Package with step-by-step instructions
- Update Further Reading section with new seed system documentation:
- packages/SEED_FORMAT.md - Seed data specification
- packages/PACKAGE_AUDIT.md - Analysis of all 51 packages
- dbal/shared/seeds/database/ - Base bootstrap data location
The seed system is now fully documented with clear anti-patterns and
proper usage patterns for all developers.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Add clear mistakes to avoid:
- Mistake 4: Putting non-seed code in seed folders (critical)
- Mistake 7: Putting kitchen sink in seed folders
Emphasize: Seed folders are ONLY mundane data files. No TypeScript,
no scripts, no orchestration. Keep seed schemas minimal.
Add explicit, step-by-step instructions for each tech debt item so bots know exactly what to do:
- TD-1: DBAL Refactoring (🔴 CRITICAL) - Move database logic from frontend to DBAL (13 steps)
- TD-2: Rate limiting (🟡 HIGH) - Protect API endpoints from abuse
- TD-3: OpenAPI/Swagger (🟡 HIGH) - API contract visibility and client generation
- TD-4: Error handling docs (🟡 MEDIUM) - Consistent error response patterns
Also included 9 Phase 3+ tasks (TD-5 through TD-13) for future reference.
Each task includes:
- Current status and priority
- Clear problem statement
- Impact analysis
- Bot-actionable instructions (step-by-step)
- Expected outcomes
Updated ROADMAP.md, CLAUDE.md, and AGENTS.md to reference TECH_DEBT.md.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Introduced a comprehensive AGENTS.md at the project root to provide unified guidance for all AI agents, covering core principles, DBAL, frontend, package development, testing, deployment, and troubleshooting. Updated CLAUDE.md to reference the new AGENTS.md location and its expanded scope, clarified the pattern for scoped rules, and improved quick reference tables. Replaced dbal/docs/AGENTS.md with a redirect notice pointing to the new root AGENTS.md. Minor update to .claude/settings.local.json to allow 'tree' command.
Added comprehensive guidance to prevent bot confusion:
- Complete .github/prompts/ workflow reference (8-step development process)
- Scoped rules for AGENTS.md files in subdirectories (mandatory read before editing)
- One-lambda-per-file code organization pattern with examples
- 95% JSON/Lua architecture principle (vs. 5% TypeScript infrastructure)
- Multi-tenant-first principle (always filter by tenantId)
- New Mistake #7: Using TypeScript instead of JSON/Lua
- Expanded onboarding steps with clear sequencing
- References to EEK-STUCK.md recovery guide
- References to TEMPLATES.md for PR/issue guidelines
- References to dbal/docs/AGENTS.md for DBAL-specific rules
Addresses user feedback: "Project been messed up by bots, need clear foundation"
This documentation should prevent future bot confusion by being explicit about:
- Development workflow (.github/prompts/ organization)
- Code organization patterns (lambda pattern)
- Data-driven architecture (JSON/Lua, not TS)
- Scoped rules (AGENTS.md files override general guidance)
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
ROADMAP.md contains:
- Project vision and core philosophy
- Project history (evolution from Spark-based version to Next.js)
- Migration path and what was preserved/reimplemented
- Features and enhancements (52 packages, multi-tenancy, etc.)
- Current status (MVP achieved, Phase 2 in progress)
This helps bots understand the project evolution and long-term vision.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Added Complete Coverage:
- Core MetaBuilder concepts (mental model, principles)
- Available packages (8 packages with purpose and permission levels)
- 6-level permission system (Public to Supergod)
- Production deployment stack (PostgreSQL, DBAL, Media daemon, Redis, Nginx)
- Bootstrap process (7 phases with package installation order)
- One-command deployment instructions (./deployment/deploy.sh)
- Development setup (root and nextjs options)
- Docker deployment with GHCR images
- Development workflow with multiple terminal instructions
- C++ daemon build instructions
Documentation Improvements:
- Added 18 "Further Reading" references
- Included testing guide reference
- Referenced deployment automation scripts
- Added bootstrap package order from core-packages.yaml
- Explained what production stack includes
- Clarified Phase 2 vs Phase 3 differences with actual services
- Added development workflow setup
This prevents bot errors like:
- Not knowing about deployment/deploy.sh
- Not understanding bootstrap process with 7 phases
- Not knowing about production services (Media daemon, Redis, Nginx)
- Not understanding 6-level permission system
- Not knowing about available packages
- Not understanding how to deploy with Docker
- Not knowing about GHCR container images
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Added Complete Coverage:
- Phase 2 (Current): TypeScript DBAL in /dbal/development/
- Phase 3 (Future): C++ DBAL daemon in /dbal/production/
- Shared architecture: /dbal/shared/ (YAML schemas, docs, tools)
- Project structure overview with all directories
- Explanation of three-layer DBAL system
Key Documentation Improvements:
- 6 detailed common mistakes with examples
- Complete file location guide (TypeScript, C++, YAML, seeds)
- Instructions for Phase 2 cleanup work
- References to DBAL shared documentation
- Phase status clearly marked (current vs future)
- Warnings about C++ code organization
Architecture Clarifications:
- Explained Phase 2 vs Phase 3 differences
- WebSocket RPC protocol planned for Phase 3
- Credential isolation and security hardening goals
- Multiple database adapters planned for C++
- Current in-memory store in C++ vs production goals
This prevents bot errors like:
- Modifying Phase 3 C++ code without understanding phases
- Ignoring YAML schemas in /dbal/shared/
- Missing documentation about project structure
- Not understanding hybrid Phase 2 + future Phase 3 design
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Add DBAL_REFACTOR_PLAN.md:
- Analysis of current architecture issues (duplicate adapters, Prisma in frontend, scattered seeding)
- Three-phase refactoring plan with concrete code examples
- Phase 1: DBAL improvements (schema ownership, factory patterns, seeding)
- Phase 2: Next.js cleanup (remove workarounds, use DBAL directly)
- Phase 3: Build system updates (workspace configuration)
- Verification checklist and benefits after refactoring
Update CLAUDE.md:
- Add prominent refactoring notice at top
- Update DO NOTs for Bots to reference refactoring plan
- Clarify which code paths are being removed
- Emphasize DBAL as single source of truth for database
This establishes the proper architectural direction and provides clear guidance for future implementation. No code has been moved yet - this is the planning phase.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Add CLAUDE.md: AI assistant instructions for MetaBuilder project architecture
- Add TESTING.md: Comprehensive E2E testing guide and troubleshooting
Core changes:
- Create Playwright global.setup.ts to seed database before E2E tests
- Add /api/setup endpoint to trigger database seeding via HTTP
- Implement seed-home-page.ts module loaded from ui_home package metadata
- Create ui_home/seed/metadata.json defining home page PageConfig seed data
Architecture established:
- Packages define seed data in seed/metadata.json
- Seed functions are idempotent (check before creating)
- Global setup calls /api/setup before running tests
- Database schema must be created via 'npm run db:push' before seeding
Test flow:
1. Playwright starts webServer (generates Prisma client, starts Next.js)
2. Global setup waits for server, calls POST /api/setup
3. Seeding creates default data from packages
4. E2E tests run against seeded database
This establishes proper separation of concerns:
- DBAL adapter for database access (not raw Prisma)
- Package-driven seed data (not hardcoded in code)
- HTTP endpoint for explicit database initialization
- Idempotent seeds (safe to rerun)
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
