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 and conventions are enabled by default; the codemap is opt-in; architecture facts are opt-in. Each key takes enabled and output. Missing enabled outputs can be generated. Existing files are audit only unless their exact paths are delegated for management. Generated content uses repository evidence and still needs review.

{
  "context": {
    "agentsMd":          { "enabled": true,  "output": "AGENTS.md" },
    "codemap":           { "enabled": false, "output": "docs/CODEMAP.md" },
    "conventions":       { "enabled": true,  "output": "docs/CONVENTIONS.md" },
    "architectureFacts": { "enabled": false, "output": "docs/architecture.facts.json" }
  }
}

Human docs#

The docs section configures the documents written for people. Kontrua treats them differently from the artifacts above. Existing README files are verify-only in the managed-output plan, while existing architecture and changelog outputs require explicit management delegation before regeneration. Review each proposed diff.

Choose each file's permission in Document permissions: Audit only checks supported references; Propose corrections permits targeted, reviewed edits; Managed generation delegates supported whole-document generation. Audit only overrides prior settings and generation history. Existing README, API, CLAUDE.md and Copilot instructions support audits and targeted corrections, not whole-document regeneration. Authorship is independent of permission; imported files are not labeled as AI-written.

ownership:
  files:
    AGENTS.md: audit
    README.md: corrections
    docs/CODEMAP.md: managed

Legacy managedPaths and correctionPaths are still read when no per-file choice exists. Clear them to return existing files to Audit only. An anchors sidecar records generation provenance; it never grants edit permission. Enabled missing outputs may be created unless their per-file mode is Audit only or Propose corrections.

Watch branch and triggers#

The watch branch is the branch that gates correction runs. It defaults to the repository's default branch (main or master). An approval only starts a run when the pull request targets this branch. Change it on the repository page in the dashboard.

Repositories can additionally run on a schedule (daily, weekly on Mondays, or monthly on the 1st) via the schedule setting - useful as a safety net for changes that land outside the pull request flow. Each scheduled run counts against your monthly allowance. Scheduling needs a paid plan; public repositories get it on any plan.

Organisation defaults#

Which human documents are enabled, and where they are written, can be set once for 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. Kontrua sends you through Notion's OAuth flow and stores the resulting access token encrypted, at the organisation level. It is available on every plan, including Free.

Once connected, each document in the docs section can be given a destination page, picked from the 50 most recently edited pages your Notion authorisation covers. After a run that regenerated that document, Kontrua converts its Markdown to Notion blocks, appends them to the page and deletes the blocks that were there before, so the page ends up holding the new version. The sync is one-way and page-level: it replaces the body of the pages you selected, it never creates pages, and it never reads Notion back into your repository. Documents with no page assigned are not sent anywhere. It runs in addition to the GitHub or GitLab pull request, never instead of it, and a Notion failure is logged without failing the run.