# Spell Specification (SPELL.md)

Every spell in the Grimoire is a directory containing Bash scripts:

```
grimoire/
└── libs/
    └── openssl/
        ├── DETAILS       # Metadata: SPELL, VERSION, SOURCE_URL, etc.
        ├── DEPENDS       # Direct dependencies + sub-depends
        ├── BUILD         # Compilation script (runs inside the sandbox)
        ├── CONFIGURE     # Interactive y/n queries (consumed by ICE)
        ├── PRE_BUILD     # Optional pre-build steps
        └── INSTALL       # Optional install override
```

## DETAILS Fields

| Field | Required | Example |
|-------|----------|---------|
| `SPELL` | yes | `openssl` |
| `VERSION` | yes | `3.2.1` |
| `SOURCE` | yes | `${SPELL}-${VERSION}.tar.gz` |
| `SOURCE_URL[0]` | yes | `https://www.openssl.org/source/...` |
| `SOURCE_HASH` | yes | `sha512:abc123...` |
| `SOURCE_DIRECTORY` | yes | `${BUILD_DIRECTORY}/${SPELL}-${VERSION}` |
| `WEB_SITE` | no | `https://www.openssl.org/` |
| `ENTERED` | no | `20260317` |
| `LICENSE[0]` | yes | `Apache-2.0` |
| `SHORT` | yes | "The Open Source toolkit for SSL/TLS" |

## DEPENDS Format

```bash
# Runtime dependency
depends glibc ""

# Build-only dependency
depends pkg-config "" build

# Optional dependency (toggled via ICE)
depends zlib "--with-zlib" optional

# Sub-dependency: requires openssl to be built with ssl3
sub_depends openssl ssl3
```

## CONFIGURE Format

The Interactive Configuration Engine (ICE) intercepts `config_query` calls:

```bash
config_query OPENSSL_SSL3  "Enable SSLv3 (insecure)?" n
config_query OPENSSL_IPV6  "Enable IPv6 support?"     y
config_query OPENSSL_ASM   "Use assembly optimisations?" y
```

Answers are persisted in the Tablet (BoltDB). Subsequent casts reuse the
answers unless `--reconfigure` is passed.

## BUILD Script

The BUILD script runs inside the OverlayFS sandbox. Standard pattern:

```bash
#!/bin/bash
cd "$SOURCE_DIRECTORY" &&
./configure --prefix=/usr "$@" &&
make &&
make install
```

The sandbox's `upper` directory captures every file `make install` writes —
this becomes the Essence manifest. No `installwatch` / `LD_PRELOAD` needed.

## Spell Generation via Quill

```bash
quill new zlib
# → launches the interview wizard
# → emits DETAILS, DEPENDS, BUILD, CONFIGURE
# → auto-hashes the upstream source via the "Smart Quill" mode
```

The WebUI provides a modal form that drives the same `quill.GenerateSpell`
code path so CLI and WebUI produce identical output.