### Quick Start Commands

Source: https://github.com/ahliweb/awcms/blob/main/awcms/README.md

Commands to initialize the project, install dependencies, and start the development server.

```bash
cd awcms
npm install
cp .env.example .env.local
npm run dev
```

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

### Install and Pull Ollama Models

Source: https://github.com/ahliweb/awcms/wiki/docs/architecture/ollama-integration

Install Ollama using the platform-specific installer. Then, pull recommended models like qwen3 and llama3.2. Finally, verify the Ollama daemon is serving models by checking the API tags.

```bash
# Install Ollama using the platform-specific installer

# Pull recommended models
ollama pull qwen3
ollama pull llama3.2

# Verify the daemon is serving models
curl http://localhost:11434/api/tags
```

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

### Setup Migration Environment

Source: https://github.com/ahliweb/awcms/wiki/docs/guides/wp-data-migration-script

Commands to initialize a Node.js project and install necessary dependencies for the migration script.

```bash
mkdir awcms-wp-migration
cd awcms-wp-migration
npm init -y
npm install @supabase/supabase-js dotenv node-fetch
```

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

### Example AWCMS Setup JSON Configuration

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/environment-bootstrap.md

This JSON structure outlines the expected configuration parameters for the AWCMS setup script. It includes keys for Supabase, Cloudflare, Context7, Mailketing, GitHub, and tenant-specific settings.

```json
{
  "VITE_SUPABASE_URL": "https://your-project.supabase.co",
  "VITE_SUPABASE_PUBLISHABLE_KEY": "your-publishable-key",
  "SUPABASE_SECRET_KEY": "your-secret-key",
  "VITE_EDGE_URL": "https://your-worker.workers.dev",
  "VITE_LOCAL_EDGE_URL": "http://127.0.0.1:8787",
  "CONTEXT7_API_KEY": "your-context7-key",
  "VITE_TURNSTILE_SITE_KEY": "your-turnstile-site-key",
  "TURNSTILE_SECRET_KEY": "your-turnstile-secret",
  "CLOUDFLARE_ACCOUNT_ID": "your-account-id",
  "CLOUDFLARE_API_TOKEN": "your-cloudflare-api-token",
  "R2_ACCOUNT_ID": "your-r2-account-id",
  "R2_ACCESS_KEY_ID": "your-r2-access-key-id",
  "R2_SECRET_ACCESS_KEY": "your-r2-secret-access-key",
  "R2_BUCKET_NAME": "your-r2-bucket-name",
  "R2_REGION": "auto",
  "R2_CUSTOM_DOMAIN": "media.example.com",
  "R2_S3_API_ENDPOINT": "https://<account>.r2.cloudflarestorage.com",
  "MAILKETING_API_TOKEN": "your-mailketing-token",
  "MAILKETING_DEFAULT_LIST_ID": "1",
  "GITHUB_REBUILD_TOKEN": "your-github-token",
  "GITHUB_REBUILD_OWNER": "your-org",
  "GITHUB_REBUILD_REPO": "your-repo",
  "GITHUB_REBUILD_EVENT_TYPE": "smandapbun-content-changed",
  "SMANDAPBUN_REBUILD_WEBHOOK_SECRET": "your-rebuild-secret",
  "PRIMARY_TENANT_ID": "tenant-uuid-primary",
  "PRIMARY_TENANT_SLUG": "primary",
  "SMANDAPBUN_TENANT_ID": "tenant-uuid-smandapbun",
  "SMANDAPBUN_TENANT_SLUG": "smandapbun",
  "PUBLIC_TURNSTILE_SITE_KEY": "your-public-turnstile-key",
  "MCP_SUPABASE_DB_URL": "postgresql://postgres:password@db.project.supabase.co:5432/postgres",
  "CONFIGURE_MOBILE": true
}
```

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

### Initialize Migration Project

Source: https://github.com/ahliweb/awcms/blob/main/docs/guides/wp-data-migration-script.md

Commands to create the project directory and install necessary dependencies.

```bash
mkdir awcms-wp-migration
cd awcms-wp-migration
npm init -y
npm install @supabase/supabase-js dotenv node-fetch
```

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

### Start Local Supabase

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/setup.md

Start the local Supabase instance and seed the primary tenant and admin user for local admin development.

```bash
npx supabase start
node awcms/src/scripts/seed-primary-tenant.js
node awcms/src/scripts/create-admin-user.js
```

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

