Tutorial: Research Notes

This walkthrough shows how to use Flint as a research workspace: gather source material, write your own interpretation in Mesh/, and publish a clean export when you are ready.

The key idea is simple:

Sources are not your notes. Mesh is your notes.

That one distinction makes the rest of the workflow much easier.

Step 1: Create the Research Workspace

Start with a fresh Flint:

flint init "Model Research"
cd "(Flint) Model Research"

At this point, you have the structure. What you do next determines whether the workspace stays clean or turns into a pile of copied material.

Step 2: Bring in External Material the Right Way

There are two common ways to bring source material into a research Flint.

Option A: Add a source repository

If the source material already exists as a repository and you want a read-only copy inside the workspace:

flint source repo add "Transformer Notes" https://github.com/example/transformer-notes.git

This creates a shallow reference copy in Sources/Repos/ and strips .git.

That makes it ideal for:

• documentation repos
• reference datasets or structured text
• example implementations you want nearby but do not intend to work in directly

Option B: Source a mesh export from another Flint

If another Flint already contains curated research material you want to reuse:

flint source meshexport list
flint source meshexport add "Research Hub/Papers"

This pulls the other Flint’s built export into Sources/Flints/.

That is a much better workflow than copy-pasting notes between vaults.

Step 3: Keep Your Actual Thinking in Mesh

Once source material exists, the temptation is to start annotating it in place. Resist that.

Your durable interpretation should live in Mesh/.

Typical research-note patterns include:

• source summary notes
• concept comparison notes
• question lists
• synthesis notes
• a guide or report that will eventually be exported

Sources/ is input. Mesh/ is where the research becomes yours.

Step 4: Use Media for Attachments and Figures

If the research involves PDFs, screenshots, diagrams, or figures, put those in Media/.

Then reference them from Mesh notes rather than scattering binary files across the rest of the workspace.

This matters later because export builds can copy referenced media into the final output.

Step 5: Write Toward a Publishable Root Note

A research Flint becomes much more useful when there is a clear note that serves as the eventual public-facing synthesis.

This could be:

• a guide
• a report
• a literature review
• an internal brief

Once that note exists, you can gradually link supporting notes beneath it instead of waiting until the very end to assemble everything.

Step 6: Declare the Export

When the root note is ready to become publishable output, tag it with #export, then run:

flint export scan
flint export build

The current export system will:

• walk the note graph from that root
• rewrite links for the export surface
• expand embeds
• copy referenced media
• write _manifest.json

This lets you keep the working graph rich while the published output stays clean.

Step 7: Refresh Sources Deliberately

Research work changes over time. Repos move, documents update, and curated source Flints evolve.

Refresh source repos explicitly when needed:

flint source repo update "Transformer Notes"

For sourced mesh exports, keep the declarations in flint.toml accurate and run:

flint sync

The key word here is deliberately. You do not want the workspace to blur together fresh source material and your own long-term interpretation without noticing.

A Good Research Pattern

One healthy pattern looks like this:

1. gather material into Sources/
2. write rough interpretation notes in Mesh/
3. merge or refine those into synthesis notes
4. keep supporting assets in Media/
5. build a clean export from one curated root note

This gives you a workspace that can grow without losing the difference between gathered context and authored understanding.