agent-first-data 0.28.1

A naming convention that lets AI agents understand your data without being told what it means, plus a CLI and library for reading and safely editing structured JSON, TOML, YAML, dotenv, and INI documents.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agentfirstkit.org/schemas/agent-first-data/cli-help-v2.schema.json",
  "title": "AFDATA CLI help v2 event",
  "description": "One command's complete invocation help, carried by an AFDATA result event. Domain outcomes, side effects, and runtime error catalogs remain in the owning tool's documentation.",
  "type": "object",
  "required": [
    "kind",
    "result",
    "trace"
  ],
  "additionalProperties": false,
  "properties": {
    "kind": {
      "const": "result"
    },
    "result": {
      "type": "object",
      "required": [
        "code",
        "help"
      ],
      "additionalProperties": false,
      "properties": {
        "code": {
          "const": "help"
        },
        "help": {
          "$ref": "#/$defs/help"
        }
      }
    },
    "trace": {
      "type": "object"
    }
  },
  "$defs": {
    "oneLine": {
      "type": "string",
      "minLength": 1,
      "pattern": "^[^\\n\\r]+$"
    },
    "nonEmptyStringMap": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": {
        "type": "string",
        "minLength": 1
      }
    },
    "help": {
      "type": "object",
      "required": [
        "schema",
        "command_path"
      ],
      "additionalProperties": false,
      "properties": {
        "schema": {
          "const": "cli-help-v2"
        },
        "command_path": {
          "$ref": "#/$defs/oneLine"
        },
        "about": {
          "$ref": "#/$defs/oneLine"
        },
        "shapes": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/shape"
          },
          "description": "Every legal shape of this command, each complete. Help answers in one round trip; a second level could only pay off by omitting the optional arguments, which would then be undiscoverable."
        },
        "subcommands": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/oneLine"
          }
        },
        "notes": {
          "$ref": "#/$defs/nonEmptyStringMap",
          "description": "Argument meanings. Arguments belong to the command rather than to one shape, so they are stated once."
        },
        "defaults": {
          "type": "object",
          "minProperties": 1,
          "additionalProperties": true
        }
      }
    },
    "shape": {
      "type": "object",
      "required": [
        "id",
        "usage"
      ],
      "additionalProperties": false,
      "properties": {
        "id": {
          "$ref": "#/$defs/oneLine"
        },
        "about": {
          "$ref": "#/$defs/oneLine",
          "description": "How this shape differs from its siblings. Absent when the command has only one shape, because its own description already covers it."
        },
        "usage": {
          "$ref": "#/$defs/oneLine"
        }
      }
    }
  }
}