Agent reads this to understand the Projects plugin

Understanding these concepts will make everything else click.

The Mental Model

Flint is a bounded workspace - a single folder that contains everything related to one domain of thought. This boundary is intentional and powerful.

Think of a Flint as a self-contained unit of knowledge work:

• Bounded - One folder with clear edges. When you move or share it, everything travels together.
• Structured - Standard directories organize different types of content.
• Agent-friendly - AI assistants can read a single init file and understand the whole context.
• Declarative - You describe what you want in configuration files; Flint handles the details.

This is different from a file system (infinite, unstructured), a database (infinite, structured), or a wiki (can sprawl indefinitely). The boundary matters because it enables comprehensibility, portability, and focused collaboration.

The Flint Folder

A Flint is a folder with a specific structure:

(Flint) My Project/
  flint.toml           # Configuration (you edit this)
  .flint/              # Internal state (managed by Flint)
    flint.lock         # Computed state
    mesh.config.yaml   # Workspace identity
  Mesh/                # Your notes and thinking
  Plugins/             # Installed plugins
  Workspace/           # References to external resources
  Media/               # Binary assets
  Imports/             # Content from other Flints
  Exports/             # Content you share out

The folder naming convention (Flint) Name makes Flints visually distinct and sortable. The name inside flint.toml is the canonical name; the folder name follows it.

Mesh: Your Thinking Space

The Mesh/ directory is the heart of a Flint. This is where your notes live - organized not as a hierarchy but as a connected graph.

Typed Prefixes

Notes use typed prefixes to indicate their purpose:

These prefixes aren't just conventions - they enable plugins to find and operate on specific note types. A Projects plugin knows to look for (Task) files; an Increments plugin tracks (Increment) files.

The Graph

Notes connect through wikilinks: [Other Note](/other-note) creates a link, ![Embedded Content](/embedded-content) transcludes content inline. This creates a graph where ideas link to related ideas.

The graph enables:

• Navigation - Follow links between concepts
• Discovery - Find backlinks (what links to this?)
• Compilation - Resolve transclusions into complete documents for export

Think of Mesh as your external brain for this domain. Ideas go in as notes. Connections form through links. Insights emerge from the structure.

Plugins: Prompt-Based Extensions

Plugins extend what you and AI agents can do in a Flint. Unlike traditional code plugins, Flint plugins are prompt packages - collections of markdown files that provide context, skills, and templates.

A plugin contains:

Plugins/Projects/
  plugin.yaml          # Plugin metadata and version
  init-proj.md         # Context to load when using this plugin
  skills/
    sk-proj-create.md  # Repeatable task: create a task
    sk-proj-archive.md # Repeatable task: archive completed tasks
  templates/
    tmp-proj-task.md   # Document structure for tasks
  workflows/
    wkfl-proj-do.md    # Multi-step process for completing a task

Why Prompt-Based?

This approach is:

• Safe - No arbitrary code execution. Plugins are just markdown that agents interpret.
• Inspectable - You can read exactly what a plugin does.
• Portable - Works with any capable AI agent.

Loading Plugins

Plugins are installed to Plugins/ but not automatically loaded. An agent reads a plugin's init file when it needs that plugin's capabilities:

# Agent reads this to understand the Projects plugin
Plugins/Projects/init-proj.md

This on-demand loading keeps context focused. Don't load everything at session start - that wastes context window.

Plugin Components

• Init file (init-*.md) - Context that explains what the plugin does and how to use it
• Skills (skills/sk-*.md) - Repeatable tasks with clear inputs and outputs
• Templates (templates/tmp-*.md) - Document structures for creating new notes
• Workflows (workflows/wkfl-*.md) - Multi-step processes with decision points

Declaring Plugins

Plugins are declared in flint.toml:

[plugins]
required = [
  "core",
  "projects",
  "increments",
]

Running flint sync installs declared plugins and removes undeclared ones.

Mods: Environment Modifications

Mods modify how the Flint environment works. Unlike plugins (which add agent capabilities), mods configure the system itself.

Examples:

• git - Initializes git repository, manages .gitignore patterns
• claude-code - Creates CLAUDE.md for Claude Code integration

Mods can:

• Create files and directories during installation
• Run hooks during sync (onSync), init (onInit), etc.
• Maintain state in .flint/mods/

Declaring Mods

Mods are declared in flint.toml:

[mods]
required = [
  "git",
  "claude-code",
]

Workspace: External References

The Workspace/ directory links your Flint to external resources - codebases, APIs, databases, or other services that your notes reference.

Reference Files

Each reference is a markdown file in Workspace/References/:

Workspace/References/
  rf-monorepo.md       # Reference to a codebase
  rf-api.md            # Reference to an API

A reference file contains:

• Human-readable description of what this resource is
• Machine-specific path (gitignored, not committed)
• Any relevant context for agents