### Start MCP Servers

Source: https://github.com/ahliweb/awcms/blob/main/README.md

Commands to initialize various MCP servers for development assistance.

```bash
node awcms-mcp/dist/index.js
```

```bash
scripts/start_github_mcp.sh
```

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

### Install and Run AWCMS MCP

Source: https://github.com/ahliweb/awcms/blob/main/awcms-mcp/README.md

Installs project dependencies and starts the MCP server in development mode using tsx. Ensure Node.js and npm are installed.

```bash
cd awcms-mcp
npm install
npm run dev
```

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

### Install Project Dependencies

Source: https://github.com/ahliweb/awcms/wiki/docs/dev/setup

Navigate to each project directory and run 'npm install' to set up the necessary dependencies for each part of the awcms project.

```bash
cd awcms && npm install
cd ../awcms-public/primary && npm install
cd ../../awcms-edge && npm install
cd ../awcms-mcp && npm install
```

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

### Run AWCMS Setup Helper with JSON Config

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/environment-bootstrap.md

Configure the setup script using a JSON file for non-interactive execution. This is useful for automated deployments.

```bash
python3 scripts/setup_awcms_environment.py --config-json path/to/setup.json
```

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

### Start Supabase Local Development

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/environment-bootstrap.md

Initiates the Supabase local development environment. This command is typically run after setting up the project.

```bash
npx supabase start
```

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

### Run Local Development Server

Source: https://github.com/ahliweb/awcms/wiki/docs/dev/edge-functions

Navigate to the awcms-edge directory and start the local development server using npm.

```bash
cd awcms-edge
npm run dev:local
```

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

### Setup Ollama Models

Source: https://github.com/ahliweb/awcms/blob/main/AGENTS.md

Commands to pull required models and verify the local Ollama service status.

```bash
# 1. Install Ollama (see https://ollama.com for platform-specific installers)
# 2. Pull a tool-calling capable model
ollama pull qwen3
ollama pull llama3.2

# 3. Verify the service is running
curl http://localhost:11434/api/tags
```

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

### Quick Start: Build and Upload Firmware

Source: https://github.com/ahliweb/awcms/blob/main/awcms-esp32/primary/README.md

Use this command to navigate to the firmware directory, set up environment variables, upload the filesystem, and then upload the firmware to the ESP32 device.

```bash
cd awcms-esp32/primary
cp .env.example .env
source .env && pio run -t uploadfs && pio run -t upload
```

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

### Setup Edge Worker Local Development

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/setup.md

Configure and start the local development server for the AWCMS Edge Worker. Local secrets are sourced from `.dev.vars`.

```bash
cd awcms-edge
cp .dev.vars.example .dev.vars
npm run dev:local
```

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

### Initialize and Run ConfigManager in main.cpp

Source: https://github.com/ahliweb/awcms/blob/main/AGENTS.md

Demonstrates the main loop integration for periodic configuration polling and WiFi connectivity management.

```cpp
// awcms-esp32/primary/src/main.cpp
#include <Arduino.h>
#include <WiFi.h>
#include "secrets.h"       // WIFI_SSID, WIFI_PASS, DEVICE_TOKEN (gitignored)
#include "config.h"        // CONFIG_ENDPOINT
#include "ConfigManager.h"

ConfigManager configMgr(CONFIG_ENDPOINT, DEVICE_TOKEN);
ConfigManager::DeviceConfig activeConfig;

void connectWifi() {
    WiFi.begin(WIFI_SSID, WIFI_PASS);
    Serial.print("[WiFi] Connecting");
    while (WiFi.status() != WL_CONNECTED) { delay(500); Serial.print("."); }
    Serial.printf("\n[WiFi] Connected: %s\n", WiFi.localIP().toString().c_str());
}

void setup() {
    Serial.begin(115200);
    connectWifi();
    activeConfig.pollingIntervalSec = 60; // Safe default
    configMgr.fetchAndApply(activeConfig);
}

void loop() {
    static unsigned long lastFetch = 0;
    unsigned long now = millis();
    if (now - lastFetch >= (unsigned long)activeConfig.pollingIntervalSec * 1000) {
        lastFetch = now;
        if (!configMgr.fetchAndApply(activeConfig)) {
            Serial.println("[Config] Fetch failed; using last-known config.");
        }
    }
    digitalWrite(LED_BUILTIN, activeConfig.ledEnabled ? HIGH : LOW);
    delay(1000);
}
```

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

