# Hugging Face Space Deployment Guidelines & Best Practices

## 1. Deployment Configuration

### Target Space
- **Profile:** `Leon4gr45`  
- **Space:** `builder`  
- **Full Identifier:** `Leon4gr45/builder`  
- **Frontend Port:** `7860` (mandatory for all Hugging Face Spaces)

### Deployment Method
We use the **Docker SDK** for flexibility, utilizing a standard `Dockerfile` configured to run Next.js standalone on port `7860`.

### HF Token
- The token is read from the environment variable (never hardcode it).

### Required Files
- `Dockerfile` (binds the app to port `7860`)
- `README.md` (includes Hugging Face YAML frontmatter)
- `.hfignore` (excludes unnecessary files to prevent repository limit issues)
- `Agent.md` (this file, detailing current practices)

---

## 2. API Exposure and Documentation

### Mandatory Endpoints
The following endpoints must be accessible publicly without any redirection/authentication block (configured in Next.js middleware):

- **`/health`**
  - **Method:** GET
  - **Purpose:** Health check returning HTTP 200 once Next.js server is ready. Necessary for Hugging Face to transition the Space status to *running*.
  - **Response:**
    ```json
    {
      "ok": true,
      "name": "osw-studio",
      "version": "1.84.0",
      "mode": "browser",
      "timestamp": "2026-07-16T12:00:00.000Z"
    }
    ```

- **`/api-docs`**
  - **Method:** GET
  - **Purpose:** Serve documentation or routes specification of the available APIs.
  - **Response:** JSON list of the endpoints.

### Functional Endpoints

All the available functional endpoints listed in `/health` under the endpoint groups (like `auth`, `public`, `analytics`, etc.) are supported.

---

## 3. Tricks & Troubleshooting

- **Large Upload / Storage Limit (Max: 1 GB):**
  - Since standard `hf upload` without exclusions attempts to scan/upload local `node_modules` and `.next` build files, it can hit the 1 GB storage limit or fail on string limit in JS wrapper.
  - **Fix:** Always explicitly set up `.hfignore` or use `--exclude` to ignore large local directories such as `node_modules/*`, `.next/*`, `.git/*`.
  - Deployment Command:
    ```bash
    hf upload Leon4gr45/builder . --repo-type=space --token=$HF_TOKEN --exclude="node_modules/*" --exclude=".next/*" --exclude=".git/*"
    ```

- **Middleware Matcher Exclusion:**
  - Standard Next.js matcher should explicitly allow `/health` and `/api-docs` so Hugging Face load balancers can reach them without running into authentication loops/redirects.

# Force rebuild comment 1