Configuration Reference

This page documents the configuration files and the state files of a Flint.

The Three Layers

Flint configuration separates into three layers.

• The committed declaration that a person edits (flint.toml).
• The committed machine-managed identity of the Flint (flint.json).
• The local fulfillment and runtime state of this machine (.flint/).

A Flint declares what it is and what it needs. Each machine fills in its own paths and live state.

Main Files

flint.toml

flint.toml is the main declaration file for a Flint. It describes the environment that Flint materializes.

[flint]
name = "My Notes"
type = "flint"
preset = "default"
visibility = "private"
tags = ["research"]
description = "Example Flint"
org = "nuucognition"

[shards]
flint = { source = "@nuucognition/flint@0.3.5", git = "NUU-Cognition/shard-flint" }
projects = { git = "NUU-Cognition/shard-projects" }
notepad = "@nuucognition/notepad@^1.1"
knap = { source = "@nuucognition/knap", git = "NUU-Cognition/shard-knap", from = "source" }

[sources]
repositories = [
  { name = "Design System", url = "https://github.com/org/design-system" },
]
bundles = [
  { source = "flint", name = "Research Hub/Guide" },
]

[workspace]
repositories = [
  { name = "App", url = "https://github.com/me/app.git" },
]

[references]
codebases = [
  { name = "Flint" },
]
flints = [
  { name = "Research Hub" },
]
bundles = [
  { source = "flint", name = "Research Hub/Guide" },
]

[orbh]
default = ["claude/o55h", "codex/a6h"]

[obsidian.applied.appearance]
enabledCssSnippets = { add = ["blockquote-tables"] }

[modules]
dms = "@nuucognition/module/dms"
crons = "@nuucognition/crons"

[flint]

Identity fields of the Flint:

flint.json#org holds the org of the Flint with its id and its slug. flint org set <org> writes both. flint org show shows both.

The [flint] table is the only section that Flint validates strictly at whole-file parse time. Feature-owned sections are tolerant: malformed entries stay for drift reporting instead of rejecting the whole file, and unknown sections and keys pass through.

[shards]

[shards] declares the cognitive programs of the Flint. Each key is the alias of one shard in this Flint. See Shards.