### ESP32 Main Application Logic

Source: https://github.com/ahliweb/awcms/wiki/AGENTS

Sets up WiFi connection, initializes the ConfigManager, and periodically fetches and applies device configuration. Handles configuration fetch failures by using the last-known configuration. Controls the built-in LED based on the active configuration.

```cpp
#include <Arduino.h>
#include <WiFi.h>
#include "secrets.h"       // WIFI_SSID, WIFI_PASS, DEVICE_TOKEN (gitignored)
#include "config.h"        // CONFIG_ENDPOINT
#include "ConfigManager.h"

ConfigManager configMgr(CONFIG_ENDPOINT, DEVICE_TOKEN);
ConfigManager::DeviceConfig activeConfig;

void connectWifi() {
    WiFi.begin(WIFI_SSID, WIFI_PASS);
    Serial.print("[WiFi] Connecting");
    while (WiFi.status() != WL_CONNECTED) { delay(500); Serial.print("."); }
    Serial.printf("\n[WiFi] Connected: %s\n", WiFi.localIP().toString().c_str());
}

void setup() {
    Serial.begin(115200);
    connectWifi();
    activeConfig.pollingIntervalSec = 60; // Safe default
    configMgr.fetchAndApply(activeConfig);
}

void loop() {
    static unsigned long lastFetch = 0;
    unsigned long now = millis();
    if (now - lastFetch >= (unsigned long)activeConfig.pollingIntervalSec * 1000) {
        lastFetch = now;
        if (!configMgr.fetchAndApply(activeConfig)) {
            Serial.println("[Config] Fetch failed; using last-known config.");
        }
    }
    digitalWrite(LED_BUILTIN, activeConfig.ledEnabled ? HIGH : LOW);
    delay(1000);
}

```

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

### Initialize and Run AWCMS Mobile Application

Source: https://github.com/ahliweb/awcms/blob/main/awcms-mobile/README.md

Commands to prepare the Flutter environment, install dependencies, and launch the application. This process assumes the user is located in the root directory and requires a valid .env file based on the provided example.

```bash
cd awcms-mobile/primary
flutter pub get
cp .env.example .env
flutter run
```

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

### Install Project Dependencies (Package Managers)

Source: https://github.com/ahliweb/awcms/blob/main/awcms/src/templates/flowbiteadminastro/README.md

Installs project dependencies using common package managers like pnpm, npm, or yarn. Ensure Node.js and a package manager are installed before running these commands.

```sh
pnpm install
# or
npm install
# or
yarn
```

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

### Install Workspace Dependencies

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/environment-bootstrap.md

Commands to install dependencies across all maintained workspaces in the AWCMS ecosystem.

```bash
cd awcms && npm install
cd ../awcms-public/primary && npm install
cd ../smandapbun && npm install
cd ../../awcms-edge && npm install
cd ../awcms-mcp && npm install
cd ../packages/awcms-shared && npm install
```

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

### Start Worker on Localhost

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/edge-functions.md

Use this command to start the Worker specifically on `127.0.0.1:8787`. This is useful for testing local network configurations.

```bash
npm run dev:local
```

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

### Initialize Admin Supabase Client

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/api-usage.md

Import the pre-configured admin client to ensure correct header injection and storage guards.

```javascript
import { supabase } from '@/lib/customSupabaseClient';
```

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

### Build Public Portal

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/ci-cd.md

Commands to check and build the Public Portal locally.

```bash
cd ../awcms-public/primary
npm run check
npm run build
```

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

### Start Local Development Server

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/edge-functions.md

Use this command to start the Worker in default local development mode. Ensure you are in the `awcms-edge/` directory.

```bash
npm run dev
```

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

### Initialize Supabase Client and Fetch Content

Source: https://github.com/ahliweb/awcms/blob/main/AGENTS.md

Configures the Supabase client using build-time environment variables and provides functions to query published blog content with mandatory tenant and status filters.

