Creating a Flint

How to create and initialize Flint workspaces.

Overview

Flint follows a local-first model. Your local flint is fully functional on its own, with all state derived from configuration files. There's no cloud service required.

The Init-Sync Model

Creating a flint is a two-phase process:

┌─────────────────────────────────────────────────────────────────┐
│  INIT PHASE                                                     │
│  Creates essential flint structure                              │
│                                                                 │
│  1. Create folder: (Flint) <name>/                              │
│  2. Create standard directories (Mesh/, Media/, Shards/, etc.)  │
│  3. Create .flint/ directory                                    │
│  4. Create flint.toml with name, type, shards, mods             │
│  5. Create flint.json with identity (UUID, version, timestamp)  │
│  6. Apply preset templates (if any)                             │
│  7. Register in local registry (~/.flint/registry.json)         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  SYNC PHASE                                                     │
│  Installs configured features from flint.toml                   │
│                                                                 │
│  1. Run pending migrations                                      │
│  2. Clone .obsidian/ configuration                              │
│  3. Install shards from [shards] section                        │
│  4. Install mods from [mods] section                            │
│  5. Pull imports from [imports] section                          │
│  6. Validate workspace references                               │
│  7. Update .gitignore                                           │
│  8. Run mod onSync hooks                                        │
└─────────────────────────────────────────────────────────────────┘

This separation means:

Init creates structure - everything that makes a flint a flint
Sync installs features - shards, mods, imports, and their effects
Sync is idempotent - run it anytime to reconcile configured state
Config is truth - the entire flint can be regenerated from flint.toml

Basic Usage

Minimal Flint

flint init my-project

Creates:

(Flint) my-project/
├── .flint/
├── Mesh/
│   └── (System) Flint Init.md
├── Media/
├── Shards/
├── Mods/
├── Imports/
├── Exports/
├── Workspace/
├── flint.toml
└── flint.json

Without a preset, the flint.toml contains only:

[flint]
name = "my-project"
type = "flint"

The flint.json contains identity:

{
  "version": "0.2.0",
  "id": "a1b2c3d4-...",
  "type": "flint",
  "created": "2026-03-02T...",
  "synced": "2026-03-02T..."
}

With a Preset

flint init my-project --preset default

The default preset adds all standard shards and mods:

[flint]
name = "my-project"
type = "flint"

[shards]
increments = { source = "NUU-Cognition/shard-increments" }
plan = { source = "NUU-Cognition/shard-plan" }
notepad = { source = "NUU-Cognition/shard-notepad" }
reports = { source = "NUU-Cognition/shard-reports" }
comments = { source = "NUU-Cognition/shard-comments" }
learn = { source = "NUU-Cognition/shard-learn" }
flint = { source = "NUU-Cognition/shard-flint" }
knap = { source = "NUU-Cognition/shard-knap" }
orbcode = { source = "NUU-Cognition/shard-orbcode" }
projects = { source = "NUU-Cognition/shard-projects" }

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

Presets

Presets are pre-configured flint templates that bundle shards, mods, and starter files.

Available Presets

Preset	Description	Shards	Mods
`blank`	Empty flint, nothing installed (default)	none	none
`default`	Full setup with all standard shards and mods	increments, plan, notepad, reports, comments, learn, flint, knap, orbcode, projects	claude-code, agents

Using Presets

# Empty flint (default behavior)
flint init notes

# Full setup with all shards and mods
flint init research --preset default

Preset Locations

Presets are discovered from:

Built-in: <flint-install>/presets/
User: ~/.flint/presets/ (can override built-in)

Creating Custom Presets

Create a folder in ~/.flint/presets/ with a preset.toml:

~/.flint/presets/my-preset/
├── preset.toml
└── templates/
    └── Overview.md

# preset.toml
[preset]
name = "my-preset"
description = "My custom preset for research projects"

[shards]
required = ["notepad", "reports"]

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

[templates](/templates)
source = "templates/Overview.md"
target = "Mesh/Overview.md"

Template files support variables:

{{name}} - flint name
{{date}} - creation date (YYYY-MM-DD)
{{uuid}} - unique identifier

Configuration Files

flint.toml (Source of Truth)

Human-editable configuration, committed to git. Declares everything:

[flint]
name = "My Project"
type = "flint"
tags = ["active", "dev"]
description = "Main development workspace"

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

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

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

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

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

flint.json (Identity & State)

Machine-managed, committed to git. Tracks identity and timestamps:

{
  "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": {
    "migration-id": "2026-02-01T..."
  }
}

.flint/ Directory (Local State)

Gitignored runtime state:

.flint/
  references.json      # Machine-specific workspace paths
  connections.json     # Machine-specific connection paths

The Local Registry

The registry at ~/.flint/registry.json tracks all your flints for CLI discovery:

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

Key points:

Registry stores name + path + type + tags + description
Path is the primary identifier
Used by flint list, import resolution, and connection fulfillment
Automatically updated by init, register, unregister, and sync
Run flint registry validate to clean up broken entries

Managing the Registry

# List registered flints
flint list

# Register an existing flint (cloned, moved, etc.)
flint register /path/to/flint

# Scan and register multiple flints
flint register --scan ~/projects

# Remove from registry (keeps files)
flint unregister

# Validate and clean broken entries
flint registry validate

# Add tags to a registered flint
flint registry tag "My Project" "important"

Command Reference

flint init

flint init <name> [options]

Options:

--path <dir> - Parent directory (default: current directory)
--preset <name> - Use a preset configuration

Examples:

flint init my-project
flint init research --preset default
flint init docs --path ~/projects

flint sync

After init, or anytime you modify flint.toml:

flint sync

What it does:

Creates missing directories
Runs pending migrations
Installs/warns about shards to match config
Installs/removes mods to match config
Pulls required imports
Validates workspace references and connections
Updates registry if name/path changed
Updates .gitignore
Stamps sync timestamp in flint.json

Best Practices

Starting Fresh

# Quick start with common shards
flint init my-project --preset default

Minimal Setup

# Just the structure, add shards later
flint init my-project
# Then edit flint.toml and run:
flint sync

Cloning an Existing Flint

git clone <repo> "(Flint) my-project"
cd "(Flint) my-project"
flint register
flint sync
# Fulfill workspace references and connections
flint workspace fulfill
flint connection fulfill --all

Moving a Flint

# Move the folder
mv "(Flint) old-location" "/new/path/(Flint) my-project"

# Update registry
flint unregister /old/path
flint register /new/path/(Flint) my-project

# Or just sync from the new location - it auto-detects the move
cd "/new/path/(Flint) my-project"
flint sync

Troubleshooting

"Not a flint directory"

The directory must have a flint.toml file. Either:

Run flint init to create a new flint
Run flint register if it's an existing flint

Missing directories after clone

Run flint sync to create standard directories and install shards.

Flint not showing in `flint list`

flint register /path/to/flint

Shards not installing

Check your flint.toml has the shards listed:

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

Then run flint sync.

Reference - CLI Commands - Full command reference
Reference - Configuration - Configuration options
Module - Shards & Mods - Shard and mod system details

On this page