@markdown-ai/cli 1.0.0-rc.2 → 1.0.0-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +124 -5
  2. package/package.json +9 -3
package/README.md CHANGED
@@ -1,18 +1,137 @@
1
1
  # @markdown-ai/cli
2
2
 
3
- Reference CLI for Markdown AI / MDA artifacts.
3
+ `@markdown-ai/cli` installs one command: `mda`.
4
+
5
+ Use it to create, validate, compile, canonicalize, and integrity-check Markdown AI
6
+ (MDA) artifacts before humans, AI agents, CI jobs, or publishing pipelines use
7
+ them.
8
+
9
+ The CLI is most useful at design time and CI time. It helps you write one `.mda`
10
+ source file, then produce the Markdown files that agent systems already know how
11
+ to read: `SKILL.md`, `AGENTS.md`, and `MCP-SERVER.md`.
12
+
13
+ ## Install
14
+
15
+ Run without installing:
4
16
 
5
17
  ```sh
6
18
  npx @markdown-ai/cli --help
7
19
  ```
8
20
 
21
+ Install globally:
22
+
23
+ ```sh
24
+ npm install -g @markdown-ai/cli
25
+ mda --help
26
+ ```
27
+
9
28
  The installed binary is `mda`.
10
29
 
30
+ Running `mda` with no arguments prints complete help. That is intentional. A
31
+ human or an AI agent can discover the command surface quickly without guessing.
32
+
33
+ ## Quick Start
34
+
35
+ Create a source file:
36
+
11
37
  ```sh
12
38
  mda init hello-skill --out hello.mda
13
- mda validate hello.mda --json
14
- mda compile hello.mda --target SKILL.md AGENTS.md MCP-SERVER.md --out-dir out --integrity
15
- mda conformance --level V --json
16
39
  ```
17
40
 
18
- See [HOW-TO-USE.md](./HOW-TO-USE.md) for the command manual.
41
+ Validate it:
42
+
43
+ ```sh
44
+ mda validate hello.mda
45
+ ```
46
+
47
+ Compile it into agent-readable Markdown:
48
+
49
+ ```sh
50
+ mda compile hello.mda --target SKILL.md AGENTS.md --out-dir out --integrity
51
+ ```
52
+
53
+ Validate the output:
54
+
55
+ ```sh
56
+ mda validate out/SKILL.md --target SKILL.md
57
+ mda validate out/AGENTS.md --target AGENTS.md
58
+ mda integrity verify out/SKILL.md --target SKILL.md
59
+ ```
60
+
61
+ That is the main flow. Start there.
62
+
63
+ ## For AI Agents
64
+
65
+ Use `--json` almost every time.
66
+
67
+ Human output is for eyes. JSON output is for code. It gives agents stable fields
68
+ such as `ok`, `command`, `exitCode`, and `diagnostics`.
69
+
70
+ Recommended agent flow:
71
+
72
+ ```sh
73
+ mda validate task.mda --target source --json
74
+ mda compile task.mda --target SKILL.md AGENTS.md MCP-SERVER.md --out-dir out --integrity --json
75
+ mda validate out/SKILL.md --target SKILL.md --json
76
+ mda validate out/AGENTS.md --target AGENTS.md --json
77
+ mda validate out/MCP-SERVER.md --target MCP-SERVER.md --json
78
+ mda integrity verify out/SKILL.md --target SKILL.md --json
79
+ ```
80
+
81
+ Agent rules:
82
+
83
+ - Treat exit code `0` and `ok: true` as success.
84
+ - Treat any non-zero exit as a stop signal.
85
+ - Read `diagnostics[0].code` before scraping human text.
86
+ - Pass `--target` when the filename is not exact.
87
+ - Write generated files into a temp or staging directory first.
88
+
89
+ This keeps the CLI useful as an external gate. Application runtime loaders should
90
+ keep their own verifier hooks instead of shelling out to `mda`.
91
+
92
+ ## Common Commands
93
+
94
+ | Command | Use it for |
95
+ | --- | --- |
96
+ | `mda` | Print full help. |
97
+ | `mda init <name> --out <file.mda>` | Create a source scaffold. |
98
+ | `mda validate <file> [--target <target>]` | Validate source or generated Markdown. |
99
+ | `mda compile <file.mda> --target SKILL.md AGENTS.md --out-dir out --integrity` | Compile source into agent-readable artifacts. |
100
+ | `mda canonicalize <file> --target <target>` | Produce deterministic canonical bytes. |
101
+ | `mda integrity compute <file> --target <target>` | Compute a stable digest. |
102
+ | `mda integrity verify <file> --target <target>` | Check the declared digest against current content. |
103
+ | `mda conformance --level V --json` | Run the conformance suite. |
104
+
105
+ Allowed targets:
106
+
107
+ - `source`
108
+ - `SKILL.md`
109
+ - `AGENTS.md`
110
+ - `MCP-SERVER.md`
111
+ - `auto`
112
+
113
+ Auto-detection is exact:
114
+
115
+ - `*.mda` means `source`
116
+ - `SKILL.md` means `SKILL.md`
117
+ - `AGENTS.md` means `AGENTS.md`
118
+ - `MCP-SERVER.md` means `MCP-SERVER.md`
119
+ - any other Markdown filename should pass `--target`
120
+
121
+ ## Full Manual
122
+
123
+ Read [HOW-TO-USE.md](./HOW-TO-USE.md) for the complete command manual, including
124
+ all parameters, exit codes, MCP sidecar handling, integrity examples, and
125
+ agent-oriented usage patterns.
126
+
127
+ For the broader project context, read the repository
128
+ [README](https://github.com/sno-ai/mda#readme) and the
129
+ [MDA Open Spec](https://github.com/sno-ai/mda/blob/main/SPEC.md).
130
+
131
+ ## Status
132
+
133
+ This is the reference CLI for the Markdown AI / MDA artifact format.
134
+
135
+ The useful path today is clear: author `.mda`, validate it, compile it, validate
136
+ the outputs, and run integrity checks before publishing or handing files to an
137
+ agent.
package/package.json CHANGED
@@ -1,14 +1,14 @@
1
1
  {
2
2
  "name": "@markdown-ai/cli",
3
- "version": "1.0.0-rc.2",
4
- "description": "Reference CLI for Markdown AI / MDA artifacts.",
3
+ "version": "1.0.0-rc.3",
4
+ "description": "MDA command-line tools for authoring, validating, compiling, and checking Markdown AI artifacts.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
8
8
  "url": "git+https://github.com/sno-ai/mda.git",
9
9
  "directory": "apps/cli"
10
10
  },
11
- "homepage": "https://github.com/sno-ai/mda/tree/main/apps/cli",
11
+ "homepage": "https://github.com/sno-ai/mda",
12
12
  "bugs": {
13
13
  "url": "https://github.com/sno-ai/mda/issues"
14
14
  },
@@ -28,8 +28,14 @@
28
28
  "keywords": [
29
29
  "mda",
30
30
  "markdown-ai",
31
+ "markdown",
32
+ "ai-agent",
31
33
  "agent",
32
34
  "cli",
35
+ "skill",
36
+ "agents-md",
37
+ "mcp",
38
+ "integrity",
33
39
  "conformance"
34
40
  ],
35
41
  "engines": {