Configuration
Per-repository and organisation-level settings in the SaaS dashboard.
.kontrua.yml. See the CLI section.Context artifacts
The context section of the repo config controls the context layer - the artifacts AI coding agents read to work on your repository. AGENTS.md, the codemap, and conventions are enabled by default; architecture facts are opt-in. Each key takes enabled, output, and template.
| Key | Default | Output | What it contains |
|---|---|---|---|
| agentsMd | On | AGENTS.md | Agent orientation file at the repo root - what the project is, how to build, test, and navigate it |
| codemap | On | docs/CODEMAP.md | Modules, entry points, and dependencies |
| conventions | On | docs/CONVENTIONS.md | Observed code patterns with cited examples |
| architectureFacts | Off | docs/architecture.facts.json | Deterministic machine-readable facts extracted from the code - no LLM involved |
{
"context": {
"agentsMd": { "enabled": true, "output": "AGENTS.md", "template": "default" },
"codemap": { "enabled": true, "output": "docs/CODEMAP.md", "template": "default" },
"conventions": { "enabled": true, "output": "docs/CONVENTIONS.md", "template": "default" },
"architectureFacts": { "enabled": false, "output": "docs/architecture.facts.json" }
}
}Doc views
The legacy docs section configures the human-readable doc views - README, API reference, architecture, and changelog. They remain fully supported and are rendered from the same understanding of your code as the context artifacts. For each repository you can independently enable or disable each view, set the output file path, and assign a template.
| Setting | Description |
|---|---|
| Enabled | Whether this doc view runs on each trigger |
| Output path | Repository-relative path where the file is written (e.g. docs/api.md) |
| Template | Which template the agent uses to generate content |
Watch branch
The watch branch is the branch that triggers context runs. It defaults to the repository's default branch (main or master). Only events targeting this branch are processed. Change it in Dashboard - [repo] - Config.
Trigger mode
| Mode | When it fires |
|---|---|
| PR approved | When a pull request / merge request targeting the watch branch is approved |
| PR merged | When a pull request / merge request is merged into the watch branch |
| Manual only | Only when you click "Run now" in the dashboard or call the API trigger |
Repositories can additionally run on a schedule (daily, weekly, or monthly) via the schedule setting - useful as a safety net for changes that land outside the PR flow.
Organisation defaults
Default artifact settings and trigger mode apply to every new repository you connect. Configure them under Dashboard - Settings - Defaults so you don't have to reconfigure each repo from scratch.
Notion integration
Connect your Notion workspace under Settings - Integrations. Once connected, each doc view can be assigned a destination Notion page. Kontrua will sync the generated Markdown to that page after every successful run in addition to opening the GitHub / GitLab PR.
Ready to keep your repo's context current?
Connect your first repository and Kontrua opens a reviewed PR with AGENTS.md, a codemap, and your conventions.