### CLI Commands for Project Setup

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/governance/rfcs/rfc-0001-frontend-init.md

Demonstrates the desired command-line interface for installing Framework M, creating a new project, and starting the application in production mode, with an option to include the frontend.

```bash
pip install framework-m
m new project crm
cd crm
m prod                     # Works immediately with bundled Desk
m prod --with-frontend     # For frontend customization
```

--------------------------------

### Install and Run Studio UI

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/apps/studio/studio_ui/README.md

Install project dependencies and start the development server.

```bash
pnpm install
pnpm dev
```

--------------------------------

### Deployment Flow Example

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/architecture/architecture_decisions/0008-frontend-plugin-architecture.md

Demonstrates the steps for building and deploying the frontend, including installing dependencies, building with Vite, and options for deployment.

```bash
cd frontend
pnpm install  # Fetches @framework-m/* from registry, symlinks workspace plugins
pnpm build    # Vite bundles everything into static assets
```

```bash
# Option A: Serve from Python (like ADR-0007 bundled desk)
m build        # Bundles dist/ into Python package wheel
pip install .  # Installs with bundled frontend
m prod         # Serves static files from Python package
```

```bash
# Option B: Deploy to CDN
aws s3 sync frontend/dist s3://my-bucket/
```

```bash
# Option C: Container
COPY frontend/dist /app/static
```

--------------------------------

### Quick Start CRM App Setup

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/examples/crm/README.md

Follow these steps to create a new CRM application, define doctypes, run migrations, and start Studio.

```bash
# Create the app
uv run m new app crm

# Create DocTypes
cd crm
uv run m new doctype Contact
uv run m new doctype Deal

# Edit doctype.py and controller.py as shown above

# Run migrations
uv run m migrate init
uv run m migrate create "Add CRM doctypes" --autogenerate
uv run m migrate

# Start Studio
uv run m studio
```

--------------------------------

### Install and Run Framework M

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/frontend-customization.md

Install the Framework M Python package and start the application in production mode. The Desk UI is pre-built and served automatically.

```bash
pip install framework-m

m prod
```

--------------------------------

### Framework M Development Setup

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/libs/framework-m/README.md

Commands for cloning the repository, installing dependencies, running tests, type checking, and linting.

```bash
# Clone and setup
git clone https://gitlab.com/castlecraft/framework-m.git
cd framework-m
```

```bash
# Install dependencies
uv sync --all-packages --all-extras --all-groups
```

```bash
# Run tests
uv run pytest
```

```bash
# Type checking
uv run mypy src/framework_m --strict
```

```bash
# Linting
uv run ruff check .
uv run ruff format .
```

--------------------------------

### Example Framework M Configuration

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/reference/configuration.md

Illustrates a complete `framework_config.toml` file with settings for framework identity, installed applications, and logging.

```toml
[framework]
name = "enterprise_erp"
version = "1.2.0"

[apps]
installed = ["hrms", "payroll"]

[logging]
enabled = true
format = "json"
# These add to the mandatory default secrets
redact_keys = ["api_key", "stripe_secret", "aws_access_key"]
mask_keys = ["email", "phone", "ssn"]
mask_char = "*"

```

--------------------------------

### Run Dev Server for Local Setup

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/plugin-system-guide.md

Navigate to the business-m app directory and run the development server using 'uv run m dev' after installing dependencies.

```bash
cd apps/business-m
uv run m dev
```

--------------------------------

### Create and Run a New App

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/README.md

Scaffold a new application and start the development server. This includes a bundled Desk UI and requires no npm setup.

```bash
# Create a new app
m new:app my-app
cd my-app

# Start the application (bundled Desk UI included)
m prod
```

--------------------------------

### Start Studio Server

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/apps/studio/docs/user-guide.md

Use this command to start the Studio server. You can specify a custom port if needed.

```bash
# Start Studio server
uv run m studio

# Or with a specific port
uv run m studio --port 8000
```

--------------------------------

### Install framework-m-standard with uv

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/libs/framework-m-standard/README.md

Use this command to install the package using uv.

```bash
uv add framework-m-standard
```

--------------------------------

### Start Development Server with Frontend

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/README.md

Starts the development server with the frontend development server enabled, automatically scaffolding the frontend if it doesn't exist, installing dependencies, and enabling Hot Module Replacement (HMR).

```bash
# Start with frontend dev server
m prod --with-frontend
```

--------------------------------

