@@ -35,11 +35,10 @@ asserts a stray `~/devkit` is ignored, not adopted).
3535The live registry is ` apps.json ` , which is local-only and gitignored.
3636The committed example registry is ` apps.example.json ` .
3737
38- ## Consumer contract (the Mac app + MCP build on this)
38+ ## Machine-readable contract
3939
40- The CLI is the single brain; the menu bar app and the MCP server are thin clients that
41- shell out to it and parse its output. Treat these as a stable public contract — other
42- programs depend on them, so do not break them casually:
40+ The CLI is the single source of truth. Other tools may shell out to it and parse its
41+ output, so treat these as a stable public contract and do not break them casually:
4342
4443- ` devkit list --json ` — one JSON object per app (` name ` , ` port ` , ` hostname ` , ` state ` ,
4544 ` path ` , ` managedBy ` , and the failed-start reason / log path). This is how clients read
@@ -50,11 +49,11 @@ programs depend on them, so do not break them casually:
5049- ` devkit scan --json ` , ` devkit doctor --json ` — machine-readable, same spirit.
5150- ** Exit codes matter** : 0 = success, non-zero = failure (clients branch on this).
5251- ** Every command must terminate** non-interactively (no ` tail -f ` -style hangs) — an agent
53- or the app may invoke any of them.
52+ or a script may invoke any of them.
5453
5554Versioning: additive changes (new fields/commands) are a minor bump; renaming/removing a
56- field or changing ` state ` values is a breaking change — bump major and update the app/MCP
57- in lockstep. Keeping this contract stable is what lets the three surfaces stay in sync.
55+ field or changing ` state ` values is a breaking change — bump major. Keeping this contract
56+ stable is what lets any consumer stay in sync.
5857
5958## Generated files
6059
@@ -70,14 +69,14 @@ They are regenerated by `devkit reload`.
7069This repo is ** public** . Avoid baking machine-specific paths, usernames, or private
7170project names into committed files.
7271
73- ** Never commit (privacy / paid product ):**
72+ ** Never commit (privacy / non-public source ):**
7473
7574- ` apps.json ` — the live registry; it contains your real project names and paths. Only the
7675 sanitized ` apps.example.json ` is tracked.
7776- ` pids/ ` , ` logs/ ` , ` Caddyfile ` , ` dashboard.html ` — runtime + generated, machine-specific.
7877- ` .claude/settings.local.json ` (local paths / allow-rules) and ` .claude/ ` generally.
79- - Anything under ` MenuBarApp/ ` except ` MenuBarApp/docs/ ` — the Mac app is the ** paid **
80- product and lives in the private ` devkit-app ` repo. Never let its source land here.
78+ - Anything under ` MenuBarApp/ ` except ` MenuBarApp/docs/ ` — that source is maintained in a
79+ separate repo and is not part of this CLI. Only the ` docs/ ` landing page is public here.
8180
8281These are all in ` .gitignore ` , but ` .gitignore ` only stops accidental ` git add ` — it does
8382not catch a file that is already tracked. The ` cli.yml ` workflow has a ** repo-hygiene
0 commit comments