Core Concepts

This guide explains the ideas that make Flint feel coherent instead of arbitrary. If Quick Start showed you what to do, this page explains why the workspace is shaped the way it is.

1. A Flint Is One Bounded Area of Work

The first concept to internalize is that a Flint is intentionally bounded.

It is not “all my notes forever.” It is not “every repo I touch.” It is one workspace for one coherent domain of work.

That might be:

• a product or system
• a research area
• a client engagement
• a documentation program
• a long-running project with a clear subject boundary

This boundary is useful because it keeps the workspace understandable. Both humans and agents can grasp a Flint much faster than they can grasp an unbounded vault.

2. Mesh Is the Durable Core

Mesh/ is where the workspace’s durable understanding lives.

If you are unsure where something belongs, ask a simple question:

Is this my actual thinking, planning, interpretation, or authored explanation?

If the answer is yes, it probably belongs in Mesh/.

That includes:

• plans
• task notes
• design notes
• reference notes
• synthesis documents
• reports
• system-level workspace notes

Mesh is not just a storage area. It is the layer Flint treats as most important.

Features that depend heavily on Mesh include:

• export builds
• runtime file watching
• shard workflows
• init-note driven agent sessions

3. flint.toml Describes Intent

Flint separates the workspace into two broad layers:

• what the workspace declares it should know about
• what is fulfilled or generated locally on this machine

flint.toml is the declaration layer. It says:

• which shards should be installed
• which codebases or Flints are referenced
• which sources should be pulled in
• which exports should exist
• which workspace repos should be managed
• which lattices are connected

That is why Flint feels different from a normal note vault. The workspace is not only content; it is also a declaration of relationships.

With shards, that declaration also does something more specific: it defines which cognitive programs are available for an agent to execute inside this Flint.

4. .flint/ Holds Local State

Some things should not be committed as portable workspace truth, because they are local to one machine or one runtime.

That is what .flint/ is for.

Important examples include:

• .flint/references.json for fulfilled codebase and Flint references
• .flint/lattices.json for fulfilled lattice connections
• .flint/sessions/*.json for agent session state
• .flint/sync.json for sync bookkeeping

This is one of Flint’s most important design choices. It lets the workspace say “I depend on X” without hardcoding “and X is at this exact path on one particular machine.”

5. Declarations and Fulfillment Are Different

This distinction shows up everywhere in the system.

Declaring a reference

In flint.toml, you say that the Flint depends on a codebase named Flint.

Fulfilling a reference

In .flint/references.json, the local machine records where that codebase actually lives on disk.

That same pattern appears again with lattices and some sync-managed relationships. Once you notice it, Flint becomes much easier to reason about.

6. Sources, References, and Workspace Repositories Are Not the Same

This is the place where many readers get tangled up, so it is worth being explicit.

References point outward

A reference gives the Flint a stable name for something external.

Examples:

• a codebase you want to inspect
• another Flint you want to point at

References are about identity and resolution.

Sources copy material inward

A source brings external material into the workspace in a read-only form.

Examples:

• a stripped reference copy of a repo in Sources/Repos/
• a sourced mesh export from another Flint in Sources/Flints/

Sources are about ingesting context.

Workspace repositories live inside the workspace

A workspace repo is not just a pointer and not just a reference copy. It is an active clone that belongs inside the Flint’s own working surface.

Workspace repos are about local active work.

If you keep these three roles separate in your head, many of Flint’s commands stop feeling redundant.

7. Exports Turn Notes Into Built Artifacts

An export is Flint’s way of saying, “this note graph should become a shareable output.”

The export flow looks like this:

1. mark a Mesh note as export-eligible with #export
2. declare it through flint export scan or flint export add
3. build it into Exports/

The export builder does real work:

• it follows the note graph from the declared root
• it rewrites links
• it expands embeds
• it copies referenced media
• it writes a manifest

So exports are not just copied markdown files. They are built artifacts.

8. Shards Are Cognitive Programs

Shards are one of the central ideas in Flint. They are not just “extensions” in the generic sense. They are cognitive programs: structured packages that tell an agent how to think and act inside the workspace.

A shard usually contains:

• init instructions
• skills
• workflows
• templates
• knowledge files
• helper scripts

When an agent loads a shard, it is effectively loading a program for cognition and action. Flint supplies the environment that makes that program useful:

• Mesh gives it durable notes to read and write
• references and sources give it access to real external context
• the init note tells it how this workspace is organized
• the CLI gives it commands for reconciliation and inspection

That is why Flint and shards belong together. Flint is the execution environment; shards are the executable cognitive patterns.

9. Agents Are Part of the Workspace, Not Outside It

Flint treats headless agent work as part of the workspace model.

Agent sessions have:

• a local session file
• statuses
• runs
• questions
• interface state
• results

That means AI work is not just “something that happened in a terminal once.” It can become inspectable workspace state.

10. Runtime and Server Are Optional Layers

The runtime and server are important, but they are not the center of Flint.

• the runtime watches files and executes hooks
• the server provides a local HTTP control plane

If you do not need automation, you can still use Flint effectively without leaning on them. They are optional power layers, not the base product.

11. Flint Is Source-First

The healthiest Flint workflow is one where notes stay close to real source material.

That means:

• docs point to real codebases
• plans mention actual systems
• sourced materials stay distinguishable from your own interpretation
• exports are built from authored Mesh notes rather than replacing them

This source-first discipline is what keeps a Flint from turning into a fantasy model of reality.

The One-Sentence Mental Model

If you want to remember just one thing, remember this:

Flint is a bounded workspace where Mesh/ holds the durable thinking, flint.toml declares the relationships, and shards give agents cognitive programs to execute inside that environment.