### Install Frontend Dependencies

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/frontend-customization.md

After scaffolding a new frontend project, navigate into the `frontend` directory and run `pnpm install` to install all necessary dependencies.

```bash
cd frontend
pnpm install
```

--------------------------------

### Install @framework-m/plugin-sdk

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/libs/framework-m-plugin-sdk/README.md

Install the plugin SDK using npm or pnpm.

```bash
npm install @framework-m/plugin-sdk

# With pnpm
pnpm add @framework-m/plugin-sdk
```

--------------------------------

### Start Framework M Studio UI

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/apps/studio/README.md

Run the command to start the Studio UI for visual DocType building.

```bash
m studio
```

--------------------------------

### Install Framework M

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/libs/framework-m/README.md

Install the main Framework M metapackage using pip or uv.

```bash
pip install framework-m
```

```bash
uv add framework-m
```

--------------------------------

### Install @framework-m/ui

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/libs/framework-m-ui/README.md

Install the package using npm or pnpm.

```bash
npm install @framework-m/ui

# With pnpm
pnpm add @framework-m/ui
```

--------------------------------

### Install @framework-m/desk

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/libs/framework-m-desk/README.md

Install the @framework-m/desk package using npm or pnpm.

```bash
npm install @framework-m/desk

# With pnpm
pnpm add @framework-m/desk
```

--------------------------------

### Starting the Desk

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/using-the-desk.md

Instructions on how to start the Desk in production mode and the necessary database configuration.

```APIDOC
## Starting the Desk

The Desk is the main application UI served by the Framework M backend.

### Production mode

```bash
m prod
```

Open `http://localhost:8888` in your browser.

> **Database required:** Set `DATABASE_URL` in your app-level `.env` (for example, `crm/.env`) before starting Desk.
> 
> Example:
> 
> `DATABASE_URL=sqlite+aiosqlite:///./dev.db`
> 
> Without this, the UI may load but records will not be persisted to the database.
```

--------------------------------

### Install Framework-M Core and Mongo Adapter

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/libs/framework-mx-mongo/README.md

Install the necessary packages using pip or uv. Ensure framework-m-core is included.

```bash
pip install framework-m-core framework-mx-mongo
```

```bash
uv pip install framework-m-core framework-mx-mongo
```

--------------------------------

### Install framework-m-standard with pip

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/libs/framework-m-standard/README.md

Use this command to install the package using pip.

```bash
pip install framework-m-standard
```

--------------------------------

### Start Studio Server

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/studio-setup.md

Use this command to start the Studio server, which includes both the UI and API on a single port. This is the primary command for running the Studio.

```bash
m studio --port 9999
```

--------------------------------

### Start Production Runtime

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/tutorials/getting-started.md

Run the application in a production-like environment with the bundled Desk UI.

```bash
# Bundled Desk via backend
uv run m prod
```

--------------------------------

### Start Framework M Studio

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/examples/todo/README.md

Command to launch the Framework M Studio development environment.

```bash
# Start Studio
uv run m studio
```

--------------------------------

### Install @framework-m/vite-plugin

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/libs/framework-m-vite-plugin/README.md

Install the plugin using npm or pnpm.

```bash
npm install @framework-m/vite-plugin

# With pnpm
pnpm add @framework-m/vite-plugin
```

--------------------------------

### Start Local Development Server

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/website/README.md

Starts a local development server for live previewing changes. Changes are reflected without server restarts.

```bash
yarn start
```

--------------------------------

### Start Development Server

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/tutorials/getting-started.md

Launch the development server for hot-reloading of frontend and backend.

```bash
uv run m dev
```

--------------------------------

### Install Framework-M (Standard)

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/architecture/architecture_decisions/0006-mx-pattern.md

Installs the 'framework-m' meta-package, which includes core and standard adapters, using SQLAlchemy by default. Run migrations and deploy to production.

```bash
# Install "batteries included"
pip install framework-m

# Uses SQLAlchemy by default
m migrate
m prod
```

--------------------------------

### Example Production .env File

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/deployment/docker.md

This example .env file shows how to configure Framework M applications using environment variables for production secrets and settings.

```env
DATABASE_URL=postgresql+asyncpg://user:password@db:5432/dbname
FRAMEWORK_M_JWT_SECRET=your-production-secret
INSTALLED_APPS=my_business_app,custom_adapter
```

--------------------------------

### Development Mode Setup

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/studio-setup.md

Instructions for running the Studio in development mode with hot reload for the frontend.

```APIDOC
## Development Mode

