clarx-manifest.json

The manifest is an optional file at the repo root that lets a repository declare its own structure to the Clarx engine. The more fields provided, the higher the confidence level of the analysis.

Why it exists

Many of the most important AI-navigability signals are not inferable from code alone:

• Which directories are generated (and should not be edited)
• What each workspace or package owns
• Where common changes belong
• Which files have high fan-in and are risky to modify
• How to verify changes

The manifest is the contract between the repo and the analysis engine.

Format

{
  "version": "0.1",
  "generated": [
    "apps/docs/.source",
    "apps/docs/.next",
    "**/dist",
    "**/node_modules"
  ],
  "workspaces": {
    "packages/ui": "Semantic UI component library",
    "packages/engine": "Codebase analysis engine",
    "packages/cli": "CLI tool wrapping engine"
  },
  "highFanIn": [
    "packages/ui/src/tokens.ts",
    "apps/docs/lib/mdx-components.ts"
  ],
  "highFanOut": [
    "apps/docs/lib/mdx-components.ts"
  ],
  "verificationCommands": {
    "typecheck": "pnpm typecheck",
    "test": "pnpm test",
    "lint": "pnpm lint"
  },
  "commonTasks": {
    "add a component": "packages/ui/src/ — follow badge.tsx pattern",
    "add a doc page": "apps/docs/content/docs/ — register in meta.json"
  }
}

All fields are optional.

Fields

Rule codes like C3 appear throughout — hover any of them for a plain-language explanation, or click through to the full definition.

version

The manifest schema version. Currently "0.1".

generated

Folders and files that are built or generated rather than written by hand — things like dist/, .next/, or coverage reports. Clarx skips them when scoring, and AI agents learn not to edit them (the next build would just overwrite their work). Declaring these satisfies O2 and helps resolve C1.

workspaces

One line per package saying what it's for — e.g. "packages/ui": "Semantic UI component library". This is how someone (or some agent) skimming the repo learns what each part owns without opening files. If you'd rather not maintain a README in every package, declaring purposes here satisfies D2 too.

highFanIn

The load-bearing files of your codebase — ones that many other files import, where a small change can quietly break callers all over the repo. You don't have to find them yourself: run clarx score and copy the paths from the C4 finding, which lists each file with its caller count. Once declared, every agent knows to tread carefully there. Files inside ui/ folders are exempt automatically — shared buttons and inputs are supposed to have many callers.

highFanOut

Files that import from lots of places on purpose — deliberate hubs like a Server Actions file, an MDX component registry, or an API coordination layer. Clarx normally flags files with a very large import list (C3), because they're usually doing too many jobs at once. If one of yours is a hub by design, declare it here and the warning goes away. Common hub filenames (actions.ts, mutations.ts, handlers.ts, …) and index files that only gather their own folder's contents are already exempt automatically.

verificationCommands

The commands that prove a change works — typecheck, test, and lint. With these declared, an agent can check its own work instead of guessing (or asking you). Satisfies O3.

commonTasks

A map from everyday tasks to where that work happens in your repo, so nobody has to guess. Satisfies O4. Examples:

• "add a component" → where component files live
• "add an API route" → where route handlers live
• "add a migration" → where database migrations live

thresholds

The standard's rules use numeric limits — lines per file, imports per file, and so on. If a default doesn't fit your repo's reality, override it here instead of living with a warning you disagree with. For example, a repo with legitimately large files can raise the C2 line limit:

{
  "thresholds": {
    "c2FileLines": 500,
    "c3ImportLimit": 20
  }
}

Available keys (defaults in parentheses): d1RootEntries (10), d1RootEntriesNextjs (17), d1RootEntriesMonorepo (20), d4MinLines (30), c2FileLines (400), c2FileLinesHard (600), c3ImportLimit (15), c4FanInThreshold (10), c5ImportDepth (8), c6ImportThreshold (8), c6InfraThreshold (2), e1RouteFileLines (300), e3UtilityExports (20).

Only finite positive numbers are honored — a malformed override can never disable a rule. Each default's rationale is documented in the engine's thresholds.ts; overrides are per-repo tuning, not a change to the standard itself.

Confidence impact

Adding a clarx-manifest.json with at minimum generated and verificationCommands is the fastest single action that raises both the confidence level and the Operational Guidance pillar score.

Initializing a manifest

Run clarx init to generate a starter manifest based on your repo structure:

npx @clarxai/cli init

The command detects common patterns (Next.js, Turborepo, Vite, etc.) and pre-fills what it can. Review and commit the result.