Declaring References

References are declared in flint.toml:

[workspace]
references = [
  { name = "Monorepo", type = "codebase" },
  { name = "API", type = "api" },
]

The declaration is portable (committed to git). The actual path is stored in .flint/workspace.toml (gitignored, machine-specific).

This separation means:

• You can clone a Flint and it knows what references it needs
• You run flint workspace fulfill to set paths on your machine
• Paths don't leak into version control

Media: Binary Assets

The Media/ directory stores binary files - images, PDFs, diagrams, and other assets that your notes reference.

Keep Media organized however makes sense for your domain. Some patterns:

• Media/screenshots/ for UI captures
• Media/diagrams/ for architecture drawings
• Media/attachments/ for general files

Media files are typically gitignored or stored in Git LFS depending on your needs.

Imports and Exports: Sharing Between Flints

Flints can share content with each other through the import/export system.

Exports

An export is a curated subset of your Mesh that you want to share. You define exports with manifest files in Exports/:

# Exports/Guide.md
---
description: User guide for Flint
depth: 1
---

This export includes the core documentation:

- [Guide - Quick Start](/guide/quick-start)
- [Guide - Core Concepts](/guide/core-concepts)
- [Guide - CLI Reference](/guide-cli-reference)

Running flint export build processes these manifests:

1. Resolves linked documents
2. Follows transclusions to the specified depth
3. Strips frontmatter
4. Rewrites wikilinks with prefixes for disambiguation
5. Outputs to Exports/Guide/

Imports

To import another Flint's export, declare it in flint.toml:

[imports]
required = [
  "NUU Flint/Guide",
]

Running flint sync pulls the export from the source Flint (which must be registered on your machine) into Imports/NUU Flint/Guide/.

Import files are prefixed E (Source Flint) Document Name.md to prevent naming collisions.

Configuration Files

flint.toml

The main configuration file. Human-editable, committed to version control.

[flint]
name = "My Project"
type = "flint"

[plugins]
required = [
  "core",
  "projects",
]

[mods]
required = [
  "git",
]

[imports]
required = [
  "NUU Flint/Guide",
]

[workspace]
references = [
  { name = "Monorepo", type = "codebase" },
]

.flint/flint.lock

Generated state file. Managed by Flint, not edited directly.

Contains:

• Lock file version
• Flint CLI version that created it
• Creation and last sync timestamps
• Installed mod versions

.flint/ Directory

The .flint/ directory stores internal state:

.flint/
  flint.lock           # Lock file
  mesh.config.yaml     # Workspace identity (ID, type, created date)
  workspace.toml       # Machine-specific paths (gitignored)
  plugins/             # Plugin installation state
  mods/                # Mod state

This directory is partially gitignored - flint.lock and mesh.config.yaml are committed; workspace.toml and plugin/mod state are not.

The Global Registry

Flint maintains a global registry at ~/.flint/ that tracks all Flints on your machine:

~/.flint/
  config.toml          # Global user preferences
  registry.json        # List of registered Flints

config.toml

Global preferences:

[open]
apps = [
  "obsidian",
]

registry.json

Tracks registered Flints by path:

{
  "version": 1,
  "flints": [
    {
      "name": "My Project",
      "path": "/Users/me/flints/(Flint) My Project",
      "type": "flint",
      "source": "local"
    }
  ]
}

The registry enables:

• flint list to show all your Flints
• Import resolution (finding source Flints for imports)

Sync: Keeping Everything in Order

The flint sync command is the reconciliation point. It ensures your Flint's actual state matches its declared configuration:

1. Bootstrap - Creates .flint/ and standard directories if missing
2. Plugins - Installs declared plugins, removes undeclared ones
3. Mods - Installs declared mods, removes undeclared ones
4. Imports - Pulls required imports from source Flints
5. Workspace - Checks that declared references have paths configured
6. Registry - Updates the global registry if the Flint moved or renamed
7. Mod Hooks - Runs onSync hooks for installed mods

Sync is idempotent - running it multiple times produces the same result. It's safe to run after any change to flint.toml.

When to Sync

• After cloning a Flint repository
• After editing flint.toml
• After pulling changes that modified flint.toml
• When something seems out of sync

Putting It Together

The Flint mental model:

1. One Flint per domain - Keep workspaces focused. When it sprawls, split it.
2. Mesh is the center - Everything else either feeds into your thinking (Imports, Workspace), flows out of it (Exports), or supports it (Media, Plugins).
3. Declare, then sync - Edit flint.toml to describe what you want, run flint sync to make it so.
4. Plugins are prompts - Safe, inspectable, portable extensions that agents interpret.
5. Agents are first-class - The system is designed for AI collaboration from the ground up.

Next Steps

• Guide - Quick Start - Create your first Flint
• Reference - CLI Commands - Complete command reference
• Guide - Plugins - Deep dive into the plugin system