Question 1

How do I connect a repository to a project?

Accepted Answer

Run mneia init in the repository root. It writes .mneia/config.json, imports the constraints already sitting in your AGENTS.md, CLAUDE.md, or .cursor/rules, and writes a generated section back into AGENTS.md inside a fence it owns.

Question 2

How do I authenticate a machine, or CI?

Accepted Answer

Interactively, mneia login writes a token to ~/.mneia/credentials. Non-interactively, set MNEIA_TOKEN in the environment — that is the path for CI and for an MCP client that starts the server without a shell.

Question 3

How do I see what the project already knows?

Accepted Answer

mneia brief "<what you are about to work on>" prints the rehydrated slice for that task. mneia log shows the decision history newest first, and mneia status shows what is stale, disputed, or unanswered.

Question 4

How do I record a decision without waiting for a checkpoint?

Accepted Answer

Call mneia_assert the moment it is settled. A checkpoint is for a batch at a boundary; assert is for the single decision you do not want to lose in the next hour.

Question 5

How do I correct something that is now wrong?

Accepted Answer

Supersede it rather than deleting it, by passing supersedesId on the replacement. The old item stays, marked superseded, which is what stops a fresh agent from proposing the approach the team already ruled out.

Question 6

How do I turn telemetry off?

Accepted Answer

Set MNEIA_TELEMETRY=off in the environment of the CLI or the MCP server. Any of off, false, no, none, or 0 works, and an unrecognised value is rejected loudly rather than silently leaving telemetry on.

Question 7

How do I point a client at a different API endpoint?

Accepted Answer

Set MNEIA_API_URL, or pass --endpoint to mneia init to persist it in .mneia/config.json. The default is https://api.mneia.dev.

Symptom	Why	Fix
`no Mneia project is bound to this directory`	There is no .mneia/config.json where the command ran, so nothing tells it which project it is talking about.	Run mneia init in the repository root. If the repository is already bound elsewhere and you mean to rebind it, add --force.
`no Mneia credentials found`	MNEIA_TOKEN is unset and ~/.mneia/credentials does not exist, so there is no token to authenticate with.	Run mneia login on a machine with a browser, or set MNEIA_TOKEN directly in CI and in your MCP client’s server configuration.
`MNEIA_TOKEN is set but empty`	The variable exists with a blank or whitespace value — usually an unresolved secret reference in CI, or a shell export that lost its value.	Set it to the token value alone: no Bearer prefix, no quotes, no trailing newline. Unsetting it entirely falls back to the credentials file, which is often what you want locally.
`the config file is not valid JSON, or a field is rejected`	A hand-edited .mneia/config.json. The file is validated on read, so a malformed binding fails immediately rather than half-working.	The error names the offending field. Fix that field, or delete the file and run mneia init to rewrite it.
`a command reports that it ships in a later milestone`	handoff and pickup ship in M2; conflicts ships in M4. The CLI refuses to pretend a surface exists before it does.	Run mneia --help for the commands this build supports. There is nothing to fix locally.
`the MCP server exits immediately on startup`	Configuration is resolved before the server accepts a connection, so a missing token or a malformed endpoint stops it there rather than failing on the first tool call.	The message names the variable at fault. MCP clients bury server stderr — check the client’s log pane before assuming the server is broken.
`a tool call comes back as an error rather than a result`	Arguments are validated before anything is read or written, so an invalid call changes nothing. Every failure carries a code, a summary, and a remedy.	Correct the arguments and call again. If the failure repeats with the same code, it is ours rather than yours — send it to security@mneia.dev if it looks like exposure, and otherwise report it with the code.
`you need the underlying stack trace`	The CLI prints a message and a fix rather than a stack, because a stack is rarely the useful part.	Set MNEIA_DEBUG=1 and re-run. Add --json to any command for machine-readable output, including the error shape.

Start here when something is not working.

Four ways in, depending on what you need.

New to Mneia

Connecting an agent

Day-to-day commands

Understanding the model

How do I…

What the error means, and what fixes it.

When the documentation does not cover it.