Creating a Flint

Creating a Flint is more than running flint init. The quality of the workspace depends on the choices you make in the first fifteen minutes: what kind of Flint this is, which dependencies it declares, and whether the init note is actually useful.

One of the most important choices is which shards the workspace declares. In practice, that means deciding which cognitive programs an agent will be able to execute here.

This guide explains the creation flow in a way that maps cleanly to how Flint works.

The Simplest Possible Start

flint init "My Project"

That command is enough to create a valid workspace. It does all of the following:

creates the (Flint) My Project/ directory
creates the standard directories
creates .flint/
writes flint.toml
writes flint.json
registers the workspace in the local registry
runs flint sync

So init is not just scaffolding. It is the full initial bootstrap path.

What Gets Created

The standard directories are:

Mesh
Media
Shards
Sources
Exports
Workspace
Workspace/Bench

Choosing the Right Creation Path

There are three common creation modes.

1. Blank or normal creation

flint init "My Project"

Use this when you want a clean workspace and you are comfortable declaring what it needs afterward.

2. Preset-based creation

flint init "My Project" --preset default

Use this when you want a more opinionated starting point, usually with shard declarations and starter content.

blank is the implicit default if you do not specify a preset.

3. Clone from an existing Flint repository

flint init --from-git git@github.com:owner/repo.git

Use this when the Flint already exists elsewhere and you want to bootstrap it locally while preserving Flint’s folder naming and registry rules.

Choosing the Parent Directory

If the current shell directory is not where you want the workspace created, use:

flint init "Client Work" --path ~/workspaces

This keeps your current shell location separate from where the Flint will actually live.

What `flint sync` Adds After Creation

init gives you the workspace skeleton, but sync is what reconciles the feature layer around it.

sync can:

install or reconcile declared shards
bootstrap or refresh .obsidian/
generate metadata for sources and references
synchronize source mesh exports
update .gitignore
refresh the registry entry

This is why you should think of the workspace in two phases:

init creates the base structure
sync reconciles the configured relationships

That includes making shard-based workflows available. A newly created Flint is not just a folder for notes; it is the environment an agent will later use to execute the cognitive programs you choose to install.

A Minimal `flint.toml` That Is Actually Useful

The smallest valid flint.toml can be very short, but a good initial version usually looks like this:

[flint]
name = "My Project"
description = "Workspace for planning and documenting the project"

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

That gives the workspace both an identity and at least one declared capability package.

In practical terms, that shard declaration says: this Flint should know how to run a certain kind of structured reasoning workflow.

From there, you grow the file deliberately by adding:

codebase references
other Flint references
sources
exports
workspace repositories

The Best First Fifteen Minutes

Once the workspace exists, a strong setup sequence looks like this:

improve Mesh/(System) Flint Init.md
add a short description to [flint]
declare only the shards you actually intend to use
add at least one real external dependency if the workspace is about something concrete
run flint sync

That sequence turns a skeleton into a usable workspace very quickly.

It also prevents a common failure mode: installing a pile of shards with no clear role. A Flint is more effective when its cognitive programs are chosen intentionally.

When to Add a Codebase Reference Immediately

If the Flint is about software, add the main codebase reference right away:

flint reference codebase "Main App"
flint fulfill codebase "Main App" /path/to/app

Doing this early changes the quality of the workspace. Notes can now point to the real source instead of becoming a detached documentation island.

When to Add a Workspace Repo Instead

If the code should actually live inside the Flint’s own working surface, use a workspace repo:

flint workspace create "App" git@github.com:me/app.git

Do not use workspace repos and references interchangeably. Use the one that matches the actual relationship you want.

A Good Post-Creation Command Set

These are the commands most people want within the first hour:

flint shard list
flint reference list
flint sync
flint open
flint git init

The Real Goal of Creation

The goal is not merely to have a Flint on disk. The goal is to create a workspace that is:

easy to understand
anchored to real sources
comfortable for future writing
legible to an agent at session start

If you optimize for that, the rest of the system starts working much more naturally.

On this page