```typescript
// awcms-public/primary/src/lib/content.ts
import { createClient } from "@supabase/supabase-js";

const supabaseUrl = import.meta.env.PUBLIC_SUPABASE_URL;
const supabaseKey = import.meta.env.PUBLIC_SUPABASE_PUBLISHABLE_KEY;
const tenantId = import.meta.env.PUBLIC_TENANT_ID
  ?? import.meta.env.VITE_PUBLIC_TENANT_ID
  ?? import.meta.env.VITE_TENANT_ID;

export const supabase = createClient(supabaseUrl, supabaseKey);

export async function getPublishedBlogs() {
  const { data, error } = await supabase
    .from("blogs")
    .select("id, title, slug, summary, content, published_at, author_id")
    .eq("tenant_id", tenantId)
    .eq("status", "published")
    .is("deleted_at", null)
    .order("published_at", { ascending: false });

  if (error) throw new Error(`Failed to fetch blogs: ${error.message}`);
  return data ?? [];
}

export async function getBlogBySlug(slug: string) {
  const { data, error } = await supabase
    .from("blogs")
    .select("id, title, slug, content, published_at, author_id, summary")
    .eq("tenant_id", tenantId)
    .eq("slug", slug)
    .eq("status", "published")
    .is("deleted_at", null)
    .single();

  if (error) return null;
  return data;
}
```

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

### Install and Typecheck Shared Package

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/setup.md

Install dependencies and run type checking for the shared AWCMS package. This is typically done when changes are made to the shared package.

```bash
cd packages/awcms-shared
npm install
npm run typecheck
```

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

### Tenant Onboarding and Isolation Reference Implementation

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/context7-benchmark-playbook.md

This TypeScript code demonstrates a condensed worker route pattern for tenant provisioning. It includes permission checks, tenant creation with defaults, and inviting the first admin user with tenant-specific metadata. Ensure necessary Supabase client and admin privileges are configured.

```typescript
// Worker route pattern (condensed)
const { data: canCreate } = await caller.rpc("has_permission", {
  permission_name: "platform.tenant.create",
});

const { data: tenant } = await admin.rpc("create_tenant_with_defaults", {
  p_name: payload.name,
  p_slug: payload.slug,
  p_domain: payload.domain ?? null,
});

await admin.auth.admin.inviteUserByEmail(payload.admin_email, {
  data: { tenant_id: tenant.tenant_id, role: "admin" },
});
```

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

### Monorepo CHANGELOG Entry Example

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/versioning.md

Example of a CHANGELOG entry for a single-app release within a monorepo. The root CHANGELOG.md serves as the single source of truth for project history.

```markdown
## [Unreleased]

## [4.5.1] - 2026-03-29

Applies to: `awcms@4.5.1`

### Changed
- Documentation: aligned authority, architecture, tenancy, workflow, and module docs with the current AWCMS runtime and version references.
```

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

### AWCMS MCP Build and Start Scripts

Source: https://github.com/ahliweb/awcms/blob/main/awcms-mcp/README.md

Provides commands to compile TypeScript to JavaScript for production and to run the compiled server. Use 'npm run build' to compile and 'npm run start' to run.

```bash
npm run build
```

```bash
npm run start
```

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

### ESP32 Device Configuration HTTP GET Request

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/context7-benchmark-playbook.md

Initiates an HTTP GET request to a configuration endpoint for an ESP32 device, including an Authorization header with a device token. The code expects a 200 OK response to proceed with parsing the JSON payload and applying settings.

```cpp
http.begin(CONFIG_ENDPOINT);
http.addHeader("Authorization", String("Bearer ") + DEVICE_TOKEN);
const int code = http.GET();
if (code == 200) {
  // parse json, apply settings, persist
}
```

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

### Build Smandapbun Portal

Source: https://github.com/ahliweb/awcms/blob/main/docs/dev/ci-cd.md

Commands to check, lint, and build the Smandapbun portal locally.

```bash
cd ../smandapbun
npm run check
npm run lint
npm run build
```

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

### Preview Astro Project Build

Source: https://github.com/ahliweb/awcms/blob/main/awcms/src/templates/flowbiteadminastro/README.md

Starts a local web server to preview the generated production build of the Astro project. This is useful for testing the final output before deployment.

```sh
pnpm run preview
```

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

### POST /webhooks/public-rebuild/smandapbun

Source: https://github.com/ahliweb/awcms/blob/main/awcms-edge/README.md

Optional secret-based route for database-trigger or webhook setups to initiate a rebuild.

```APIDOC
## POST /webhooks/public-rebuild/smandapbun

### Description
Optional secret-based route for database-trigger or webhook setups.

### Method
POST

### Endpoint
/webhooks/public-rebuild/smandapbun

### Parameters
#### Headers
- **x-awcms-rebuild-secret** (string) - Required - Secret key for authentication
```