An item didn’t show up in ~/.claude. Run mind introspect; it reports
missing links and drift, and mind introspect --fix recreates missing
symlinks.
learn refused to overwrite a path. mind will not clobber a file or link it
did not create (the clobber guard). Move the existing one aside, then learn
again.
Two sources ship an item with the same name. Namespace one with mind meld <repo> --namespace <prefix>, so its items install as <prefix>:<name>. See
examples/namespacing/.
Where things live: see Configuration. Override the
roots with MIND_HOME and CLAUDE_HOME.
Before publishing a source, run mind review <path> to check its mind.toml,
item kinds, {{ns:}} references, and pin directive. See
Authoring a source.
Stuck in the TUI. Press q in the main view, or Ctrl-C twice from anywhere
(search box, dialogs) to force exit.
A mind.toml change is rejected as a parse error. The file is strict
(deny_unknown_fields), so a misspelled key is a hard error, not silently
ignored (DSC-30). Common near-misses: pin keys are hyphenated
(follow-branch, pin-tag, pin-ref), not underscored; min-mind-version
likewise uses a hyphen; and entry keys under [discover].sources are exact
(DSC-31). Run mind review <path> to check the file before melding.
A source’s items are not discovered after setting roots in mind.toml.
roots = [] (an explicit empty list) is distinct from omitting the key: it
scans zero roots and finds nothing. Omitting roots (or removing the key)
keeps the default behavior of scanning the repo root (DSC-50). Set the actual
subdirectory paths, or remove roots entirely.
learn reports LinkOccupied and refuses to overwrite. The clobber guard
will not replace a path that mind did not create (LIFE-41). Move the existing
file aside, then learn again, or pass learn --force (CLI-35) to replace
it unconditionally. Note: on non-unix platforms mind cannot always recognize
its own copies (symlink ownership is not detectable), so a reinstall or
upgrade may report LinkOccupied for items mind did install; this is a
documented platform limitation (see the lifecycle.md platform note).
An item shows as out of date in recall/probe without an upstream change.
Editing a store or source file by hand changes its content hash; mind compares
source-content hashes and reports the delta as drift (LIFE-33, CLI-75). Either
re-sync and then upgrade the item, or restore the edited file to its
original content. See Configuration for where store and
source files live.
meld or sync fails with “git executable not found”. mind shells out to
git for all clone and fetch operations; put git on your PATH first. See
the Install page.
A skill links to a Gemini or Codex lobe but a rule does not. Rules have no
cross-harness directory equivalent and are Claude-only (HARN-3). Only skills
and agents are linked into non-Claude lobes. If the lobe was added via a
preset, this is expected; rules remain in ~/.claude only.
An agent’s tool permissions don’t work in Gemini or Codex after linking. mind
links files verbatim and does not rewrite frontmatter. A skill or agent whose
frontmatter uses Claude-specific keys (e.g. the tools: allow-list schema)
will link correctly but those keys may be ignored or produce a warning in the
target harness. Adapt the frontmatter for the target harness by hand (HARN-6).
See Configuration.