For frontend development with hot reload:

**Terminal 1 - API Server:**

```bash
m studio --port 9999
```

**Terminal 2 - Frontend Dev Server:**

```bash
cd apps/studio/studio_ui
pnpm dev
```

The Vite dev server runs on `http://localhost:5173` with API proxying to port 9999.
```

--------------------------------

### Running the Studio

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/studio-setup.md

Starts the Studio server with both the UI and API on a single port.

```APIDOC
## Running Studio

Starts the Studio server with both the UI and API on a single port.

### Command

```bash
m studio --port 9999
```

### URL Structure

- **UI**: `http://127.0.0.1:9999/studio/ui/`
- **API**: `http://127.0.0.1:9999/studio/api/`
- **Root**: `http://127.0.0.1:9999/` (Redirects to `/studio/ui/`)
```

--------------------------------

### Starting Frontend Development Server

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/governance/rfcs/rfc-0001-frontend-init.md

This Python code snippet outlines the logic for starting the Framework M application with the frontend development server, including scaffolding if necessary.

```python
def _start_with_frontend(port: int, reload: bool):
    frontend_dir = Path.cwd() / "frontend"

    # Auto-scaffold if not exists
    if not frontend_dir.exists():
        _scaffold_frontend(frontend_dir)

    # Start both processes
    backend = _start_backend(port, reload)
    frontend = _start_frontend_dev(frontend_dir)

    # Wait for both
    try:
        backend.wait()
        frontend.wait()
    except KeyboardInterrupt:
        backend.terminate()
        frontend.terminate()
```

--------------------------------

### Start Backend with Frontend Dev Server

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/architecture/architecture_decisions/0007-bundled-desk-distribution.md

Starts both the backend Uvicorn server and the frontend pnpm dev server. It includes logic to auto-scaffold the frontend if it doesn't exist and handles graceful shutdown on KeyboardInterrupt.

```python
def _start_with_frontend(port: int, reload: bool):
    """Start backend + frontend dev server."""
    frontend_dir = Path.cwd() / "frontend"

    # Auto-scaffold if not exists
    if not frontend_dir.exists():
        print("No frontend/ found. Scaffolding...")
        init_frontend_command(frontend_dir)

    # Start both processes
    backend = subprocess.Popen([
        "uvicorn",
        "framework_m.app:app",
        f"--port={port}",
        "--reload" if reload else "",
    ])

    frontend = subprocess.Popen(
        ["pnpm", "dev"],
        cwd=frontend_dir,
    )

    try:
        backend.wait()
        frontend.wait()
    except KeyboardInterrupt:
        backend.terminate()
        frontend.terminate()
```

--------------------------------

### Example plugin.config.ts for Framework M

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/reference/plugin-menu-code-examples.md

This is a comprehensive example of a plugin configuration file. It demonstrates how to define application IDs, labels, icons, and resources including pages, doctypes, and reports. It also shows how to define routes for lazy-loaded components.

```typescript
import type { FrameworkMPlugin } from "@framework-m/plugin-sdk";

export default {
  name: "wms",
  version: "1.0.0",
  manifests: [
    {
      app_id: "wms",
      label: "Warehouse",
      icon: "package",
      resources: [
        {
          name: "wms.dashboard",
          label: "Warehouse Dashboard",
          route: "/wms/dashboard",
          icon: "layout-dashboard",
          type: "Page",
        },
        {
          name: "wms.item",
          label: "Inventory Items",
          route: "/app/WMSItem/list",
          icon: "box",
          type: "DocType",
        },
      ],
    },
    {
      app_id: "core",
      label: "Core",
      icon: "settings-2",
      resources: [
        {
          name: "wms.audit",
          label: "Inventory Audit",
          route: "/wms/reports/audit",
          icon: "search-check",
          type: "Report",
        },
      ],
    },
  ],
  routes: [
    {
      path: "/wms/dashboard",
      element: () => import("./pages/Dashboard"),
    },
  ],
} satisfies FrameworkMPlugin;
```

--------------------------------

### Example CLI Output for Schema Change Analysis

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/governance/rfcs/rfc-0003-schema-change-detection.md

This example demonstrates the output from the `m migrate:create` command when schema changes are detected. It shows how warnings and dangerous changes are reported, including recommendations and links to documentation. The output indicates whether a migration was created or blocked.

```text
$ m migrate:create add_phone_field

