References

References are Flint's dependency declaration layer. A Flint declares the external codebases and other Flints it needs without storing machine-specific paths in version control.

flint.toml declares what the Flint needs. .flint/references.json records where those items live on this machine. This split keeps the Flint portable and keeps local execution possible.

Declaration in flint.toml

References live under [references] in flint.toml. Flint supports three lists: codebases, flints, and bundles.

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

A codebase declaration names one source tree outside this Flint. A Flint declaration names one other Flint. A bundle declaration names one export folder of another Flint, in the form <Flint Name>/<Bundle Name>. Its source value must be "flint".

Declare codebases and Flints with the CLI. Declare bundles by hand in flint.toml: no command adds them. A Tinderbox can also write codebase and Flint references into its members (see Using Tinderbox). Names match without regard to letter case.

Codebase References

A codebase reference points at a local source tree outside the current Flint. Use one when the Flint needs to read an external repository without cloning or owning it.

flint reference codebase "Flint" ~/dev/flint

The command declares the reference and records the local path for this machine. Then run flint sync to complete the setup.

Flint References

A Flint reference points at another Flint on this machine. Use one when the Flint needs to read the Mesh of another Flint.

flint reference flint "Research Hub"

The command declares the reference only. flint sync fulfils it from the roster of this machine. The other Flint must be in the roster: run flint register in its folder when it is not. See The Roster.

Bundle References

A bundle reference points at one export folder of another Flint. It copies no content. It resolves to the folder Exports/(Bundle) <Bundle Name>/ of the producing Flint.

Declare the bundle by hand in flint.toml, then run flint sync. Sync fulfils it when the producing Flint is in the roster of this machine and holds the bundle folder.

Fulfilment on This Machine

Local fulfilment lives in .flint/references.json. The file is local to this machine. The managed block of .gitignore ignores .flint/, so Git does not track it.

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

Each entry records a name, a local path, and an optional fulfilment timestamp. When the file is not valid JSON, a command that reads it stops. The error names the file, the line, and the column.

Codebase references need manual fulfilment on each new machine:

flint fulfill codebase "Flint" ~/dev/flint
flint fulfill codebase --all

The first form records the path of one declared codebase. You can also give the path with --target <path>. When the path does not exist, the command warns and records the path. When the name has no declaration, the command refuses.

The --all form prompts for each unfulfilled codebase path in turn. Press Enter to skip one. It needs an interactive terminal. Flint references and bundle references fulfil automatically during sync, so flint fulfill accepts only the type codebase.

List the state of each reference:

flint reference list

The list shows codebase and Flint references with their state: fulfilled, unfulfilled, or fulfilled with a missing path. It does not show bundle references. For unfulfilled codebases, it names flint fulfill codebase --all. For unfulfilled Flints, it says that the next sync fulfils them.

Remove a declaration:

flint reference remove "Flint"

The command removes each declaration with that name from the three lists, bundles included. The next sync removes the local fulfilment that has no declaration left.

Resolving a Path

flint resolve prints the local path of a fulfilled reference:

flint resolve codebase "Flint"
flint resolve flint "Research Hub"
flint resolve bundle "Research Hub/Guide"

Resolving a codebase also lists its Git worktrees. An unfulfilled reference is a refusal: it names flint reference list as the next command. --json prints one JSON value.

flint resolve source "Research Hub/Guide" prints the path of a bundle that sync copied into Sources/Bundles/ of this Flint. See Sources.

flint resolve also resolves entity references and shard packages. See flint resolve.

Worktrees

flint worktree manages Git worktrees inside a codebase reference. It needs a fulfilled codebase reference.

flint worktree list "Flint"
flint worktree add "Flint" my-feature
flint worktree remove "Flint" my-feature

The add command creates one branch named <machine-name>-wt-<suffix>. It checks the branch out in a sibling folder named <repo>-wt-<suffix>. It copies each .env and .env.* file of the repository into the new worktree. The remove command accepts a branch, a worktree path, or the bare suffix. flint worktree list accepts --json. Set the machine prefix with flint config machine-name <name>.

What Sync Does

flint sync converges the references of the Flint. See Sync.

For references, sync does the following:

• It fulfils each declared Flint reference from the roster of this machine.
• It fulfils each declared bundle reference from the bundle folder of the producing Flint.
• It re-resolves each broken Flint or bundle path, so a moved target heals.
• It removes each local fulfilment that has no declaration left.
• It reports each codebase reference that has no path yet, with flint fulfill codebase <name> <path> as the next command.
• It reports each codebase reference whose path does not exist, with the same next command.
• It reports each Flint or bundle whose target is absent from this machine, without failing the run.
• It writes one marker note per declared reference under Mesh/Metadata/References/.

References vs Sources

Use a reference when the agent only needs a stable pointer to something external. Use a source when the agent needs a copied local snapshot inside the Flint itself. See Sources.

In short:

• references point
• sources copy

Related

• Sync
• Sources
• The Roster
• Using Tinderbox