Introduction

Flint is a local-first workspace framework for structured thinking. It provides a simple but powerful way to organize your notes, connect them to external resources, and collaborate with AI agents.

At its heart, Flint is a folder structure with conventions. But these conventions create something greater: a cognitive workspace where your ideas live as interconnected markdown files, navigable by both humans and AI.

Who Is Flint For?

Developers managing complex projects. If you're building software and need to keep track of architecture decisions, implementation notes, and project plans alongside your code, Flint gives you a structured home for that thinking.

Researchers organizing knowledge. If your work involves connecting ideas across sources, building understanding over time, and producing written outputs, Flint provides the framework to capture and evolve your thinking.

AI-assisted workflows. If you collaborate with AI agents (Claude, ChatGPT, or local models), Flint gives them the context they need to be genuinely helpful. Your agent can read the init file, understand the workspace structure, and get to work without lengthy explanations.

Anyone who wants their notes to be more than a pile of files. Flint turns scattered documents into a connected knowledge graph with clear organization.

The Local-First Philosophy

Your data stays on your machine. A Flint is just a folder - plain markdown files in a sensible structure. There is no cloud service, no proprietary database, no vendor lock-in.

This means:

• You own your data. Move it, back it up, version it with git, sync it however you want.
• It works offline. No internet required. Your workspace is always available.
• It's future-proof. Markdown files will be readable in 50 years. Proprietary formats won't.
• It's inspectable. You can open any file in any text editor and see exactly what's there.

Core Concepts

Mesh: Your Thinking Space

The Mesh/ folder is where your notes live. Every markdown file in Mesh is automatically indexed and becomes part of your knowledge graph. When you write [Other Note](/other-note), you create a link. When you write ![Embedded Content](/embedded-content), you create a transclusion.

Mesh is the center of your workspace. Everything else either feeds into it (context, resources) or flows out of it (exports, outputs).

Shards: Agent Capabilities

The Shards/ folder extends what you and AI agents can do. Shards are markdown-based prompt packages - they provide context, skills, templates, workflows, and knowledge that agents can follow.

For example, the Increments shard helps you track versioned work. The Projects shard provides task management patterns. The Plan shard enables structured planning workflows.

Shards are safe and inspectable. They don't run arbitrary code - they provide structured prompts that agents interpret. Each shard has a shard.yaml manifest defining its identity, version, dependencies, and install behavior.

Mods: Environment Integration

Mods configure how Flint integrates with your environment. The claude-code mod generates CLAUDE.md and .claude/settings.json for Claude Code integration. The agents mod configures AGENTS.md for multi-agent workflows.

Mods can install files, run shell commands at lifecycle points (onInstall, onSync), and provide executable scripts. Unlike shards (which are prompt-based), mods are infrastructure-focused and actively modify your environment.

Workspace: External Resources

The Workspace/ folder connects your thinking to external reality. When you're documenting an API or planning a feature, Workspace bridges the gap between your notes and the actual codebase.

Declare workspace references in flint.toml, fulfill them with local paths, and the reference documents travel with your Flint to explain what each resource is.

The Folder Structure

(Flint) my-project/
├── flint.toml           # Configuration (you edit this)
├── flint.json           # Identity and state (managed by Flint)
├── .flint/              # Runtime data (gitignored)
├── Mesh/                # Your notes and documents
│   └── (System) Flint Init.md
├── Imports/             # Content from other Flints
├── Exports/             # Compiled outputs for sharing
├── Workspace/           # External resource links
├── Media/               # Images, PDFs, assets
├── Shards/              # Agent capabilities (prompt packages)
├── Mods/                # Environment modifications
├── Connections/         # Links to other Flints (gitignored)
└── Subflints/           # Nested Flint workspaces

Each folder has a specific purpose:

Obsidian Integration

Flint workspaces work seamlessly with Obsidian. Open any Flint folder as an Obsidian vault, and you get:

• Graph view of your note connections
• Backlinks panel showing what links to each note
• Quick switcher for fast navigation
• Link completion as you type [
• Preview of linked and embedded content

Flint's conventions (wiki-links, YAML frontmatter, folder structure) are fully compatible with Obsidian's features. You can use Obsidian as your primary editor while the Flint CLI handles syncing and automation.

AI Agent Collaboration

Flint is designed for human-AI collaboration. The structure provides what agents need to be genuinely useful:

Clear entry point. Every Flint has Mesh/(System) Flint Init.md - an overview that agents read at session start. It explains what this workspace is for, how it's organized, and what the current focus is.

Structured context. Shards provide init files that agents load on demand. Instead of dumping everything into context, agents load what they need when they need it.

Defined capabilities. Shard skills give agents clear instructions for common tasks. "Archive completed tasks" or "Create a new increment" become reliable operations, not improvised attempts.

Knowledge references. Shards include knowledge files (knw-*.md) that provide deep reference material on specific topics, giving agents expert-level understanding when needed.

Inspectable state. Everything is markdown. Agents can read any file, understand the structure, and work within established patterns.

The result: shorter sessions, less explanation, more useful output. Your agent understands where things go and how they connect.

Getting Started

Install Flint via npm:

npm install -g @nuucognition/flint

Then create your first workspace:

flint init my-project

This creates the folder structure, initializes configuration, registers the Flint, and syncs configured features. From there:

1. Open the folder in Obsidian or your preferred editor
2. Read the init file at Mesh/(System) Flint Init.md
3. Create notes in Mesh/ - they're automatically indexed
4. Run flint sync anytime you change flint.toml

See [Guide - Quick Start for a complete walkthrough.

Key Commands

What Makes Flint Different

Bounded, not infinite. A Flint has clear edges. One folder, one domain of thought. When it gets too big, split it. This makes workspaces comprehensible to both humans and agents.

Modules with purposes. Each folder has a specific role. You know where things go. No more wondering if this document belongs in docs/, notes/, or resources/.

Declarative configuration. Everything is declared in TOML and markdown. You describe what you want, not how to achieve it. Configuration is readable and portable.

Agent-native design. The init file convention, shard system, and structured context are designed for AI collaboration from the ground up.

Just files. No database, no proprietary format. Your Flint is a folder of markdown files that you can read, edit, and move with any tool.

Next Steps

• Guide - Quick Start - Create your first Flint
• Guide - Core Concepts - Understand the mental model
• Guide - Tutorial Project Planning - See Flint in action for software projects
• Guide - Tutorial Research Notes - See Flint for research and writing
• Module - Mesh - Deep dive into the core module
• Module - Shards & Mods - Understand the extension system