Workspace

Connect your Flint to external codebases and resources.

Purpose

Your Mesh contains thoughts about things. The Workspace module connects those thoughts to the actual things - codebases, data directories, APIs, databases, and external services. When you're documenting an API or planning a feature, Workspace bridges the gap between your notes and the code.

The key insight: declarations travel, paths don't. Workspace references are declared in flint.toml (committed, portable), while the actual machine-specific paths live in Workspace/References/*.md files (gitignored, local).

Architecture

Workspace uses a two-part system to maintain portability:

1. Declarations in flint.toml - what external resources this Flint needs
2. Fulfillments in Workspace/References/*.md - where those resources live on this machine

flint.toml (committed)              Workspace/References/ (gitignored)
┌─────────────────────────┐        ┌──────────────────────────────┐
│ [workspace]             │        │ rf-monorepo.md               │
│ references = [          │        │   **Path:** /Users/me/code   │
│   { name = "Monorepo",  │   →    │   **Type:** codebase         │
│     type = "codebase"}, │        │                              │
│ ]                       │        │   ## Key Paths               │
└─────────────────────────┘        │   - packages/flint/          │
                                   └──────────────────────────────┘

When you clone a Flint, you see what external resources it needs (from flint.toml) and can fulfill them with local paths.

Reference Types

Workspace supports five reference types:

Directory Structure

Workspace/
└── References/           # Gitignored - machine-specific paths
    ├── rf-monorepo.md    # Path to monorepo on this machine
    └── rf-assets.md      # Path to assets folder

The Workspace/References/ directory is gitignored. Each rf-*.md file contains:

• The local path to the resource
• The reference type
• Optional notes about key paths and usage

Commands

List Workspace References

flint workspace list

Shows all declared workspace references with their fulfillment status:

• Green checkmark - Fulfilled (path exists)
• Yellow circle - Unfulfilled (no path configured)
• Red exclamation - Missing (path configured but doesn't exist)

Example output:

Workspace References:

  ✓ Monorepo (codebase)
      ~/dev/nuu/main
  ○ Assets (drive)
      (unfulfilled - no path configured)
  ! OldProject (codebase)
      ~/dev/old-project
      (path not found)

Add a Reference

flint workspace add <name> [--type <type>]

Declares a new workspace reference in flint.toml. The reference is unfulfilled until you provide a path.

# Add a codebase reference (default type)
flint workspace add Monorepo

# Add a drive reference
flint workspace add Assets --type drive

# Add a database reference
flint workspace add DevDB --type database

This adds to your flint.toml:

[workspace]
references = [
  { name = "Monorepo", type = "codebase" },
  { name = "Assets", type = "drive" },
  { name = "DevDB", type = "database" },
]

Fulfill a Reference

flint workspace fulfill [name] [path]

Provides a local path for a declared reference. Creates a rf-*.md file in Workspace/References/.

# Fulfill a specific reference with a path
flint workspace fulfill Monorepo /Users/me/dev/main

# Interactive mode - prompts for all unfulfilled references
flint workspace fulfill

When you fulfill a reference, Flint creates:

Workspace/References/rf-monorepo.md

With content:

**Path:** /Users/me/dev/main
**Type:** codebase

## Key Paths

- (add key paths here)

## Notes

(add notes here)

Remove a Reference

flint workspace remove <name>

Removes both the declaration from flint.toml and the fulfillment file from Workspace/References/.

flint workspace remove OldProject

Reference Command (Legacy)

flint workspace reference <name> [path] [--type <type>]

Combines add and fulfill in one step. If you provide a path, the reference is immediately fulfilled.

# Declare and fulfill in one step
flint workspace reference Monorepo /Users/me/dev/main

# Just declare (same as 'add')
flint workspace reference Monorepo

Reference File Format

Each rf-*.md file in Workspace/References/ follows this format:

**Path:** /absolute/path/to/resource
**Type:** codebase

## Key Paths

- packages/flint/ - Core Flint library
- apps/flint-cli/ - CLI application

## Notes

Main development monorepo for the Flint project.
Contains all packages and applications.

The file is parsed to extract:

• Path - The machine-specific absolute path
• Type - The reference type (for validation)

The Key Paths and Notes sections are for documentation - they help collaborators understand the resource when they clone the Flint and need to fulfill the reference.

Portability

The workspace system is designed for portable Flints:

1. Clone a Flint - flint.toml tells you what external resources are needed
2. Run sync - flint sync shows unfulfilled workspace references
3. Fulfill references - flint workspace fulfill lets you provide local paths
4. Continue working - Your local paths stay gitignored

Example: Cloning a Flint

# Clone a Flint that needs a monorepo reference
git clone https://github.com/example/my-flint.git

cd my-flint

# See what's needed
flint workspace list
#   ○ Monorepo (codebase)
#       (unfulfilled - no path configured)

# Fulfill with your local path
flint workspace fulfill Monorepo ~/code/main-project

# Now ready to work
flint sync

Sync Behavior

When you run flint sync, workspace references are validated:

1. Migration - Old workspace formats are migrated to the new system
2. Status check - Each declared reference is checked for fulfillment
3. Path validation - Fulfilled references are checked to ensure paths exist
4. Reporting - Issues are displayed with guidance on how to fix them

Example sync output with workspace issues:

Workspace:
  ○ Assets (unfulfilled)
  ! OldProject (path not found)

  Run 'flint workspace fulfill' to provide local paths.

Use Cases

Linking a Git Repository

The most common use case - connecting your Flint to the codebase it documents.

# Declare the reference
flint workspace add Monorepo --type codebase

# Fulfill with path
flint workspace fulfill Monorepo ~/dev/nuu/main

Now your Mesh notes can reference the codebase, and collaborators know the Flint needs access to a monorepo.

Linking an External Docs Folder

Connect to a shared documentation folder or drive.

flint workspace add SharedDocs --type drive
flint workspace fulfill SharedDocs "/Volumes/Team Drive/Documentation"

Linking a Development Database

Track external dependencies like databases.

flint workspace add DevDatabase --type database
flint workspace fulfill DevDatabase "localhost:5432/devdb"

Handling Missing References

If a reference path no longer exists (resource moved or deleted):

# Check status
flint workspace list
#   ! OldProject (codebase)
#       ~/dev/old-project
#       (path not found)

# Option 1: Update the path
flint workspace fulfill OldProject ~/dev/new-location

# Option 2: Remove if no longer needed
flint workspace remove OldProject

Referencing from Mesh

Link to workspace references in your notes using Obsidian wiki-links:

See the implementation in [Workspace/References/rf-monorepo](/workspace-references-rf-monorepo).

The codebase follows the patterns documented in [Workspace/References/rf-monorepo#Key Paths](/workspace-references-rf-monorepo-key-paths).

Note: These links reference the fulfillment files, which contain documentation about the resource. The actual external paths are for tooling use, not direct linking.

Best Practices

Declare all external dependencies. If your Flint references external resources, declare them in workspace so collaborators know what's needed.

Document your references. Add key paths and notes to your rf-*.md files. When someone clones your Flint, they should understand what each reference is for.

Use descriptive names. "Monorepo" is better than "repo". "ClientAssets" is better than "assets".

Check status regularly. Run flint workspace list to ensure your paths are still valid.

Keep paths absolute. Always use absolute paths when fulfilling references. Relative paths break when you work from different directories.

Common Mistakes

• Committing reference files - Workspace/References/*.md should be gitignored
• Using relative paths - Always use absolute paths for fulfillment
• Forgetting to fulfill - After cloning, run flint workspace fulfill
• Hardcoding paths in Mesh - Reference the workspace, not raw file paths

Related

• Module - Mesh - Notes that reference workspace resources
• Reference - Configuration - Workspace section in flint.toml
• Command - Sync - How sync validates workspace references