Quick Start: Your First Flint

Get from zero to a working Flint workspace.

Prerequisites

Node.js 20+ - Check with node --version
macOS or Linux (Windows users: use WSL)
Obsidian (optional but recommended) - For the best editing experience

Step 1: Install the CLI

Install Flint via npm:

npm install -g @nuucognition/flint

Verify installation:

flint --version

Update

npm update -g @nuucognition/flint

Uninstall

npm uninstall -g @nuucognition/flint

Your data (~/.flint/) is preserved.

Step 2: Create Your First Flint

Navigate to where you want your workspace and create a new Flint:

flint init "My Project"

This creates the folder (Flint) My Project/ with the essential structure, registers it in the global registry, and syncs any configured features.

With the default preset (recommended for new users):

flint init "My Project" --preset default

The default preset includes all standard shards (projects, increments, notepad, plan, reports, etc.) and mods (Claude Code, agents). Without --preset, you get a clean empty flint.

Step 3: Explore the Structure

Navigate into your new Flint:

cd "(Flint) My Project"

Here's what was created:

(Flint) My Project/
├── flint.toml           # Configuration file (you edit this)
├── flint.json           # Identity and state (auto-managed)
├── .flint/              # Runtime data (gitignored)
├── Mesh/                # Your notes go here
│   └── (System) Flint Init.md
├── Imports/             # Content from other Flints
├── Exports/             # Compiled outputs for sharing
├── Workspace/           # Links to external resources
├── Media/               # Images, PDFs, assets
├── Shards/              # Agent capabilities (prompt packages)
├── Mods/                # Environment modifications
├── Connections/         # References to other Flints
└── Subflints/           # Nested Flint workspaces

If you used --preset default, you'll also have shards installed in Shards/ and mods in Mods/.

Step 4: Read the Init File

Open Mesh/(System) Flint Init.md in any text editor. This file:

Explains what this Flint is for
Describes the folder structure
Lists installed shards and their capabilities
Provides guidance for AI agents working in this space

Every time you (or an AI agent) starts working in a Flint, reading the init file first ensures you understand the workspace context.

Step 5: Open in Obsidian

For the best editing experience, open your Flint folder directly in Obsidian as a vault:

Open Obsidian
Click "Open folder as vault"
Select your (Flint) My Project/ folder

Flint's conventions (wiki-links, YAML frontmatter, folder structure) are fully compatible with Obsidian's features.

Step 6: Create Your First Note

Create a file in Mesh/. You can use the command line, your editor, or Obsidian.

Example note at Mesh/Project Ideas.md:

---
id: auto-generated-by-sync
tags:
  - "#brainstorm"
---

# Project Ideas

Initial thoughts for the project.

## Mobile App

A mobile companion would help with [On-the-Go Access](/on-the-go-access).

## Integration

Consider connecting to [External Services](/external-services).

Key concepts:

Frontmatter - YAML at the top with metadata
Wiki links - [Note Name](/note-name) links to other notes
Tags - Use #tag format in frontmatter or inline
IDs - Auto-generated by index (unique identifiers)

Step 7: Sync Your Workspace

Run sync to update the workspace state:

flint sync

Sync performs several operations:

Creates missing directories
Installs/updates shards declared in flint.toml
Installs/updates mods declared in flint.toml
Pulls required imports from source Flints
Validates workspace references and connections
Updates the global registry
Updates .gitignore for current configuration

Run sync regularly - after changing configuration, pulling git changes, or when something seems off.

Step 8: Basic Workflows

Install Shards

Use the CLI to install shards:

# Install from the default registry
flint shard install NUU-Cognition/shard-projects

# Or add to flint.toml and sync

Edit flint.toml to declare shards:

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

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

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

Then sync to install them:

flint sync

List Installed Shards

flint shard list

Link a Codebase

If your Flint relates to a codebase, create a workspace reference:

flint workspace reference monorepo /path/to/your/code

This declares the reference in flint.toml and creates Workspace/References/rf-monorepo.md with the local path.

Index Your Notes

To manually add IDs to markdown files:

flint index

This scans all markdown files and adds unique IDs to their frontmatter.

Essential Commands Reference

Command	What it does
`flint init <name>`	Create a new Flint
`flint sync`	Sync config, shards, mods, imports
`flint list`	List registered Flints
`flint index`	Add IDs to Mesh files
`flint shard list`	Show installed shards
`flint shard install <source>`	Install a shard
`flint mod list`	Show installed mods
`flint mod install <source>`	Install a mod
`flint workspace list`	Show workspace references
`flint connection list`	Show connections
`flint --help`	See all commands

File Naming Conventions

Flint uses typed prefixes to indicate document purpose:

Pattern	Purpose
`(System) *.md`	Configuration and navigation
`(Task) NNN *.md`	Actionable work items
`(Dashboard) *.md`	Overview documents
`(Plan) NNN *.md`	High-level plans
`(Increment) X.Y.Z - *.md`	Version work packages
`(Notepad) NNN *.md`	Brainstorming sessions
`(Report) *.md`	Research/analysis output
`*.md`	Regular notes