📊 Schema Change Analysis (framework-m-studio)

  ✅ SAFE: Adding 'notes' (nullable Text) to Customer

  ⚠️  WARNING: Adding 'phone' (non-nullable String) to Customer
     │ Existing rows will cause migration to fail.
     │ Recommendation: Add with default or make nullable.
     │ Docs: https://framework-m.dev/migrations/zero-downtime
     │
     └─ Use --force to proceed anyway.

  ❌ DANGEROUS: Changing 'amount' from String → Decimal in Invoice
     │ Incompatible type change requires manual data migration.
     │ Pattern: Two-Phase Migration
     │ Docs: https://framework-m.dev/migrations/type-changes
     │
     └─ Cannot auto-generate. Write migration manually.

Migration NOT created.
```

--------------------------------

### Add Framework M Packages

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/tutorials/creating-apps.md

Install Framework M and its development tools as project dependencies using uv.

```bash
uv add framework-m

uv add --dev framework-m-studio
```

--------------------------------

### Example Migration Path: After

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/governance/rfcs/rfc-0001-frontend-init.md

Demonstrates the new, simplified workflow for setting up and running a project with the integrated framework-m CLI.

```bash
pip install framework-m
m new project myapp && cd myapp
m prod                     # Just works
m prod --with-frontend     # If customizing
```

--------------------------------

### Project Setup with uv

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/tutorials/getting-started.md

Initialize a new project and add core runtime and developer tooling dependencies using uv.

```bash
mkdir my-project && cd my-project
uv init

# Core runtime
uv add framework-m

# Developer tooling
uv add --dev framework-m-studio
```

--------------------------------

### Serve Bundled Frontend with Backend

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/governance/rfcs/rfc-0001-frontend-init.md

Use this command to start the backend and serve the bundled frontend. It's the default behavior for production environments.

```bash
m prod
```

--------------------------------

### Troubleshooting DocTypes Not Appearing

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/desk-setup.md

Guides on resolving issues where custom DocTypes are not displayed in the sidebar. Requires verifying app installation, entry points in `pyproject.toml`, and server restart.

```markdown
If your custom DocTypes don't show in the sidebar:

1. **Install your app**: `cd apps/myapp && uv pip install -e .`
2. **Check entry points**: Verify `pyproject.toml` has `[project.entry-points."framework_m.apps"]`
3. **Restart server**: DocTypes are discovered at startup
4. **Check logs**: Look for "Discovered X DocType(s) from app 'myapp'"
```

--------------------------------

### Start Framework M Studio

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/tutorials/creating-apps.md

Launch the Framework M Studio development server to manage your application's data and configuration through a web interface.

```bash
uv run m studio
```

--------------------------------

### Configure Multi-Database Setup

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/architecture/architecture_decisions/0006-mx-pattern.md

Configure multiple database connections for different purposes within the same application. This example shows setting up both SQLAlchemy for transactional data and MongoDB for audit logs.

```python
# Use SQLAlchemy for transactional data
pip install framework-m-standard

# Use MongoDB for audit logs (write-heavy)
pip install framework-mx-mongo

# Configure binds in config
DATABASES = {
    "default": "postgresql://...",  # SQLAlchemy
    "audit": "mongodb://...",        # MongoDB
}
```

--------------------------------

### Example Migration Path: Before

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/governance/rfcs/rfc-0001-frontend-init.md

Illustrates the previous method for running the frontend development server before the proposed CLI integration.

```bash
git clone https://gitlab.com/castlecraft/m.git
cd m/frontend && pnpm dev
```

--------------------------------

### Install Custom App

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/desk-setup.md

Installs a custom application in editable mode using `uv pip install -e .`. This is necessary if you have developed your own app within the framework.

```bash
cd apps/myapp
uv pip install -e .
```

--------------------------------

### Install MX MongoDB Variant

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/architecture/architecture_decisions/0006-mx-pattern.md

Install the MX variant for MongoDB alongside the core framework. This command installs the necessary packages to use MongoDB as the primary database.

```bash
pip install framework-m-core framework-mx-mongo
```

--------------------------------

### New Project Initialization (Bash)

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/architecture/architecture_decisions/0007-bundled-desk-distribution.md

Commands for a new third-party developer to install the framework and create a new project.

```bash
# After this ADR implementation
pip install framework-m
m new project myapp
cd myapp
m prod                     # Just works with bundled Desk

