Understand a message from Kin.

Read the whole picture first

Summary: 27 passed, 1 need attention, 6 not applicable.

kin doctor checks the binary, the daemon, the repository, the graph, the projection, the shell hook, every detected AI client and the memory the daemon is allowed. Rows that pass are as informative as rows that do not: they tell you where not to look.

A row marked with an arrow is not applicable rather than broken. A row that needs attention carries its own fix line underneath it.

Kin says nothing calls it

No incoming Calls relations.

An empty incoming-Calls result says the current graph contains no incoming Calls edges for this entity. That does not establish that no callers exist in the source: the graph may still be incomplete for the languages involved.

Drop the --kind filter and ask again, since something may import or reference it without calling it. Then check readiness with kin graph status, and check kin languages for whether the calling code is in a language Kin extracts entities from.

Kin cannot find the entity at all

Error: Entity 'applyDiscount' not found in this repo's graph.

The name did not resolve. Commands fail closed here rather than returning an empty result that reads like a safe change.

Run kin search <name> for the real spelling. If the definition lives in another repository, kin refs and kin impact will not reach it: use kin xref.

History refuses instead of returning nothing

kin history refused (HTTP 500): No entity matching 'applyDiscount' found.

Entity history is resolved by the daemon, and a name it cannot resolve comes back as a refusal rather than an empty list.

Same fix: find the real name with kin search, then ask again.

A reference with no line to open

sites none (no_evidence_span)

Kin recorded a relationship but has no source span for it. Inspect the named files before relying on it.

Open the named file and read it. Do not treat the row as noise.

The first command after a while takes a few seconds

starting the kin daemon for this repository; the first query after a start waits for it to load the graph

The daemon for that repository was not running, so it started and loaded the graph before answering.

Wait for it. Later queries against the same repository answer from the loaded graph.

A command reports a gap in its own answer

Semantic scope: no live graph was reachable, so the entity and relation counts above are the admitted overlay's and cannot move for work in the working copy. That is a gap in this answer, not a statement that nothing changed; start the daemon, or commit and diff change to change.

kin diff without a running daemon answers from durable authority. It says what it could not measure rather than reporting that nothing changed, which is the failure it would otherwise look like.

Run any query to start the repository daemon, then ask again.

A note about role classification on a small repository

all entities are Source - role classification may not be working

A role heuristic had too little code to calibrate against. On a repository of a few files this is expected and it says nothing about the recorded edges.

Ignore it for caller, impact and history questions. Check the embedding and parse coverage lines in the same report instead.

Kin refuses to record a change

Error: config error: kin has no author identity to record for this change.

Authorship is provenance. A change attributed to nobody cannot support review attribution, blame or audit, and it cannot be corrected later without rewriting history, so Kin refuses to invent one.

Set git config user.name and user.email, or put default_author = "Your Name <you@example.com>" at the top of .kin/config.toml, above the first section.

git status stays dirty after you recorded a change

Recorded in Kin authority, not in git.

The change is in Kin authority and Git has not been asked to do anything.

Leave it while you evaluate, commit with Git as well if you want both moving together, or export a Git repository from Kin authority. The Git page covers all three.

Entity history is missing a change you made

The change went to Git. Kin history is built from semantic changes, and a git commit does not create one.

Record it with kin commit, then read the history again.

The shim is not installed

VFS projection             MISSING        shim not installed

Nothing else is broken. The CLI and the daemon answer from the graph with no projection in force.

kin doctor prints the exact copy command for this install underneath the row, and kin setup installs the shim as part of shell integration.

The shim is installed but not engaged in this shell

Projection in force        STALE

The shim is injected per process by a shell hook, not mounted, so a shell that started before the hook existed is reading raw disk rather than graph truth. The row says which of those it is.

Start a new interactive shell so the hook injects the shim, then run kin doctor there. A login shell that never runs its interactive startup file will not engage it.

Export refuses the destination

Git export destination ... is inside the Kin working repository

Export writes a new repository, so it will not write underneath the one it is reading from.

Give --output a sibling path outside the working repository.

Backup finds nothing to back up

Error: no graph snapshot found at .../.kin/kindb/graph.kndb

kin backup create works on a graph snapshot, and a store that has not written one has nothing for it to take.

During an evaluation, treat the Git repository you admitted from as the backup, and work on a disposable copy.

A warning that the daemon is degraded, while everything answers

daemon is up and serving but reports health=attention (degraded); continuing to use it. Run `kin doctor` for details.

The daemon is up and serving and says so. Degraded names a component that is not healthy, which on a fresh machine is usually the projection.

Run kin doctor and read the one row that needs attention.