Agent reads this to understand the Projects shard

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.json           # Identity and state (managed by Flint)
  .flint/              # Internal state (gitignored)
  Mesh/                # Your notes and thinking
  Shards/              # Installed shards (agent capabilities)
  Mods/                # Installed mods (environment integrations)
  Workspace/           # References to external resources
  Media/               # Binary assets
  Imports/             # Content from other Flints
  Exports/             # Built export output
  Connections/         # References to other Flints (gitignored)
  Subflints/           # Nested Flint workspaces

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 shards to find and operate on specific note types. A Projects shard knows to look for (Task) files; an Increments shard tracks (Increment) files.

Typed artifacts use sequential numbering: (Type) NNN Name.md. Use flint helper type newnumber <Type> to get the next available number.

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.

Shards: Prompt-Based Extensions

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

A shard contains:

Shards/Projects/
  shard.yaml              # Shard manifest (version, dependencies, install entries)
  init-proj.md            # Context to load when using this shard
  skills/
    sk-proj-capture_as_task.md   # Repeatable task: capture ideas as tasks
    sk-proj-archive_tasks.md     # Repeatable task: archive completed tasks
  templates/
    tmp-proj-task.md      # Document structure for tasks
  workflows/
    wkfl-proj-create_task.md     # Multi-step process for creating tasks
    wkfl-proj-do_task.md         # Multi-step process for completing tasks
  knowledge/
    knw-proj-conventions.md      # Deep reference on project conventions
  scripts/
    newtasknum.js         # Executable utility scripts
  install/
    (Dashboard) Backlog.md       # Files installed into Mesh/

Why Prompt-Based?

This approach is:

• Safe - No arbitrary code execution in shard markdown. Agents interpret prompts.
• Inspectable - You can read exactly what a shard does.
• Portable - Works with any capable AI agent.
• Extensible - Create your own shards with flint shard create.

Loading Shards

Shards are installed to Shards/ but not automatically loaded into agent context. An agent reads a shard's init file when it needs that shard's capabilities:

# Agent reads this to understand the Projects shard
@Shards/Projects/init-proj.md

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

Shard Components

Declaring Shards

Shards are declared in flint.toml with their source:

[shards]
projects = { source = "NUU-Cognition/shard-projects" }
increments = { source = "NUU-Cognition/shard-increments" }
plan = { source = "NUU-Cognition/shard-plan" }
my-shard = { source = "path:./Shards/(Dev) My Shard", dev = true }

Running flint sync installs declared shards and warns about orphaned ones.

Mods: Environment Modifications

Mods modify how the Flint environment works. Unlike shards (which add agent capabilities), mods configure the system itself by installing files, running commands, and providing scripts.

Examples:

• claude-code - Creates CLAUDE.md and .claude/settings.json for Claude Code integration
• agents - Creates AGENTS.md for multi-agent tool integration

Mods can:

• Install files into the flint root (with template rendering)
• Run shell commands at lifecycle points (onInstall, onSync)
• Provide executable scripts
• Use template variables like {{flint.name}}, {{uuid}}, {{date}}

Declaring Mods

Mods are declared in flint.toml with their source:

[mods]
claude-code = { source = "NUU-Cognition/flint-mod-claude-code" }
agents = { source = "NUU-Cognition/flint-mod-agents" }
my-mod = { source = "path:./Mods/(Dev) My Mod", dev = true }

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-docs", type = "drive" },
]

The declaration is portable (committed to git). The actual path is stored in the reference file and .flint/references.json (both 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

Repositories

Workspace also supports cloned repositories - Git repos pulled into your Flint for reference:

[workspace]
repositories = [
  { name = "example-api", url = "https://github.com/user/example-api" },
]

[workspace.sources]
repositories = [
  { name = "design-ref", url = "https://github.com/company/design-system" },
]

Full repositories keep .git history. Source repositories are shallow-cloned with .git removed for lightweight reference.

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

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 by creating (Export) prefixed documents in your Mesh/:

# Mesh/(Export) Guide.md
---
export-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 documents, resolves linked documents, follows transclusions, and outputs to Exports/Guide/.

Imports

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

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

Running flint sync automatically builds exports from the source Flint and copies them into Imports/NUU Flint/Guide/.

Connections: Cross-Flint References

Connections link your Flint to other Flints you work with. They use the same declaration + fulfillment pattern as workspace references:

[connections]
flints = [
  { name = "NUU Vessel" },
  { name = "NUU Mesh" },
]

Declarations travel in flint.toml (committed). Fulfillments with machine-specific paths live in Connections/ (gitignored). Target Flints must be registered in the global registry.

Connections are one-way. Flint A connecting to Flint B doesn't mean B knows about A.

Configuration Files

flint.toml

The main configuration file. Human-editable, committed to version control. This is the source of truth for declarations - what shards, mods, imports, references, and connections your Flint needs.

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

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

[mods]
claude-code = { source = "NUU-Cognition/flint-mod-claude-code" }

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

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

[connections]
flints = [
  { name = "NUU Vessel" },
]

flint.json

Machine-managed identity and state file. Committed to version control.

{
  "version": "0.2.0",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "flint",
  "created": "2026-01-15T10:00:00.000Z",
  "synced": "2026-03-01T15:30:00.000Z",
  "migrations": {}
}

Contains the Flint's unique identity (UUID), creation timestamp, last sync timestamp, and applied migrations.

.flint/ Directory

The .flint/ directory stores internal state (gitignored):

.flint/
  references.json      # Fulfilled workspace reference paths
  connections.json     # Fulfilled connection paths

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
  presets/             # Custom preset configurations

registry.json

Tracks registered Flints by path:

{
  "version": 1,
  "flints": [
    {
      "name": "My Project",
      "path": "/Users/me/flints/(Flint) My Project",
      "type": "flint",
      "tags": ["active"],
      "description": "Main project workspace"
    }
  ]
}

The registry enables:

• flint list to show all your Flints
• Import resolution (finding source Flints for imports)
• Connection fulfillment (auto-resolving paths from registry)
• Discovery scan (flint register --scan)

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. Migrations - Runs pending data migrations
3. Obsidian - Clones .obsidian/ configuration if missing
4. Shards - Installs declared shards, warns about orphaned ones
5. Mods - Installs declared mods, runs onSync hooks
6. Imports - Pulls required imports from source Flints
7. Workspace - Validates reference fulfillment status
8. Registry - Updates the global registry if name/path changed
9. Connections - Migrates old formats, validates fulfillment
10. Gitignore - Updates .gitignore for current configuration

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, Shards).
3. Declare, then sync - Edit flint.toml to describe what you want, run flint sync to make it so.
4. Shards are prompts - Safe, inspectable, portable extensions that agents interpret.
5. Mods are infrastructure - Active environment modifications that install files and run commands.
6. 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
• Module - Shards & Mods - Deep dive into the extension system