commands.graph

The graph as one document, with its fingerprint and every diagnostic its build found: a duplicate identity, a recipe name two commands would take, an annotation that names a command which no longer exists. Deterministic — two builds over one tree produce the same document — so a client may cache against the fingerprint.

query
implemented
module commands
#commands
#introspection
#diagnostics

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surface	as
MCP	tool majordomus_command_graph
HTTP	GET /api/v1/commands/graph operationId commands.graph
command line	—

Schemas

The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.

input · Empty

No input.

No properties: the capability takes no input.

JSON Schema

{
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty",
  "type": "object"
}

output · CommandGraphReport

The whole graph, with what its build found.

property	type	required	description
errors	integer	yes	How many findings are errors; a projection refuses to write while this is not zero.
graph	reference	yes	The graph.

JSON Schema

{
  "$defs": {
    "CapabilityId": {
      "description": "A stable, globally meaningful identity: a namespace, a dot, and a local part.\n`repository.info` and `objects.get` for executables; `<kind>.<identity>` for a\ndeclarative object (`rule.majordomus.scope-integrity@1`, `document.docs/CLI.md`,\n`policy..ai/repo/policy.yaml`).\n\nGrammar: the namespace matches `[a-z][a-z0-9_-]*`; the local part is non-empty and\ncarries no whitespace or control character, any other Unicode included, because it is\nopaque: a path, a versioned identity, or a name, as the kind's identity rule produced it.",
      "type": "string"
    },
    "CommandArgument": {
      "description": "One argument of a command, as the declaration gives it plus what can be inferred.",
      "properties": {
        "defaults": {
          "description": "The defaults, as the declaration renders them.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "global": {
          "description": "Accepted by every command under the one that declares it.",
          "type": "boolean"
        },
        "help": {
          "description": "The help text, one line.",
          "type": "string"
        },
        "long": {
          "description": "`--long`, without the dashes.",
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "description": "The argument's id.",
          "type": "string"
        },
        "positional": {
          "description": "Given by position rather than by flag.",
          "type": "boolean"
        },
        "required": {
          "description": "Must be given.",
          "type": "boolean"
        },
        "secrecy": {
          "$ref": "#/$defs/CommandSecrecy",
          "description": "How openly the value may be handled."
        },
        "short": {
          "description": "`-s`, without the dash.",
          "maxLength": 1,
          "minLength": 1,
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "$ref": "#/$defs/CommandValueSource",
          "description": "Where further values come from."
        },
        "takes_value": {
          "description": "Takes a value at all; a flag does not.",
          "type": "boolean"
        },
        "value_name": {
          "description": "The placeholder, `PATH`.",
          "type": [
            "string",
            "null"
          ]
        },
        "values": {
          "description": "The values the declaration carries, each with its help.",
          "items": {
            "$ref": "#/$defs/CommandValueChoice"
          },
          "type": "array"
        },
        "variadic": {
          "description": "Takes any number of values.",
          "type": "boolean"
        }
      },
      "required": [
        "name",
        "positional",
        "takes_value",
        "required",
        "variadic",
        "global",
        "help",
        "source",
        "secrecy"
      ],
      "type": "object"
    },
    "CommandAvailability": {
      "description": "Where a command means anything, and why not when it does not.\n\nDerived from the repository environment rather than declared per command, so that a\nprojection reads a field instead of re-deciding. The reason is carried because the\nanswer a person needs is never `false`.",
      "properties": {
        "available": {
          "description": "Can it be run here, now?",
          "type": "boolean"
        },
        "reason": {
          "description": "Why not, in one line, when it cannot.",
          "type": [
            "string",
            "null"
          ]
        },
        "requires": {
          "description": "What it needs, whether or not that is satisfied here.",
          "items": {
            "$ref": "#/$defs/CommandRequirement"
          },
          "type": "array"
        }
      },
      "required": [
        "available"
      ],
      "type": "object"
    },
    "CommandDeprecation": {
      "description": "A command that is no longer the name to use.",
      "properties": {
        "reason": {
          "description": "Why, in one line.",
          "type": "string"
        },
        "replaced_by": {
          "anyOf": [
            {
              "$ref": "#/$defs/CommandId"
            },
            {
              "type": "null"
            }
          ],
          "description": "What to use instead."
        }
      },
      "required": [
        "reason"
      ],
      "type": "object"
    },
    "CommandDiagnostic": {
      "description": "One thing the build found.",
      "properties": {
        "code": {
          "description": "A stable code, for a gate to match on.",
          "type": "string"
        },
        "commands": {
          "description": "The nodes it is about.",
          "items": {
            "$ref": "#/$defs/CommandId"
          },
          "type": "array"
        },
        "message": {
          "description": "What is wrong, in one line.",
          "type": "string"
        },
        "remedy": {
          "description": "What to do about it.",
          "type": [
            "string",
            "null"
          ]
        },
        "severity": {
          "$ref": "#/$defs/CommandDiagnosticSeverity",
          "description": "How bad."
        }
      },
      "required": [
        "severity",
        "code",
        "message"
      ],
      "type": "object"
    },
    "CommandDiagnosticSeverity": {
      "description": "How bad a finding is.",
      "oneOf": [
        {
          "const": "error",
          "description": "The graph is wrong and a projection built from it would be wrong.",
          "type": "string"
        },
        {
          "const": "warning",
          "description": "Worth saying; the graph stands.",
          "type": "string"
        },
        {
          "const": "info",
          "description": "A fact a reader may want.",
          "type": "string"
        }
      ]
    },
    "CommandEffect": {
      "description": "What running a command changes. The one thing a surface policy is allowed to ask.\n\nThe order is the order of increasing consequence, and it is the order the derived\nexposure policy reads: a surface declares the strongest effect it will carry, and\nevery node at or below it is projected there. Nothing configures a surface per\ncommand.",
      "oneOf": [
        {
          "const": "read_only",
          "description": "Reads and answers. Changes nothing anywhere.",
          "type": "string"
        },
        {
          "const": "local_mutation",
          "description": "Writes only where the repository keeps a checkout's own state — the process's\nmemory, `.ai/local/`, a build directory. Nothing a commit would carry.",
          "type": "string"
        },
        {
          "const": "repository_mutation",
          "description": "Writes tracked files: generated artifacts, the worktree, git itself.",
          "type": "string"
        },
        {
          "const": "network_mutation",
          "description": "Reaches the network with an effect on the far side: a push, a deploy, a release.",
          "type": "string"
        },
        {
          "const": "destructive",
          "description": "Removes something a person would have to reconstruct.",
          "type": "string"
        }
      ]
    },
    "CommandExecution": {
      "description": "How a command is actually run: the program and the words before the caller's own.\n\nThis is what forbids a cycle. A projection renders an invocation from the execution\ndescriptor, so a generated bridge always spells the *canonical* program — never the\nsurface it is a bridge for.",
      "properties": {
        "argv": {
          "description": "The words that precede the caller's arguments, the program's own name excluded.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "origin": {
          "$ref": "#/$defs/CommandOrigin",
          "description": "Which program."
        }
      },
      "required": [
        "origin",
        "argv"
      ],
      "type": "object"
    },
    "CommandGraph": {
      "description": "The whole graph.",
      "properties": {
        "commands": {
          "description": "Every command, in a deterministic order: origin, then path.",
          "items": {
            "$ref": "#/$defs/CommandNode"
          },
          "type": "array"
        },
        "diagnostics": {
          "description": "What the build found.",
          "items": {
            "$ref": "#/$defs/CommandDiagnostic"
          },
          "type": "array"
        },
        "fingerprint": {
          "description": "A hash of the semantic content: the identity a cache and a generated projection\nkey on. Nothing that varies between two runs over the same tree is in it.",
          "type": "string"
        },
        "schema": {
          "description": "The schema of this document.",
          "type": "string"
        }
      },
      "required": [
        "schema",
        "fingerprint",
        "commands",
        "diagnostics"
      ],
      "type": "object"
    },
    "CommandId": {
      "description": "The canonical identity of one command.\n\nConstructed from the origin and the command path, never written by hand, so that a\nprojection cannot invent one and a rename of a display string cannot change one.",
      "type": "string"
    },
    "CommandInteractivity": {
      "description": "How a command behaves towards the caller's terminal and the caller's patience.",
      "oneOf": [
        {
          "const": "non_interactive",
          "description": "Runs, answers, exits. Safe to call from a machine surface.",
          "type": "string"
        },
        {
          "const": "interactive",
          "description": "Asks the person something, or reads the body of a record from a terminal. A\nmachine surface that offered it would hang.",
          "type": "string"
        },
        {
          "const": "long_running",
          "description": "Serves until it is stopped. A request/response surface cannot carry it.",
          "type": "string"
        }
      ]
    },
    "CommandNode": {
      "description": "One command, from whichever program offers it.",
      "properties": {
        "aliases": {
          "description": "Other names that resolve to this node, declared once here and honoured by every\nprojection that has a use for one.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "arguments": {
          "description": "The arguments, in declaration order.",
          "items": {
            "$ref": "#/$defs/CommandArgument"
          },
          "type": "array"
        },
        "availability": {
          "$ref": "#/$defs/CommandAvailability",
          "description": "Where it means anything."
        },
        "deprecation": {
          "anyOf": [
            {
              "$ref": "#/$defs/CommandDeprecation"
            },
            {
              "type": "null"
            }
          ],
          "description": "Whether this is still the name to use."
        },
        "description": {
          "description": "The longer description, when the declaration carries one.",
          "type": [
            "string",
            "null"
          ]
        },
        "effect": {
          "$ref": "#/$defs/CommandEffect",
          "description": "What it changes."
        },
        "entrypoint": {
          "description": "Is this command an entry point of its group — the one a newcomer is offered?",
          "type": [
            "boolean",
            "null"
          ]
        },
        "execution": {
          "$ref": "#/$defs/CommandExecution",
          "description": "How it is run."
        },
        "group": {
          "description": "The group a person finds it under, when the declaration has groups.",
          "type": [
            "string",
            "null"
          ]
        },
        "id": {
          "$ref": "#/$defs/CommandId",
          "description": "The canonical identity."
        },
        "interactivity": {
          "$ref": "#/$defs/CommandInteractivity",
          "description": "How it behaves towards a terminal."
        },
        "invocation": {
          "description": "The command line a person types, rendered once here.",
          "type": "string"
        },
        "origin": {
          "$ref": "#/$defs/CommandOrigin",
          "description": "Which program runs it."
        },
        "path": {
          "description": "The words after the program's own name.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "projections": {
          "$ref": "#/$defs/CommandProjections",
          "description": "Where it appears."
        },
        "provenance": {
          "$ref": "#/$defs/CommandProvenance",
          "description": "Where it came from."
        },
        "runnable": {
          "description": "Can it be run on its own, or does it only group the commands under it?",
          "type": "boolean"
        },
        "stability": {
          "$ref": "#/$defs/Stability",
          "description": "Where it stands."
        },
        "summary": {
          "description": "One line.",
          "type": "string"
        },
        "tags": {
          "description": "Free tags.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "id",
        "origin",
        "path",
        "invocation",
        "summary",
        "runnable",
        "arguments",
        "execution",
        "effect",
        "interactivity",
        "stability",
        "availability",
        "provenance",
        "projections"
      ],
      "type": "object"
    },
    "CommandOrigin": {
      "description": "Which program runs a command. Part of the identity, because the three are different\nprograms that share one name on the path.",
      "oneOf": [
        {
          "const": "executable",
          "description": "The Rust executable, `apps/majordomus-cli`: the read-only interfaces, generation,\nintrospection, the servers. Declared by clap.",
          "type": "string"
        },
        {
          "const": "tool",
          "description": "The shell tool, `bin/majordomus`: the task lifecycle. Declared by the shipped\ncommand registry and dispatched by the tool itself.",
          "type": "string"
        },
        {
          "const": "workflow",
          "description": "A workflow the repository declares for a person to run — a `just` recipe that is\nnot a generated bridge. Declared by the justfile and read from the runner's dump.",
          "type": "string"
        }
      ]
    },
    "CommandProjections": {
      "description": "Where one command appears, derived from its effect, its interactivity and its origin.\n\nEvery field is computed by [`super::policy`]. Nothing declares a projection, and no\nsurface keeps a list of what it carries: a surface asks the graph.",
      "properties": {
        "cli": {
          "description": "The command line, as typed.",
          "type": [
            "string",
            "null"
          ]
        },
        "cockpit": {
          "description": "The Cockpit address, when the surface carries it.",
          "type": [
            "string",
            "null"
          ]
        },
        "docs": {
          "description": "The page on the site. Every command has one.",
          "type": "string"
        },
        "http": {
          "description": "The HTTP route, when the capability behind it declares one.",
          "type": [
            "string",
            "null"
          ]
        },
        "mcp": {
          "description": "The MCP tool name, when the capability behind it declares one.",
          "type": [
            "string",
            "null"
          ]
        },
        "withheld": {
          "description": "Why a machine surface does not carry it, when one does not.",
          "type": [
            "string",
            "null"
          ]
        },
        "workflow": {
          "description": "The generated workflow bridge's recipe name.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "docs"
      ],
      "type": "object"
    },
    "CommandProvenance": {
      "description": "Where a node came from, in enough detail to open the file.",
      "properties": {
        "capability": {
          "anyOf": [
            {
              "$ref": "#/$defs/CapabilityId"
            },
            {
              "type": "null"
            }
          ],
          "description": "The capability this command runs, when it runs one."
        },
        "declared_in": {
          "description": "The repository-relative file that declares it.",
          "type": "string"
        },
        "read_by": {
          "description": "The command that reads that declaration, when a reader wants to reproduce it.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "declared_in"
      ],
      "type": "object"
    },
    "CommandRequirement": {
      "description": "One thing a command needs before it can run.",
      "oneOf": [
        {
          "const": "repository",
          "description": "A git repository.",
          "type": "string"
        },
        {
          "const": "layer",
          "description": "The `.ai/` layer, initialised.",
          "type": "string"
        },
        {
          "const": "task",
          "description": "An active task record.",
          "type": "string"
        },
        {
          "const": "executable",
          "description": "The Rust executable, built.",
          "type": "string"
        },
        {
          "const": "workflow_runner",
          "description": "The workflow runner, installed.",
          "type": "string"
        },
        {
          "const": "rust_toolchain",
          "description": "A cargo workspace and a toolchain to build it.",
          "type": "string"
        },
        {
          "const": "site",
          "description": "The site sources and its generator.",
          "type": "string"
        }
      ]
    },
    "CommandSecrecy": {
      "description": "How openly a value may be handled.",
      "oneOf": [
        {
          "const": "public",
          "description": "Ordinary: may be logged, completed, shown.",
          "type": "string"
        },
        {
          "const": "sensitive",
          "description": "A path or an identifier that names something private. Shown, never logged.",
          "type": "string"
        },
        {
          "const": "secret",
          "description": "A credential. Never completed, never logged, never cached.",
          "type": "string"
        }
      ]
    },
    "CommandValueChoice": {
      "description": "One value an argument accepts, from the declaration.",
      "properties": {
        "description": {
          "description": "Its help, when the declaration carries one.",
          "type": [
            "string",
            "null"
          ]
        },
        "value": {
          "description": "The value as typed.",
          "type": "string"
        }
      },
      "required": [
        "value"
      ],
      "type": "object"
    },
    "CommandValueSource": {
      "description": "Where a value for an argument comes from, when something in this repository knows the\nset.\n\nThis is the completion contract, and it is a property of the *argument*, not of a shell\nscript: the same source answers a shell's TAB, a generated form's select and a machine\nsurface's enumeration of what it will accept. Inference from the declaration comes\nfirst — a value-enum argument carries its own values, a `PATH` placeholder is a path —\nand only what cannot be inferred is annotated beside the command.",
      "oneOf": [
        {
          "description": "Nothing here knows the set; the caller types a value.",
          "properties": {
            "kind": {
              "const": "free",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "The declaration carries the values; they are on the argument.",
          "properties": {
            "kind": {
              "const": "enumerated",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A path in the filesystem.",
          "properties": {
            "kind": {
              "const": "path",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A path inside the repository.",
          "properties": {
            "kind": {
              "const": "repository_path",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A capability id, from the registry.",
          "properties": {
            "kind": {
              "const": "capability",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A command id, from this graph.",
          "properties": {
            "kind": {
              "const": "command",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A rule id, from the effective rule set.",
          "properties": {
            "kind": {
              "const": "rule",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "An object kind, from the index.",
          "properties": {
            "kind": {
              "const": "object_kind",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A git branch in this repository.",
          "properties": {
            "kind": {
              "const": "branch",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A graph id, from the graph registry.",
          "properties": {
            "kind": {
              "const": "graph",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A moment id, from the why catalogue.",
          "properties": {
            "kind": {
              "const": "moment",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A shell name, from the shells the activation supports.",
          "properties": {
            "kind": {
              "const": "shell",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A secret. Never enumerated, never cached, never suggested.",
          "properties": {
            "kind": {
              "const": "secret",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        }
      ]
    },
    "Stability": {
      "description": "Where a capability stands, in the repository's own vocabulary for claims. A capability\nthat is `Planned` or `Unsupported` may be listed but is never executable through any\nprojection; the registry refuses to build otherwise.",
      "oneOf": [
        {
          "const": "implemented",
          "description": "Implemented, and no behavioural test names it yet.",
          "type": "string"
        },
        {
          "const": "behaviorally_verified",
          "description": "Implemented and proved by a behavioural test.",
          "type": "string"
        },
        {
          "const": "experimental",
          "description": "Implemented, executable, and expected to change.",
          "type": "string"
        },
        {
          "const": "planned",
          "description": "Specified and not implemented: listed, never executable.",
          "type": "string"
        },
        {
          "const": "unsupported",
          "description": "Considered and refused: listed with the reason, never executable.",
          "type": "string"
        }
      ]
    }
  },
  "description": "The whole graph, with what its build found.",
  "properties": {
    "errors": {
      "description": "How many findings are errors; a projection refuses to write while this is not zero.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "graph": {
      "$ref": "#/$defs/CommandGraph",
      "description": "The graph."
    }
  },
  "required": [
    "graph",
    "errors"
  ],
  "title": "CommandGraphReport",
  "type": "object"
}

Policies

benchmark: required — a target on every transport the exposure declares; the cases are the input type's
cache: disabled — every call runs the handler

Benchmark targets

Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.

transport	state	cases	targets
direct	covered	1	default
mcp	covered	1	default
http	covered	1	default