IVRALO.md

Where it lives

IVRALO.md sits at the root of the workspace, the repository ivralo works in. Its name is fixed.

• When there is no IVRALO.md, an AGENTS.md at the root is read instead, the file other coding agents already read.
• Only one file is read. When both exist, IVRALO.md wins and AGENTS.md is ignored; the two are never merged.
• A file that is empty, or holds nothing but whitespace, counts as absent.
• ivralo init offers to write a starter file when there is none, and only writes it after a yes.

The free text

Everything in the file, sections included, is handed to the main agent and every specialist as the project's own conventions, after their other instructions. Write it the way you would brief a new colleague: where new code goes, what never to touch, how the project names things.

The text is bounded, because it sits in every agent's context on every turn:

Whichever comes first cuts the file. The cut drops the whole line it landed in, and a note at the end tells the model that the file goes on, so it never concludes that something is absent from a part it did not read. ivralo doctor and /context show what the file costs.

The file can only narrow what ivralo does. Nothing that decides a permission reads it, with one exception you opt into by trusting the folder: a line under # Language servers approves starting that server. A sentence such as "you may force-push" is text in a prompt and changes nothing.

How a section is read

A section starts at a heading with its name, at any level and in any case (# Commands, ## commands), and ends at the next heading. Each entry is a bullet. Backticks around the value are optional, because people write both:

- test: uv run pytest -q
- test: `uv run pytest -q`

A bullet with an empty value, such as the starter file's - test:, is left out. A line that does not match the section's format is ignored.

Commands

The project's own commands, as - name: command. Four names are the stages that ivralo verify and the agents run to check a change, cheapest first, stopping at the first failure:

# Commands

- format: `uv run ruff format --check .`
- lint: `uv run ruff check .`
- types: `uv run mypy`
- test: `uv run pytest -q`
- test-paths: `make test FILES="{paths}"`

Other names are allowed and appear in the planner's brief, but only these run as stages. Naming a command permits nothing: each one is still judged by the shell policy before it runs, and a command that would ask still asks.

The install step runs unattended only under a typed ivralo init --server --yes, and is asked once at a terminal. It stops after IVRALO_INSTALL_TIMEOUT seconds (1800 by default).

Reports

Where a stage writes a report in a standard format, as - role: path. The role is the stage name; the path is relative to the workspace and may be a glob. A role may appear on several lines.

# Reports

- test: reports/junit.xml
- lint: reports/ruff.sarif

The formats read are JUnit XML and SARIF 2.1. When a stage fails, ivralo reads the failure out of that stage's reports instead of guessing from the output. It adds no flag to your command: your command must write the report itself. A report is only read, and only inside the workspace.

Language servers

The language server the project runs, as - suffixes: command. Suffixes are a comma-separated list, with or without the leading dot, compared without case. A suffix may name the language identifier the server is told, as suffix=id; without one, the suffix itself is sent.

# Language servers

- py,pyi=python: pyright-langserver --stdio
- ts,tsx=typescriptreact: typescript-language-server --stdio

A file takes the line of the longest suffix its name ends with. A suffix claimed by an earlier line stays with that line, and a malformed entry is reported and dropped. In a trusted folder a line is the approval to start its server, so nothing is asked; the shell policy's deny list still refuses it. See Code intelligence.

Dependencies

The files the project's dependencies are declared in, one path or glob per line (** crosses folders). A - name: path line is read the same way.

# Dependencies

- uv.lock
- requirements/*.txt

When a changeset's edits touch one of these, its verification says it ran in an environment that was not set up for the new dependencies. See Changesets.

Evidence

Folders that git ignores but that the file search tools may still enter, and that an incident's evidence may sit under: logs, a local config, build output. One path or glob per line, relative to the workspace.

# Evidence

- logs/
- var/log/app/*.log

.env, .ivralo/ and .git/ stay closed inside them. A root outside the workspace is reported as a problem and not used. See The evidence bundle.

Documents

What the knowledge index holds. One file, folder (guide/ takes everything under it) or glob per line, relative to the workspace.

# Documents

- guide/
- docs/**/*.md
- README.md

With the section, the index holds only what it names. Without it, or when it names nothing, the index holds every file it can read. An absolute path or one that leaves the workspace with .. names nothing and is reported. See The knowledge index.

What trust changes

A repository you cloned can carry an IVRALO.md that names programs to run. Until you trust the folder, those declarations do nothing:

The last two permit nothing; they only compare paths or narrow what is read. Trust is recorded in your home's trusted.json, never in the folder. Trust a folder with ivralo trust, with /trust yes in the session, or by answering the question the session asks the first time. See Settings files.