NUU Guide

Sources/ holds copies of external material for reading. It has two families: source repositories and Flint bundles. You declare both in flint.toml under [sources]. Sync copies them into the Flint.

Overview

Sources are copies, not pointers. Flint materializes each declared source as a local folder, so people and agents read it without network access. Treat every folder under Sources/ as read-only derived state. Do not edit it in place. When the upstream changes, sync or an update command takes a fresh copy.

The [sources] block in flint.toml is the source of truth. Sync copies each missing declared source. Sync reports each extra local folder as drift. Sync never deletes an extra folder.

Source Repositories

A source repository is a read-only snapshot of an external Git repository. It lives in Sources/Repos/<name>/.

Manage source repositories with these commands:

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"

Each command behaves as follows:

add records the declaration in flint.toml. It clones nothing. Run flint sync to clone the snapshot.
list shows each declared repository and whether its folder exists. It accepts --wide for full-width output.
update takes a fresh snapshot of the upstream HEAD and replaces the old snapshot. When the folder is missing, it makes the first snapshot. Use it to move a snapshot to newer upstream content.
remove deletes the declaration from flint.toml. It leaves the folder on disk for manual cleanup. It asks for confirmation. Use --force to skip the question. Without a terminal, the command refuses and names the --force form.

Names match without regard to letter case.

When sync clones a snapshot, it takes a shallow clone of depth 1 and strips .git. The copy is not an active checkout. Sync writes a receipt (.flint-receipt.json) into the snapshot folder. On later runs sync trusts a snapshot that has a complete receipt. Sync does not contact the upstream for a snapshot that it already has. When you change the url of a declaration, the next sync takes a new snapshot.

A snapshot older than 7 days produces a notice that names flint source repo update "<name>". The snapshot stays in place.

Flint Bundles

A Flint bundle is a folder that this Flint copies from another Flint on this machine (the producer). It lives in Sources/Bundles/<bundle name>/.

No command adds or removes a bundle declaration. Edit flint.toml by hand:

[sources]
bundles = [
  { source = "flint", name = "Research Hub/Guide" },
]

The source value must be "flint". The name value has this form:

"Flint Name/Bundle Name"

During sync, Flint finds the producer Flint by name in the roster of this machine (see The Roster). It copies the producer folder Exports/(Bundle) <Bundle Name>/ into Sources/Bundles/<Bundle Name>/. When the producer changes its bundle, the next sync copies the new content. When the producer Flint is missing from this machine, or its bundle folder is missing, sync reports one row and keeps the copied bundle unchanged. Extra local bundle folders are reported as drift, not deleted.

flint resolve source prints the path of a copied bundle in this Flint:

flint resolve source "Research Hub/Guide"

When the folder is missing, the command refuses and names flint sync.

Sync Behavior

flint sync treats [sources] as the source of truth. It copies each missing declared repository and each missing or changed declared bundle. It aligns the managed block of .gitignore with the current declarations. It writes marker notes under Mesh/Metadata/Sources/, so each source stays visible from the Mesh metadata layer.

While the Flint declares a source repository, the managed block of .gitignore ignores Sources/Repos/. Git does not track the snapshots, and each machine takes its own snapshot. The managed block does not ignore Sources/Bundles/.

flint plan and flint sync --dry-run show the same plan and change nothing. They open no network connection.

Each repository name and each bundle name must be one folder name. A bad name produces one report row. Sync still processes each valid declaration.

Configuration

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

The url of a repository is a Git URL. The accepted forms are https:// (and http://, git://), ssh://, the short SSH form git@host:path (for example git@github.com:org/repo.git), file://, and a local path (absolute, ./, ../, or ~/). A value that starts with -, or that uses the form <transport>::<address>, is refused. Git runs with only the protocols file, git, http, https, and ssh. A value that is not a Git URL is reported as not valid, and sync clones nothing for it. flint source repo add writes a relative local path relative to the Flint root, with ./ or ../.

Sources, Workspace Repositories, and References

Three mechanisms connect a Flint to outside material. Each one serves a different need.

Use Sources/ when you want Flint to copy external material into the Flint for reading. The copy is read-only.
Use Workspace/Repos/ when you want to edit, run, and commit a repository as part of daily work. The copy is a full Git checkout. See Workspace.
Use a reference when you need only a named pointer to a codebase or to another Flint, with no copy. See References.

Sources