boxel: Skill for Claude Code

BXL engine — architecture and the invariants a change must preserve

packages/bxl is the expression engine: a vendored jq runtime (src/jqtools/), a vendored Excel formula library (src/formulajs/), and BXL's own readable syntax, linter, formatter, registry bridge, authorization and mutation subsystems (src/bxl/, src/authorization/, src/mutation/). It ships raw erasable TypeScript with .ts import specifiers — Node runs the sources directly, the host bundles them, and there is no build step to go stale.

This skill is for people changing the engine. Card authors writing formulas want packages/bxl/README.md and packages/bxl/docs/ instead — the syntax surface, the tag choice, the profile constraints as an author meets them.

Several of this package's invariants are enforced by the suite; the ones worth a skill are the ones that are not, because their violation leaves every test green while the thing under test quietly changes.

How a formula becomes a value

source ── compileReadableSyntax ──▶ canonical jq text     src/bxl/compiler/readable-syntax.ts
       (skipped when readableSyntax: false — the jq tag)
  │  Tokenizer → Parser                                   src/jqtools/parser/
  ▼
AST
  │  annotateBuiltinFilters      resolve each call against the registry
  │  compileScalarExpression     try to compile the WHOLE program to scalars
  ▼
either  compiledScalar(input)        one call, no jq machinery   src/jqtools/evaluate/compiledScalar.ts
or      evaluateWithRegistry(ast)    streaming Item iterators     src/jqtools/evaluate/evaluate.ts
  │  outputs unwrapped, then recordRuntimeOutput
  ▼
outputs[]

annotateBuiltinFilters (src/bxl/bridge/native.ts) walks the AST once and stamps each filter node with the implementation it resolved: resolvedJq if the registry has a jq-source definition at that NAME/arity, otherwise resolvedNative. A jq definition at a key permanently hides a native at the same key — in the annotator and in the evaluator both. The same pass marks each node singleOutput, which is what lets the evaluator evaluate an argument without materializing a stream.