Configuration Reference

This page reflects the current workspace and local-state model implemented in packages/flint/src/types.ts, mesh-config.ts, global-config.ts, and the registry/reference modules.

The Big Picture

Flint configuration is easier to understand if you separate it into three layers:

committed human-edited declaration
committed machine-managed workspace identity
local machine fulfillment and runtime state

That split is one of the reasons a Flint can be portable without becoming vague. The workspace can declare what it is and what it needs, while each machine fills in its own paths and live state.

Main Files

File	Location	Purpose	Edit
`flint.toml`	Flint root	Human-edited workspace declaration	yes
`flint.json`	Flint root	Machine-managed workspace state tracked in git	usually no
`.flint/references.json`	`.flint/`	Local fulfillment for codebase and Flint references	no
`.flint/lattices.json`	`.flint/`	Local fulfillment for lattices	no
`.flint/sessions/*.json`	`.flint/`	Agent session state	no
`flint-hooks.toml`	Flint root	Runtime hook configuration	yes, if using runtime
`~/.nuucognition/flint/config.toml`	global	Global Flint configuration	yes
`~/.nuucognition/flint/registry.json`	global	Local Flint registry	usually no

`flint.toml`

flint.toml is the main declaration file for a workspace. It describes the environment Flint should materialize.

Current high-level shape:

[flint]
name = "My Project"
description = "Example workspace"

[shards]
projects = { source = "NUU-Cognition/shard-projects" }

[exports]
required = [
  { name = "Guide", file = "Guide.md", mode = "mesh" },
]

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

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

[references]
codebases = [
  { name = "Flint" },
]
flints = [
  { name = "Research Hub" },
]

[lattices]
references = [
  { name = "customer_data" },
]

[server]
port = 7433

`[flint]`

Workspace identity fields:

name
type
tags
description
org

`[shards]`

This is where the workspace declares the cognitive programs available to agents.

Recommended current form:

[shards]
projects = { source = "NUU-Cognition/shard-projects" }
local = { source = "path:./Shards/(Dev) Local", mode = "dev", version = "1.2.0" }

Supported fields on each shard declaration:

source
mode
version

`[exports]`

Stores export declarations under required.

Each export includes:

name
file
mode
optional depth

`[sources]`

Current source fields:

repositories
meshexports

`[workspace]`

Current workspace field:

repositories

`[references]`

Current reference fields:

codebases
flints

Each declaration currently only needs a name.

`[lattices]`

Current lattice field:

references

`[carve]`

The current type model also includes:

pool
namespace

`[server]`

Current public field:

port

`flint.json`

flint.json is tracked in git and stores machine-managed state that should travel with the workspace.

Current fields include:

version
id
type
created
migrations
org

Unlike .flint/, this file is intended to remain portable.

Local Fulfillment and Runtime State

`.flint/references.json`

Stores local fulfillment for references.

Current shape:

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

Each fulfillment records name, path, and fulfilled.

`.flint/lattices.json`

Stores local lattice connections with:

name
path
lang
fulfilled

`.flint/sessions/*.json`

Stores headless agent session state, including status, runs, interface state, and questions.

Global Config

The global config currently supports:

mode
[open].apps

Example:

mode = "production"

[open]
apps = ["obsidian"]

This file controls user-level preferences, not workspace declaration.

Registry File

The global registry stores:

Flint name
absolute path
optional tags
optional description
known export names

The registry is how Flint resolves named workspaces locally for commands such as list, Flint references, and source mesh exports.

On this page