NUU Guide

The roster is the list of Flints that this machine knows. Flint uses it to find a Flint by its name.

Where the Roster Is

The roster is one file in the NUU home:

~/.nuucognition/places.json

(With NUU_HOME set, the file is $NUU_HOME/places.json.) The file ~/.nuucognition/flint/registry.json is a copy that Flint makes from the roster; do not edit it. The command flint registry manages this roster copy, not the shard registry. flint registry rebuild makes the copy again.

Each row of the roster has the path and the kind of a Flint. Flint reads the id and the name from the files of the Flint. The copy flint/registry.json holds the id, the type, the name, the local name, the aliases, and the path. The roster is local to this machine. It is not a cloud service, and no Flint holds it.

The roster is not the shard registry. The shard registry is the NUU service that lists the published shards.

Why the Roster Matters

These commands find a Flint through the roster:

flint open <name> and flint cd <name>
flint move <name> <destination> and flint convert <name>
flint delete <name>
flint reference flint "<name>", when flint sync fulfills the reference
flint sync, for a bundle declared as "<Flint>/<Bundle>" in [sources].bundles
flint list, which shows the roster

flint open, flint cd, flint move, and flint convert accept the name in any letter case, a local name, an alias, the id, or the address of the Flint. The word computer names the Computer Flint. If a name matches two Flints, the command refuses and shows both, each with its type. If a name matches none, the command refuses and names flint list.

The other commands are stricter. flint delete takes the exact name or the path of the Flint. A Flint reference and a bundle take the exact name, local name, or alias of a Flint of the type flint.

`flint create` Adds the Flint

flint create "<name>" adds the new Flint to the roster. flint create --from <git url> adds the clone too. Most of the time, you do not touch the roster.

You touch it when:

you moved or copied a Flint folder by hand
you have a Flint that another machine made
a path changed and the row is out of date

The Name Rule

The name of a Flint is unique for its type on this machine. Two Flints of one type cannot have names with the same slug, in any case and in any folder: My Notes and my notes are one name. A Flint and a Guide can have one name; then give the type to find one of them. flint create checks the name before it writes anything. When the name is in use, it stops and prints the next command.

A Flint name uses the letters A to Z, the digits 0 to 9, spaces, and the characters - ' , . ! & + ; @. It has at most 100 characters. It does not end with a space or a dot.

The word computer is reserved: it always names the Computer Flint. No other Flint can take it as its name, its local name, or an alias. flint create and flint rename refuse it. A Flint that arrives with the name Computer, for example a clone, gets the local name Computer (1) and a warning. flint doctor then names the Flint and the rename to run.

The rule keeps flint open <name>, flint reference flint "<name>", and the bundle names of flint sync clear.

The Flint Types

Each Flint has one type. The type shows in the TYPE column of flint list and in the folder name in parentheses, for example (Guide) NUU Cognition. The four types are:

flint — a normal Flint. Most Flints have this type.
computer — the Computer Flint. It is the home of this machine. One machine has one. flint setup always makes it. flint setup computer makes it alone.
guide — a Guide about an entity. An agent answers questions from its Mesh. With an org, its visibility is public. With no org, it is private. flint create --type guide --about <address> makes one.
member — the Member Flint of one person about one org. Its visibility is private and it cannot change. The org cannot read it. One person has one Member Flint per org. flint create --type member --regarding <org> makes one.

flint convert changes the type of a Flint that already exists. See Change the Type below.

List the Roster

flint list

ls is an alias of list. The table shows the type, the name, the org, and the path of each Flint. The ORG column shows - for a local Flint.

Useful flags:

flint list --status      # Show whether each path still exists
flint list --json        # One JSON value
flint list --full-path   # Show the full paths
flint list --group       # Group the Flints by tag
flint list --tag docs    # Only the Flints with the tag docs
flint list --search notes

flint list hides a row whose path does not exist. flint list --status shows each row as valid or broken. Use --status first when a name does not resolve.

Browse the Roster

flint browse

flint browse shows the roster in an interactive list. Pick a Flint to open the Orbh cockpit in it. Press o to open the highlighted Flint in Obsidian: the list stays, and one line shows the result of the open and its next step. The list hides an entry with no Flint on disk: a missing folder, or a folder with no flint.toml. flint browse --all also shows these entries.

Open a Flint in Obsidian

flint open "My Notes"
flint open guide "NUU Cognition"
flint open computer

flint open opens or focuses the Flint in Obsidian. Give a name, or a type and a name when two Flints share one name. The word computer opens the Computer Flint of this machine, from any folder. With no Computer Flint, it refuses with Next: flint setup computer. With no argument, flint open opens the Flint of the current folder.

To print the folder without opening Obsidian:

flint open "My Notes" --no-launch

Go to a Flint in the Terminal

flint cd "My Notes"
flint cd guide "NUU Cognition"
flint cd computer