# If customizing frontend
m prod --with-frontend     # Auto-scaffolds and starts Vite
```

--------------------------------

### Install Database Drivers

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/tutorials/getting-started.md

Install necessary database drivers for development (SQLite) and production (PostgreSQL).

```bash
# Development (SQLite)
uv add --dev aiosqlite

# Production (PostgreSQL)
uv add asyncpg
```

--------------------------------

### Register a Startup Step

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/explanation/framework-entry-points.md

Use this entry point to execute custom code during application initialization, such as binding Dependency Injection services. Ensure the class implements `BootstrapProtocol` and define an `order` for execution.

```toml
[project.entry-points."framework_m.bootstrap"]
init_my_service = "my_app.bootstrap:MyServiceInit"
```

```python
from typing import Any
from framework_m_core.interfaces.bootstrap import BootstrapProtocol

class MyServiceInit(BootstrapProtocol):
    name = "init_my_service"
    order = 40  # Runs after DB (10) and Registries (20)

    def run(self, container: Any) -> None:
        # The framework automatically hydrates apps, containers, and overrides
        # via the hydrate_apps() orchestrator before this step runs.
        print("✓ My Service Initialized")
```

--------------------------------

### Install Framework M

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/README.md

Install the framework using pip. Ensure you are using Python 3.12 or later.

```bash
pip install framework-m
```

--------------------------------

### CLI User Creation Examples

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/auth-role-management.md

Demonstrates how to create users via the CLI with explicit roles, interactive prompts, or using the backward-compatible alias.

```bash
m create-user --email user@example.com --password "strong-pass" --role User --name "App User"
```

```bash
m create-user --email admin@example.com --password "strong-pass"
```

```bash
m create-admin --email admin@example.com --password "strong-pass"
```

--------------------------------

### Initialize New Frontend Project

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/frontend-customization.md

Use the 'm studio new frontend' command to initialize a new frontend project from the standard template in a specified target directory.

```bash
m studio new frontend [TARGET]
```

```bash
# Initialize in ./frontend
m studio new frontend

# Initialize in custom directory
m studio new frontend ../my-ui
```

--------------------------------

### Install Website Dependencies

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/website/README.md

Installs project dependencies using yarn. This is typically the first step before running any other commands.

```bash
yarn
```

--------------------------------

### Install Dependencies with pnpm

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/frontend-testing.md

Command to install project dependencies using pnpm. Use this when encountering 'Cannot find module' errors.

```bash
pnpm install
```

--------------------------------

### Deployment Scenario 1 (Bash)

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/architecture/architecture_decisions/0007-bundled-desk-distribution.md

Deploying with standard packages, including framework-m, business-m, and wms-app.

```bash
# Scenario 1: Deploy with standard packages
pip install framework-m business-m wms-app
m build  # Output: framework + business + wms UIs
```

--------------------------------

### Start Interactive Console with Container

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/interactive-console.md

Use this command to start the interactive console and automatically initialize the dependency injection container.

```bash
uv run m console --with-container
```

--------------------------------

### RFC File Naming Convention Example

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/governance/processes/RFC_PROCESS.md

Example of how to name RFC draft files using a placeholder number before assignment.

```bash
docs/rfcs/
├── 0001-protocol-versioning.md
├── 0002-virtual-doctype-api.md
└── ...
```

--------------------------------

### Example Usage Snippet

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/governance/processes/rfc-template.md

Illustrates how a proposed feature or change would be used in practice. This serves as a concrete example for reviewers.

```python
# Show how the feature would be used
```

--------------------------------

### Install Playwright Browsers

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/frontend-testing.md

Command to install the necessary browser binaries for Playwright. Run this if you encounter errors related to missing browsers.

```bash
pnpm exec playwright install
```

--------------------------------

### Install Framework-M with MongoDB

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/architecture/architecture_decisions/0006-mx-pattern.md

Installs the core package and the MongoDB variant ('framework-mx-mongo'). This configures the application to use MongoDB for repository operations.

```bash
# Install core + MongoDB variant
pip install framework-m-core framework-mx-mongo

