Shards

Shards are the capability layer of Flint. They are cognitive programs -- structured packages of instructions, templates, workflows, and knowledge that agents execute inside the workspace.

Without shards, a Flint is a directory structure and some configuration. With shards, it becomes an environment where an agent can perform repeatable forms of reasoning and produce consistent artifacts.

This page covers how Flint declares, installs, and manages shards. For shard internals -- manifest format, file conventions, authoring, health checks, scripts, and the full CLI reference -- see the dedicated Shard Documentation.

Why Shards Matter

This is the core mental model:

• Flint is the execution environment
• Shards are the cognitive programs available in that environment
• Mesh is where the results of those programs become durable knowledge

Declaring a shard is not just adding a plugin. It is adding a reusable mode of thinking and working. The shards you choose define what your workspace can do.

Declaring Shards

Shards are declared in flint.toml using a keyed declaration model. Each entry names the shard and specifies where to find it:

[shards]
projects = { source = "NUU-Cognition/shard-projects" }
guides = { source = "NUU-Cognition/shard-guides" }
local-tools = { source = "path:./Shards/(Dev) Local Tools", mode = "dev" }

Shards without a mode are normal (consumer) shards -- installed from a remote source and updated via flint shard update.

Three Shard Modes

Flint recognizes three shard modes, each serving a different purpose:

Dev shards are gitignored from the parent Flint repository. Normal and custom shards are committed to it.

Sync Behavior

flint sync treats the shard declarations in flint.toml as authoritative:

• Installs missing declared shards from their sources
• Reconciles installed shards with their declarations
• Warns about undeclared shard folders in Shards/
• Applies install entries and creates declared Mesh folders

This is why a Flint can be cloned and made usable again with a single sync. The workspace declaration says which cognitive programs should be available, and sync makes that true on the local machine.

Common Commands

flint shard list              # List installed shards
flint shard install <source>  # Install a shard
flint shard update            # Update all remote shards
flint sync                    # Sync everything from flint.toml

For the full command reference, including authoring, publishing, health, and script commands, see the Shard CLI Commands in the shard documentation.

Further Reading

The shard system has its own dedicated documentation set covering everything from concepts to CLI reference:

• Concept - What Are Shards -- the shard model, three modes, distribution, and dependencies
• Guide - Creating a Shard -- step-by-step tutorial for building and publishing a shard
• Module - Manifest -- complete shard.yaml field reference
• Module - File Conventions -- directory structure and naming patterns
• Module - Install & Update -- install pipeline, update, pull, and version pinning
• Module - Health & Heal -- diagnostics and auto-repair
• Module - Scripts -- executable scripts shipped with shards
• Module - Migrations -- version-to-version workspace migrations
• Module - Dev Lifecycle -- create, edit, freeze, release, publish
• Reference - CLI Commands -- all flint shard subcommands