commands.get

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "The identity, `executable.worktree.status`."
    }
  },
  "required": [
    "id"
  ],
  "description": "One command, by its canonical identity.",
  "title": "CommandRequest"
}

{
  "type": "object",
  "properties": {
    "id": {
      "$ref": "#/$defs/CommandId",
      "description": "The canonical identity."
    },
    "origin": {
      "$ref": "#/$defs/CommandOrigin",
      "description": "Which program runs it."
    },
    "path": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The words after the program's own name."
    },
    "invocation": {
      "type": "string",
      "description": "The command line a person types, rendered once here."
    },
    "summary": {
      "type": "string",
      "description": "One line."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "The longer description, when the declaration carries one."
    },
    "runnable": {
      "type": "boolean",
      "description": "Can it be run on its own, or does it only group the commands under it?"
    },
    "arguments": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CommandArgument"
      },
      "description": "The arguments, in declaration order."
    },
    "execution": {
      "$ref": "#/$defs/CommandExecution",
      "description": "How it is run."
    },
    "effect": {
      "$ref": "#/$defs/CommandEffect",
      "description": "What it changes."
    },
    "interactivity": {
      "$ref": "#/$defs/CommandInteractivity",
      "description": "How it behaves towards a terminal."
    },
    "stability": {
      "$ref": "#/$defs/Stability",
      "description": "Where it stands."
    },
    "availability": {
      "$ref": "#/$defs/CommandAvailability",
      "description": "Where it means anything."
    },
    "group": {
      "type": [
        "string",
        "null"
      ],
      "description": "The group a person finds it under, when the declaration has groups."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Free tags."
    },
    "aliases": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Other names that resolve to this node, declared once here and honoured by every\nprojection that has a use for one."
    },
    "deprecation": {
      "anyOf": [
        {
          "$ref": "#/$defs/CommandDeprecation"
        },
        {
          "type": "null"
        }
      ],
      "description": "Whether this is still the name to use."
    },
    "provenance": {
      "$ref": "#/$defs/CommandProvenance",
      "description": "Where it came from."
    },
    "projections": {
      "$ref": "#/$defs/CommandProjections",
      "description": "Where it appears."
    },
    "entrypoint": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Is this command an entry point of its group — the one a newcomer is offered?"
    }
  },
  "required": [
    "id",
    "origin",
    "path",
    "invocation",
    "summary",
    "runnable",
    "arguments",
    "execution",
    "effect",
    "interactivity",
    "stability",
    "availability",
    "provenance",
    "projections"
  ],
  "description": "One command, from whichever program offers it.",
  "title": "CommandNode",
  "$defs": {
    "CommandId": {
      "type": "string",
      "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."
    },
    "CommandOrigin": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "description": "Which program runs a command. Part of the identity, because the three are different\nprograms that share one name on the path."
    },
    "CommandArgument": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The argument's id."
        },
        "long": {
          "type": [
            "string",
            "null"
          ],
          "description": "`--long`, without the dashes."
        },
        "short": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 1,
          "description": "`-s`, without the dash."
        },
        "positional": {
          "type": "boolean",
          "description": "Given by position rather than by flag."
        },
        "takes_value": {
          "type": "boolean",
          "description": "Takes a value at all; a flag does not."
        },
        "required": {
          "type": "boolean",
          "description": "Must be given."
        },
        "variadic": {
          "type": "boolean",
          "description": "Takes any number of values."
        },
        "global": {
          "type": "boolean",
          "description": "Accepted by every command under the one that declares it."
        },
        "help": {
          "type": "string",
          "description": "The help text, one line."
        },
        "value_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The placeholder, `PATH`."
        },
        "values": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CommandValueChoice"
          },
          "description": "The values the declaration carries, each with its help."
        },
        "defaults": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The defaults, as the declaration renders them."
        },
        "source": {
          "$ref": "#/$defs/CommandValueSource",
          "description": "Where further values come from."
        },
        "secrecy": {
          "$ref": "#/$defs/CommandSecrecy",
          "description": "How openly the value may be handled."
        }
      },
      "required": [
        "name",
        "positional",
        "takes_value",
        "required",
        "variadic",
        "global",
        "help",
        "source",
        "secrecy"
      ],
      "description": "One argument of a command, as the declaration gives it plus what can be inferred."
    },
    "CommandValueChoice": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string",
          "description": "The value as typed."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "Its help, when the declaration carries one."
        }
      },
      "required": [
        "value"
      ],
      "description": "One value an argument accepts, from the declaration."
    },
    "CommandValueSource": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "free"
            }
          },
          "required": [
            "kind"
          ],
          "description": "Nothing here knows the set; the caller types a value."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "enumerated"
            }
          },
          "required": [
            "kind"
          ],
          "description": "The declaration carries the values; they are on the argument."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "path"
            }
          },
          "required": [
            "kind"
          ],
          "description": "A path in the filesystem."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "repository_path"
            }
          },
          "required": [
            "kind"
          ],
          "description": "A path inside the repository."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "capability"
            }
          },
          "required": [
            "kind"
          ],
          "description": "A capability id, from the registry."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "command"
            }
          },
          "required": [
            "kind"
          ],
          "description": "A command id, from this graph."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "rule"
            }
          },
          "required": [
            "kind"
          ],
          "description": "A rule id, from the effective rule set."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "object_kind"
            }
          },
          "required": [
            "kind"
          ],
          "description": "An object kind, from the index."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "branch"
            }
          },
          "required": [
            "kind"
          ],
          "description": "A git branch in this repository."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "graph"
            }
          },
          "required": [
            "kind"
          ],
          "description": "A graph id, from the graph registry."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "moment"
            }
          },
          "required": [
            "kind"
          ],
          "description": "A moment id, from the why catalogue."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "shell"
            }
          },
          "required": [
            "kind"
          ],
          "description": "A shell name, from the shells the activation supports."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "secret"
            }
          },
          "required": [
            "kind"
          ],
          "description": "A secret. Never enumerated, never cached, never suggested."
        }
      ],
      "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."
    },
    "CommandSecrecy": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "description": "How openly a value may be handled."
    },
    "CommandExecution": {
      "type": "object",
      "properties": {
        "origin": {
          "$ref": "#/$defs/CommandOrigin",
          "description": "Which program."
        },
        "argv": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The words that precede the caller's arguments, the program's own name excluded."
        }
      },
      "required": [
        "origin",
        "argv"
      ],
      "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."
    },
    "CommandEffect": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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."
    },
    "CommandInteractivity": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "description": "How a command behaves towards the caller's terminal and the caller's patience."
    },
    "Stability": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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."
    },
    "CommandAvailability": {
      "type": "object",
      "properties": {
        "available": {
          "type": "boolean",
          "description": "Can it be run here, now?"
        },
        "reason": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why not, in one line, when it cannot."
        },
        "requires": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CommandRequirement"
          },
          "description": "What it needs, whether or not that is satisfied here."
        }
      },
      "required": [
        "available"
      ],
      "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`."
    },
    "CommandRequirement": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "description": "One thing a command needs before it can run."
    },
    "CommandDeprecation": {
      "type": "object",
      "properties": {
        "reason": {
          "type": "string",
          "description": "Why, in one line."
        },
        "replaced_by": {
          "anyOf": [
            {
              "$ref": "#/$defs/CommandId"
            },
            {
              "type": "null"
            }
          ],
          "description": "What to use instead."
        }
      },
      "required": [
        "reason"
      ],
      "description": "A command that is no longer the name to use."
    },
    "CommandProvenance": {
      "type": "object",
      "properties": {
        "declared_in": {
          "type": "string",
          "description": "The repository-relative file that declares it."
        },
        "read_by": {
          "type": [
            "string",
            "null"
          ],
          "description": "The command that reads that declaration, when a reader wants to reproduce it."
        },
        "capability": {
          "anyOf": [
            {
              "$ref": "#/$defs/CapabilityId"
            },
            {
              "type": "null"
            }
          ],
          "description": "The capability this command runs, when it runs one."
        }
      },
      "required": [
        "declared_in"
      ],
      "description": "Where a node came from, in enough detail to open the file."
    },
    "CapabilityId": {
      "type": "string",
      "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."
    },
    "CommandProjections": {
      "type": "object",
      "properties": {
        "cli": {
          "type": [
            "string",
            "null"
          ],
          "description": "The command line, as typed."
        },
        "workflow": {
          "type": [
            "string",
            "null"
          ],
          "description": "The generated workflow bridge's recipe name."
        },
        "mcp": {
          "type": [
            "string",
            "null"
          ],
          "description": "The MCP tool name, when the capability behind it declares one."
        },
        "http": {
          "type": [
            "string",
            "null"
          ],
          "description": "The HTTP route, when the capability behind it declares one."
        },
        "cockpit": {
          "type": [
            "string",
            "null"
          ],
          "description": "The Cockpit address, when the surface carries it."
        },
        "docs": {
          "type": "string",
          "description": "The page on the site. Every command has one."
        },
        "withheld": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why a machine surface does not carry it, when one does not."
        }
      },
      "required": [
        "docs"
      ],
      "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."
    }
  }
}