env-contract.json

{
  "_comment": "Declarative contract for structural environment expectations. Read by scripts/doctor.{sh,ps1} to verify (and optionally fix) drift on a running install. v1 covers structural paths only; tooling-required vars and version pins live in versions.conf and sensitive/env-mapping.conf.",
  "env_vars": [
    {
      "name": "DOTFILES_DIR",
      "required": true,
      "description": "Stable install location of dotfiles deployed by setup-linux.sh. Used by healthcheck and shell profiles.",
      "default": {
        "linux": "$HOME/.dotfiles",
        "windows": "$env:USERPROFILE\\.dotfiles"
      },
      "validation": "path_exists"
    },
    {
      "name": "CLAUDE_CONFIG_DIR",
      "required": false,
      "description": "Override for Claude Code's config dir. When unset, ~/.claude is assumed. Used by claude-mem-heal to locate the plugin cache.",
      "default": {
        "linux": "$HOME/.claude",
        "windows": "$env:USERPROFILE\\.claude"
      },
      "validation": "path_exists"
    },
    {
      "name": "HOME",
      "required_on": "linux",
      "description": "POSIX home directory. OS-provided; validated as a real directory.",
      "validation": "path_exists"
    },
    {
      "name": "USERPROFILE",
      "required_on": "windows",
      "description": "Windows home directory. OS-provided; validated as a real directory.",
      "validation": "path_exists"
    }
  ],
  "required_path_entries": {
    "linux": [
      "$HOME/.dotfiles/scripts",
      "$HOME/.local/bin"
    ],
    "windows": [
      "$env:USERPROFILE\\scripts",
      "$env:USERPROFILE\\.local\\bin"
    ]
  },
  "required_binaries": [
    {
      "name": "git",
      "required": true,
      "min_version": "2.30.0",
      "version_pattern": "git version ([0-9]+\\.[0-9]+\\.[0-9]+)"
    },
    {
      "name": "jq",
      "required": true,
      "min_version": "1.6",
      "_pattern_note": "regex must be valid in both bash ERE (no `(?:..)`) and .NET; capture group 1 holds the version. Group 2 is intentionally captured-but-unused for the optional patch component.",
      "version_pattern": "jq-?([0-9]+\\.[0-9]+(\\.[0-9]+)?)"
    }
  ],
  "optional_binaries": [
    { "name": "claude", "purpose": "Claude Code CLI (MCP registration, plugins)" },
    { "name": "npx", "purpose": "MCP server stdio transports" },
    { "name": "npm", "purpose": "claude-mem-heal zod install" },
    { "name": "age", "purpose": "secrets encryption" },
    { "name": "gh", "purpose": "GitHub CLI (PR/issue management; Copilot CLI is the standalone `copilot` binary, not a gh extension since BUG-003)" },
    { "name": "copilot", "purpose": "GitHub Copilot CLI (agentic assistant; winget GitHub.Copilot on Windows, manual install on Linux)" },
    { "name": "uv", "purpose": "Python tool installs (hive-vault, general Python workflows)" }
  ]
}