firn

Use whenever editing ~/code/nixos-config (firn): packages, modules, services, host config, hooks/skills, inputs, or any "install X system-wide" request. Write interface is .bnix (compiled to .nix — never edit .nix). System switch (firn rebuild) is agent-runnable; it builds a commit snapshot (rev=HEAD), so commit your own changes first — nobody's uncommitted state blocks or leaks. NOT general Nix in other repos.

Use WHENEVER writing, editing, or debugging Beagle source in ANY project — files ending .bclj/.bcljs/.bjs/.bnix/.bgl, starting with `#lang beagle`, or anything under ~/code/beagle. Establishes the repair loop is online and functionally working BEFORE coding; the compiler is the loop's oracle and the source of truth, never a static cheat sheet. NOT for relational queries over a Beagle tree — that's codegraph.

Use when editing a Beagle source file whose UPSTREAM is the fact GRAPH (code-as-facts) — one listed in the graph-upstream registry or whose leading comment block carries `;; @upstream:graph`. Its text is a regenerable view of the Fram fact graph: author by GRAPH EDIT via the mcp__fram__* tools, never Edit/Write/MultiEdit (a PreToolUse guard refuses text edits). NOT for ordinary Beagle files or non-adopted modules.

Use when you need RELATIONAL code-intelligence over a BEAGLE source tree (.bjs/.bclj/.bnix) — scope-correct "who calls THIS x", transitive blast radius / leverage, the real call graph. The codegraph module (chartroom/) projects the AST into a Fram fact graph; Datalog derives the answer. NOT for arbitrary-language repos, plain string search, or a single-file lookup (grep wins there).

Use when BUILDING a program, app, or tool on the Fram fact engine — modeling data/logic as facts (subject predicate object) + Datalog instead of SQL/records/imperative state. Covers assert vs supersede (update), live-view queries, and Datalog derivation. Formerly named fact-authoring. NOT for one-off fact reads — just rent the store and call by-lp.