# Sandbox Resource Constraints

## Environment Limits

- **RAM**: 512MB total
- **OS + Python baseline**: ~60–80MB
- **Usable working budget**: ~430–450MB

This sandbox is NOT a full compute environment. Certain operations are too heavy and
will cause OOM crashes. Read this before using any skill that touches LibreOffice,
Node.js, or image processing.

---

## 🔴 High-Risk Operations — Avoid or Mitigate

| Operation | Approx. RAM | Appears In | Mitigation |
|---|---|---|---|
| LibreOffice (`soffice`) startup | 300–500MB | PPTX, DOCX, XLSX | Avoid where possible; **never** run concurrently with Node.js |
| Node.js + large npm packages | 100–300MB | PPTX, DOCX | Always cap: `node --max-old-space-size=200 script.js` |
| `react-icons` + `sharp` (icon pipeline) | 150–200MB | PPTX | Replace with `cairosvg` (Python, ~20MB) |
| `pdf2image` OCR (all pages in RAM) | Scales with pages | PDF | Process one page at a time; warn user for large PDFs |
| `pandas` loading a large file whole | Scales with file | XLSX, PDF | Use `read_only=True`, `usecols`, or chunked reads |

---

## Rules

1. **Never run LibreOffice and Node.js at the same time.** Together they will exceed 512MB.
2. **Always cap Node.js heap**: `node --max-old-space-size=200 script.js`
3. **Skip LibreOffice visual QA** — use `markitdown` content QA instead; ask the user to visually verify after download.
4. **LibreOffice for formula recalc (XLSX)** is the hardest to avoid. If needed, shut down all other processes first and run it alone.
5. **OCR large PDFs** one page at a time — never load all pages into memory simultaneously.
6. **Prefer Python-native libraries** over Node.js or LibreOffice equivalents wherever possible.

---

## ✅ What Works Comfortably Within 512MB

- Python XML manipulation (PPTX/DOCX unpack → edit → pack)
- `markitdown` text extraction
- `pypdf`, `pdfplumber`, `reportlab` (pure Python PDF tools)
- `openpyxl`, `pandas` on reasonably sized files (<10MB)
- `cairosvg` for SVG → PNG conversion
- All file I/O and shell scripting

---

## When to Warn the User

Proactively set expectations when:
- The user provides a large input file (>5MB) to any skill
- A task requires LibreOffice (especially XLSX formula recalc — flag that it may be slow or fail)
- A task would benefit from visual QA that we're skipping due to memory constraints

---

## Placement Note

This file belongs at `/home/sandbox/skills/CONSTRAINTS.md` so it is discovered
automatically alongside all skill SKILL.md files before any sandbox task begins.
It should be consulted before executing any skill that involves LibreOffice, Node.js,
or large file processing.

---

## Rules File Compliance (Pre-Task Mandatory Check)

Before executing **any** sandbox task — including simple bash commands, file ops, or API calls — check the active working directory for project-level rules files:

| Filename | Common Source |
|---|---|
| `CLAUDE.md` | Anthropic Claude projects |
| `agents.md` | Custom agent instructions |
| `.rules` | Generic rules convention |
| `.cursorrules` | Cursor IDE projects |
| `AGENTS.md` | OpenAI Codex / agent frameworks |

### How to Check

```bash
for f in CLAUDE.md agents.md AGENTS.md .rules .cursorrules; do
  [ -f "$f" ] && echo "FOUND: $f" && cat "$f"
done
```

### Compliance Rules

1. **If a rules file is found** — read it fully before proceeding. Treat its instructions as authoritative for the task scope.
2. **If rules conflict with the system prompt** — surface the conflict to the user before acting.
3. **If no rules file is found** — proceed normally.
4. **Never skip this check** — even for one-liners or "quick" tasks.

### Placement Note

This section belongs in `/home/sandbox/skills/CONSTRAINTS.md` so it is discovered automatically alongside all SKILL.md files before any sandbox task begins.