flint cd takes its arguments exactly as flint open does. It prints the folder of the Flint. With the shell integration, it changes the folder of your shell. Without the integration, use its output:

cd "$(flint cd "My Notes")"

To install the integration, run flint setup shell-integration. With the integration, flint cd --help (or -h) prints the help and changes no folder. The help names the word computer. An integration block from an older Flint can fail on flint cd --help with file name too long: run flint setup shell-integration again to write the current block.

Add a Flint to the Roster

To add a Flint that is on disk:

flint register /path/to/flint

In the Flint, the path is not needed:

flint register

flint register reads the name and the type from flint.toml of the Flint. Run it again after you move a Flint folder by hand, or after you change the name in flint.toml: the row then takes the new path, name, and type. It refuses when the path is not a Flint.

Move a Flint

To move a Flint, prefer flint move <name> <destination>. It moves the folder and updates the roster in one step. The destination is the new path of the Flint folder, not its parent folder:

flint move "My Notes" "$HOME/notes/(Flint) My Notes"

The parent folder of the destination must exist. The command refuses when the destination exists. flint move --force first deletes the folder at the destination, then moves the Flint.

The command also relocates the vault registry entry of Obsidian, so the vault keeps its vault id and its trust. It refuses when the vault is open in Obsidian: close the vault, then run the command again from a terminal outside Obsidian. When Obsidian runs during the move, the change of the vault registry waits. Quit Obsidian, then run flint obsidian vaults repair --yes.

A Flint that is a member of a Tinderbox leaves the box: the command asks first, then removes the member from tinderbox.toml. --yes skips the question.

To move the Computer Flint, run flint move computer "<new path>". Flint still finds it after the move.

A move by hand does not change the vault registry of Obsidian. Its entry then names the old folder, which is missing. Quit Obsidian, then clean the vault registry:

flint obsidian vaults repair          # the preview
flint obsidian vaults repair --yes    # remove the entries whose folder is missing

Obsidian registers the new folder when it opens it, and it asks for the trust click again. After a move by hand, run flint register in the new folder. Do not move the Computer Flint by hand.

Rename a Flint

In the Flint, run:

flint rename "New Name"

flint rename renames the Flint that holds the current folder. It renames the folder too, so the folder name matches the new name and the type. It refuses before any write when another Flint of the same type has the name in any letter case, when the name breaks the name rule, or when the name is the reserved word computer.

In the Computer Flint, the rename also renames the machine: the machine display name takes the new name. The new name uses letters, digits, and single spaces. The machine name, the word of addresses, stays the same. flint setup --machine-proper-name "<name>" does the same rename from any folder.

Change the Type

flint convert "My Notes" --to guide --about "@org/entity"
flint convert "My Notes" --to member --regarding my-org

flint convert changes the type of a Flint: flint, computer, guide, or member. The id does not change. A conversion to member needs --regarding <org>: the org that the Flint regards. A conversion to guide can take --about <address>: the entity that the Guide is about.

To see the plan without changes:

flint convert "My Notes" --to guide --dry-run

If a conversion stops part way, flint convert "My Notes" --abort returns it to its start.

Remove a Flint from the Roster

To remove the row and keep the files:

flint unregister /path/to/flint

In the Flint:

flint unregister

flint unregister asks for a confirmation. --yes (or --force) skips the question. --json asks no question, so it needs --yes.

To remove the row and the folder, use flint delete <name>. Give the exact name or the path of the Flint. With no argument, it deletes the Flint of the current folder. It deletes the files. It also:

asks you to type the name of the Flint to confirm; --force skips the question;
refuses when the vault is open in Obsidian, and names the command to run again;
for a member of a Tinderbox, asks again and removes the member from tinderbox.toml, so the next sync does not clone it again;
exports the Obsidian backups of the Flint before it deletes the folder: it copies them into the deleted scope of the backup store. When the export fails, it deletes nothing. It prints <n> Obsidian backups kept in the deleted scope. See: flint obsidian backups list --scope deleted;
removes the vault registry entry of Obsidian. When Obsidian runs, the change waits until you run flint obsidian vaults repair --yes with Obsidian quit.

Check and Repair

When a name does not resolve:

Run flint list --status.
Find the broken or missing row.
If the Flint folder exists, run flint register <path>.
Run flint registry check to compare the roster and the copy. It writes nothing. Run flint registry rebuild if the copy is out of date. flint registry rebuild --dry-run shows the plan without writes.
Run flint sync in the Flint.

The Roster Is Not Your Name

The roster lists Flints. It does not hold your Name. flint setup sets your Name and the machine names; flint config name "<Name>" changes your Name only; flint whoami shows them. Your Name is in the NUU config (~/.nuucognition/config.toml), and it is the same for every Flint on this machine. See Global Configuration.

The Roster

On this page