# Now uses MongoDB everywhere
m migrate  # Creates MongoDB collections
m prod     # Uses Motor for queries
```

--------------------------------

### CLI Command: Uvicorn Server Start

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/explanation/features.md

Starts the uvicorn server on a specified port (defaulting to 9000) to serve the Studio UI.

```python
Start uvicorn server on port 9000 (default)
```

--------------------------------

### Full Custom Procfile Example

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/desk-setup.md

An extensive Procfile example defining commands for backend, frontend, worker, scheduler, mailhog, and redis.

```procfile
backend: uvicorn app:app --reload
frontend: cd ui && pnpm dev
worker: m worker --concurrency 8
scheduler: m worker --scheduler-only
mailhog: mailhog -smtp-bind-addr 127.0.0.1:1025
redis: redis-server
```

--------------------------------

### Start Bundled Desk UI

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/tutorials/getting-started.md

Run the application with the bundled Desk UI for immediate access to the interface.

```bash
uv run m prod
```

--------------------------------

### Procfile Example

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/architecture/architecture_decisions/0009-m-dev-redesign.md

This is an example Procfile that can be used to define custom processes for the `m dev` command, allowing for flexible development environment configurations.

```procfile
web: uvicorn app:app --port 8000
worker: m worker --concurrency 4

```

--------------------------------

### Basic Refine Setup with Framework M Providers

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/libs/framework-m-desk/README.md

Set up the Refine application using the frameworkMDataProvider, authProvider, and liveProvider from @framework-m/desk. Configure resources and live mode.

```tsx
import { Refine } from "@refinedev/core";
import {
  frameworkMDataProvider,
  authProvider,
  liveProvider,
} from "@framework-m/desk";

function App() {
  return (
    <Refine
      dataProvider={frameworkMDataProvider}
      authProvider={authProvider}
      liveProvider={liveProvider}
      options={{
        liveMode: "auto", // Enable real-time updates
      }}
      resources={[
        {
          name: "users",
          list: "/users",
          create: "/users/create",
          edit: "/users/edit/:id",
        },
      ]}>
      {/* Define your app routes */}
    </Refine>
  );
}
```

--------------------------------

### Frappe Virtual DocType Example

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/explanation/migration-from-frappe.md

Example of a Virtual DocType in Frappe, fetching data from an external API and handling custom insert logic.

```python
# Virtual DocType - data from external API, not database
class ExternalProduct(Document):
    def db_insert(self):
        # Custom insert logic
        api.create_product(self.as_dict())

    def load_from_db(self):
        data = api.get_product(self.name)
        self.update(data)
```

--------------------------------

### RFC Template Frontmatter Example

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/governance/processes/RFC_PROCESS.md

This is an example of the required frontmatter for an RFC document, including status, author, discussion link, and creation date.

```markdown
- **Status**: Proposed
- **Author**: @username
- **Discussion**: [Link to Forum Post]
- **Created**: YYYY-MM-DD
```

--------------------------------

### m dev Command Usage Examples

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/architecture/architecture_decisions/0009-m-dev-redesign.md

Demonstrates how to run the `m dev` command with default settings, a custom Procfile, or to enable specific processes.

```bash
m dev                    # Use defaults
m dev --procfile Procfile.dev  # Custom processes
m dev --enable-worker    # Enable worker from config
```

--------------------------------

### Clone and Install Business-M Module

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/examples/business-m-package.md

Steps to clone the repository, sync dependencies using uv, and run tests for the business-m module.

```bash
# Clone repository
git clone https://gitlab.com/castlecraft/framework-m/business-m.git
cd business-m

# Sync workspace using uv
uv sync

# Run tests
uv run pytest

# Run dev server
pnpm -F business-m dev
```

--------------------------------

### Run Framework M in Development Mode

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/how-to/frontend-customization.md

Standard command for full-stack development, starting the backend, frontend (Vite), and Studio. Options include custom ports and disabling the frontend.

```bash
m dev [OPTIONS]
```

--------------------------------

### CLI Scaffolding for New Projects

Source: https://gitlab.com/castlecraft/framework-m/-/blob/main/docs/architecture/architecture_decisions/0008-frontend-plugin-architecture.md

Demonstrates using the command-line interface (CLI) to scaffold a new project with frontend plugins. This includes creating a workspace project, adding applications with frontend support, and running the development server.

```bash
# Option 1: Workspace development
m new project erp
cd erp
m new app wms --with-frontend
m new app personnel --with-frontend
cd frontend
pnpm dev  # Both plugins auto-loaded via workspace

# Option 2: Install published packages
pip install framework-m business-m wms-app
m dev     # All plugins auto-loaded via entry points
m build   # Single bundle with all UIs
```