A string value is a package spec: @org/name[@range][#place]. A table value holds these fields:

Every other field stays as it is and changes no meaning. flint shard install with a source writes a record. flint shard install --from-git <owner/repo> writes <alias> = { source = "<spec>", git = "<owner/repo>" } for a package the registry knows (the spec carries @<tag> when the build hash matches a registry version), and <alias> = { git = "<owner/repo>" } only for an unregistered package or when the registry does not answer. flint shard install with no argument makes the lock match the records.

The shard registry serves versions of most NUU Cognition shards (Flint 0.4.0, Orbh 0.5.0, Knap 1.2.0, and more). An install by package spec resolves its range against the registry. With no range, it takes the latest release. A few older records still have no shard id. Install one of those with flint shard install --from-git NUU-Cognition/shard-<slug>.

A Flint of 0.6.0 has the old lists installed, dev-remote, and dev-local. flint migrate run rewrites them to records. Until then, flint shard list, status, and start read them with a notice, and every shard write is refused.

[sources]

[sources] declares read-only material that flint sync fetches. See Sources.

A bundle entry names a bundle of a producer Flint. flint sync copies Exports/(Bundle) <Bundle Name>/ of the producer Flint into Sources/Bundles/<Bundle Name>/. No command adds or removes a bundle source entry. A person edits it by hand.

[workspace]

[workspace] declares full-cloned working repos. See Workspace.

[references]

[references] declares names that resolve to paths on this machine. See References.

flint reference codebase <name> <path> writes the declaration and records the path in .flint/references.json. flint reference flint <name> and flint reference remove <name> write the declaration only. flint fulfill records a local path for a codebase reference. flint sync fulfills the references.

[plates]

[plates] holds the plate declarations of Steel, keyed by plate name. A declaration can hold title, source, version, path, and repo.

[server]

[server] holds settings of the Flint server of this Flint.

[orbh]

Current field:

• default: the Flint layer of the default target list of Orbh. It is a list of one or more runtime/profile targets, in order.

[orbh]
default = ["codex/a6h", "claude/o55h"]

A command of Orbh with no target (flint orbh i, flint orbh launch "<prompt>", flint orbh request "<prompt>") in this Flint starts the first available target of this list. The Flint layer replaces the machine layer and the shipped list; it does not merge with them. flint orbh profiles default set --flint <target>... writes the key, and flint orbh profiles default unset --flint removes it. A value that is not a list of targets stops each launch with no target in this Flint. The refusal names flint orbh profiles default unset --flint -p <the Flint root>. See Agent Sessions > The Default Target List.

[obsidian]

[obsidian] holds only applied: the Flint layer of applied settings. See Using Obsidian.

[obsidian.applied.appearance]
cssTheme = "Baseline"
enabledCssSnippets = { add = ["blockquote-tables"], remove = ["old-snippet"] }

[obsidian.applied.app]
showLineNumber = true

The tables under [obsidian.applied] are appearance and app. A string, a boolean, or a number sets one key. { add = [...] } and { remove = [...] } change a list. { set = [...] } sets a whole list. The Flint layer wins over the machine layer and the release layer. flint obsidian applied set <file>.<key> <value> and flint obsidian applied unset <file>.<key> write this table.

[modules]

[modules] holds one record for each module of the Flint. A module is a package of the kind module, as a shard is a package of the kind shard: it has a source, a version, a lock record, and a build in Modules/. The pages Module - … of these docs use the word "module" for an area of Flint; that is a different meaning. See Modules, Crons, and DMs and Write a Module.

[modules]
dms = "@nuucognition/module/dms"                                 # A package spec
crons = "@nuucognition/crons"                                    # The short form @<org>/<slug> names the same package
hello = { source = "@/hello", from = "source" }                  # Built from its source in this Flint
bot = { source = "@acme/bot", git = "acme/module-bot" }          # A package with its Git location

flint module install, uninstall, and build write the records. flint sync makes the builds match the lock, runs the plan of each module, and makes the objects of the modules on this machine (cron schedules, stations). When a record goes away, sync pauses the objects of its module; it never deletes them. The objects are in the Orb store .orb/ of each machine.

A table [modules.<id>] with no source key is a legacy declaration of the built-in modules of the 0.7.0 pre-releases. Sync never reads it as a record, and no migration moves it. A legacy table does not make the Flint behind. flint module list, the sync report, and flint doctor name it with a step by hand and the next command flint module install @nuucognition/module/<id>. To replace [modules.crons] or [modules.dms]: move its keys, without enabled, to Modules/Crons.settings.toml or Modules/DMs.settings.toml (each [modules.crons.schedules.<name>] becomes [schedules.<name>]), remove the table, then run flint module install @nuucognition/module/<id> and flint sync. When the table has enabled = false, do not install the module.

The Settings Files

The settings of a module in this Flint are in Modules/<Name>.settings.toml. <Name> is the folder of the build: Modules/Crons.settings.toml for the record crons, Modules/DMs.settings.toml for the record dms. Git tracks the file. A build, an install, and an update never change it, and flint module uninstall keeps it. The manifest of the module names its keys. A settings file that does not parse fails the plan of its module, and sync does not reconcile that module. After a change, run flint sync.

The Settings of the Module crons

machine = "katana"

[schedules.morning-brief]
expr   = "0 7 * * 1-5"
prompt = "Write the brief of the day."

The keys of [schedules.<name>]:

A value of machine with the UUID shape is compared with the machine id. Each other value is compared with the machine slug (machine-slug of the NUU config). Only the owner machine makes and fires the schedule. Flint does not check that two machines have different slugs, so a slug owner is safe only when each machine that syncs the Flint has a different machine slug. A machine id names one exact machine: nuu computer id prints it. flint module crons own [<name>] writes the slug of this machine. A schedule that does not parse is an issue, and sync keeps its object as it is. A wrong type of machine, target, or schedules fails the plan, and sync changes no schedule. An unknown key is an issue, and the module ignores it.

The Settings of the Module dms

Each key is optional. With no settings file, the module serves DMs with the defaults.

A value that is not valid fails the plan, and sync keeps the station dm as it is.

flint.json

flint.json holds machine-managed state that travels with the Flint in git. Only flint create makes it. A writer never recreates a lost one.

Each lock record in shards holds the spec, the package name, the alias, the shorthand, the name, the address, the version, the state, the Git facts of the fetch (resolved: repo, ref, sha), the package hash and its files, the payloads, the folders, the setup state, the migrations, and the pending migration steps. The state is published (a registry version with its tag and hash), snapshot (a build of a commit with its sha), or edited (a build of an edited source). The request and the answer of the registry are local facts in .flint/shards.json.

These commands write the Obsidian pin: flint create writes the recommended release for each new Flint, flint obsidian update moves the pin to the recommended release or to --to, a full backup restore writes the pin of the backup, and the conversion of a legacy payload writes a pin only when the Flint has none. flint sync never changes the pin.

Local State

Git ignores .flint/. Each machine has its own.

.flint/local.json

.flint/local.json is the local version record. It holds the Flint Version of the local state of this machine and the ledger of the local migrations. flint create writes it, so a new Flint is current. A current Flint that arrives from Git gets it at its first flint sync or flint git sync. Before that, flint sync --dry-run and flint plan show Would initialize the local state at <version>, and flint doctor counts it as one change to apply (Next: flint sync); no migration is needed.

{
  "version": "0.7.0",
  "migrations": {
    "flint-0.6.0-to-0.7.0-l1": "2026-10-04T16:57:07.681Z"
  }
}

.flint/references.json

.flint/references.json holds the local fulfillment of the [references] declarations.

{
  "version": 2,
  "codebases": [],
  "flints": [],
  "bundles": []
}

Each fulfillment records name, path, and optional fulfilled (the time of fulfillment). Names match without case.

.flint/shards.json

.flint/shards.json holds the local record of each shard, keyed by shard id. Each entry holds the setup state, the Git presence of a source (branch, sha, ahead, behind, dirty, last fetch time), the walk of this machine for the request (where the files came from and what the registry said), and the install and build times. It is not committed.

.flint/modules.json

.flint/modules.json holds the local record of each module, keyed by module id: the walk of this machine for the request (where the files came from and what the registry said), and the install and build times. The data folder of a module is .flint/modules/<name>/: only that module writes there. It is not committed.

.flint/sync.json

.flint/sync.json holds the last sync timestamp.

{
  "synced": "2026-07-07T00:00:00.000Z"
}

Env Files

Three files at the Flint root hold the env values of the Flint. The syntax is dotenv: NAME=VALUE lines, # comment lines, an optional export prefix, single quotes (literal), and double quotes (with the escapes \n, \r, \t, \", and \\).

# flint.env.local: the values of this machine (Git ignores this file)
DISCORD_TOKEN="…"

Each module process gets every value. A name that starts with FLINT_ is refused: only Flint sets those values. A line that does not parse is an issue with its line number, and it is not loaded. When flint.env.example names a value that no env file sets, flint module status and flint sync show one notice; the exit code does not change. An agent can read the values from flint.env.local and flint.env at the Flint root; Orbh does not put them into a session.

The managed block of .gitignore always ignores flint.env and flint.env.local. When the Flint has Modules/ or [modules], it also ignores Modules/(Source Remote) */, Modules/**/node_modules/, Modules/**/.venv/, and Modules/**/__pycache__/.

The NUU Config

~/.nuucognition/config.toml (or $NUU_HOME/config.toml) is the NUU config. Every NUU CLI reads it. Flint reads and writes these keys:

flint setup --machine-proper-name "<name>" and flint rename "<name>" in the Computer Flint change machine-display-name and rename the Computer Flint too. See The Computer Flint > Rename the Machine.

flint config org unset makes new Flints local again. A NUU account and an org are optional. Flint works with no NUU account and no org.

The Orbh Settings

~/.nuucognition/orbh/settings.json holds the Orbh settings of this machine. The key defaultTargets is the machine layer of the default target list:

{
  "defaultTargets": ["codex/a6h", "claude/o55h"]
}

flint orbh profiles default set <target>... writes the key, flint orbh profiles default unset removes it, and step 4 of flint setup writes it when you put another target first. The Flint layer ([orbh] default in flint.toml) wins over this key. With no key, the shipped list applies: claude/o55h, then codex/a6h. The variable ORBH_SETTINGS_PATH names another settings file. See Agent Sessions > The Default Target List.

The Flint CLI Config

~/.nuucognition/flint/config.toml is the Flint CLI config of this machine. A dev build uses ~/.nuucognition/flint-dev/config.toml. The build selects the file. The code reads these keys:

flint config get <key>, flint config set <key> <value>, and flint config open act on this file. flint config set writes a dotted key as a nested table, and it keeps every other key and comment of the file. It refuses a key under obsidian. and names the command to use instead. flint config name, flint config machine-name, and flint config org write the NUU config, not this file. This file holds preferences of this machine, not the declaration of a Flint.

update-check = "on"

[obsidian]
choice = "on"
trust = "auto"

[obsidian.applied.appearance]
cssTheme = "Tokyo Night"

[orbit]
devOrigins = ["http://localhost:5173"]

The Roster Files

The roster is ~/.nuucognition/places.json: the list of Flints that this machine knows. Each row holds the path and the kind of a Flint. ~/.nuucognition/flint/registry.json is a copy of the roster: it holds the id, the name, the type, and the path. flint registry rebuild makes the copy again. flint registry check checks it without writes. See The Roster.

The roster is how Flint finds a Flint by its name: flint open, flint list, Flint references, and source bundles.

Environment Variables

The daily release check also stays off after flint config set update-check off, in a pipe, with --json, in CI, for flint update and flint setup, and on a machine that is not set up.