Sources

Sources/ is Flint's intake layer for external material that should be copied into the workspace. If Shards/ gives an agent cognitive programs to execute, Sources/ gives those programs local material to read from.

Use sources when you want external content to become part of the working environment. The source stays external in origin, but Flint materializes a local copy so agents and humans can inspect it without resolving a remote dependency every time.

What Lives in Sources/

Flint currently supports two source families:

• source repositories copied into Sources/Repos/
• mesh exports copied into Sources/Flints/(Flint) Name/(Mesh Export) ExportName/

Both are declared in flint.toml under [sources].

[sources]
repositories = [
  { name = "Design System", url = "https://github.com/org/design-system" },
]
meshexports = [
  "Research Hub/Guide",
]

Source Repositories

Source repositories are read-only reference copies of external Git repositories.

flint source repo add "Design System" https://github.com/org/design-system
flint source repo list
flint source repo update "Design System"
flint source repo remove "Design System"

When Flint adds one of these repositories it:

• clones into Sources/Repos/
• uses a shallow reference-style clone
• strips .git so the copy behaves like workspace material, not an active checkout
• writes metadata so the source is visible from the Mesh metadata layer

This is the right choice when an agent needs code or documents as reference input, but the repo is not supposed to be edited in place from the current Flint.

Source Mesh Exports

Source mesh exports let one Flint pull a published export from another Flint into its own workspace.

flint source meshexport list
flint source meshexport add "Research Hub/Guide"
flint source meshexport remove "Research Hub/Guide"

The value format is always:

"Flint Name/Export Name"

When you add a mesh export source, Flint:

1. resolves the source Flint through the local registry
2. checks that the named export exists
3. builds that export in the source Flint
4. copies the built Mesh/ and Media/ output into Sources/Flints/...
5. writes metadata notes for the sourced material

That gives the current Flint a stable local copy of another workspace's published knowledge.

Sync Behavior

flint sync treats [sources] as the source of truth.

For mesh exports, sync reconciles the copied output against the declarations in flint.toml. If a mesh export source is removed from config, sync removes the local sourced copy and its metadata. If it stays declared, sync refreshes it.

For source repositories, Flint can also clone missing declared repositories and keep .gitignore aligned with the current declarations.

Sources vs References

Choose Sources/ when you want the external material copied into the Flint.

Choose references when you only need a named pointer to another codebase or Flint and do not want Flint to copy the content itself.

That distinction matters in practice:

• sources make material locally browseable for agents
• references keep dependencies lightweight and machine-specific

Sources vs Workspace Repositories

Use Workspace/Repos/ for repositories you intend to actively work in.

Use Sources/Repos/ for read-only reference copies that support the agent's cognitive work without becoming the workspace's active development surface.