refactor: migrate protocol + docs tooling into buddy commands

Per Chris: reusable tooling should be discoverable behind `buddy`, not loose
scripts. Move the protocol governance + docs-freshness tooling out of
.github/scripts and expose it as `buddy protocol:*` (16 commands) and
`buddy docs:*` (6). The protocol suite/evidence data stays under
.github/protocol; the pre-install / CI-internal glue (check-lockfile-version,
check-dependency-commits, deploy/resolve-target) stays as scripts.

- .github/scripts/{protocol,docs} -> app/Commands/{protocol,docs}. Same depth,
  so root + framework-import paths are unchanged; sync-suite.test.ts's combined
  `../../protocol` ref needed one more `../` since app/Commands and
  .github/protocol are not siblings.
- Each tool's `if (import.meta.main)` body extracted to `export run()`; a
  runTool() helper swaps process.argv so each tool's existing --check/--write
  parsing works unchanged.
- app/Commands/{Protocol,Docs}.ts register the commands; package.json + CI now
  invoke `buddy <cmd>`.

Verified: every command runs; protocol:conformance 15/37; moved tests 48/0;
lint clean. The manifest/desktop/craft/docs:buddy checks fail only locally
(missing rfcs git object, env-dependent evidence, machine-path doc noise),
identical on origin/main and green in CI.

Author: glennmichael123

.github/scripts/protocol/desktop-support.ts

@@ -174,8 +174,8 @@ jobs:
         env:
           PROTOCOL_REPORT_DIR: .github/protocol/reports
         run: |
-          bun test ./.github/scripts/protocol/run-conformance.test.ts
-          bun test ./.github/scripts/protocol/craft-evidence.test.ts ./.github/scripts/protocol/desktop-lifecycle-report.test.ts
+          bun test ./app/Commands/protocol/run-conformance.test.ts
+          bun test ./app/Commands/protocol/craft-evidence.test.ts ./app/Commands/protocol/desktop-lifecycle-report.test.ts
           bun test ./.github/scripts/deploy/resolve-target.test.ts
           bun run protocol:drivers:test
           bun run protocol:conformance

.github/workflows/ci.yml

@@ -5,16 +5,16 @@ on:
     branches: [main]
     paths:
       - storage/framework/core/desktop/**
-      - .github/scripts/protocol/craft-evidence.ts
-      - .github/scripts/protocol/desktop-lifecycle-report.ts
+      - app/Commands/protocol/craft-evidence.ts
+      - app/Commands/protocol/desktop-lifecycle-report.ts
       - .github/protocol/evidence/craft.json
       - .github/workflows/desktop-lifecycle.yml
   pull_request:
     branches: [main]
     paths:
       - storage/framework/core/desktop/**
-      - .github/scripts/protocol/craft-evidence.ts
-      - .github/scripts/protocol/desktop-lifecycle-report.ts
+      - app/Commands/protocol/craft-evidence.ts
+      - app/Commands/protocol/desktop-lifecycle-report.ts
       - .github/protocol/evidence/craft.json
       - .github/workflows/desktop-lifecycle.yml
   workflow_dispatch:
@@ -123,7 +123,7 @@ jobs:
 
       - name: Validate and attest lifecycle report
         run: >-
-          bun .github/scripts/protocol/desktop-lifecycle-report.ts
+          bun app/Commands/protocol/desktop-lifecycle-report.ts
           --report .craft-contract/artifacts/native-lifecycle/${{ matrix.name }}/report.json
           --output .github/protocol/reports/desktop/${{ matrix.name }}/attestation.json
           --revision "$CRAFT_SOURCE_REVISION"

.github/workflows/desktop-lifecycle.yml

@@ -28,4 +28,6 @@ export type CommandRegistry = Record<string, string | CommandConfig>
  */
 export default {
   'inspire': 'Inspire',
+  'protocol': 'Protocol',
+  'docs': 'Docs',
 } satisfies CommandRegistry

app/Commands.ts

@@ -0,0 +1,48 @@
+import type { CLI } from '@stacksjs/types'
+import { run as runArtifacts } from './docs/generated-artifacts'
+import { run as runBuddyDocs } from './docs/buddy-commands'
+import { run as runLinks } from './docs/links'
+import { runTool } from './run-tool'
+
+/**
+ * Repo-scoped `buddy docs:*` commands wrapping the documentation-freshness
+ * tooling under `app/Commands/docs/`: the generated buddy command reference,
+ * generated API artifacts (OpenAPI + types), and internal link checking.
+ */
+export default function (cli: CLI): void {
+  cli
+    .command('docs:buddy', 'Regenerate the buddy command reference doc')
+    .action(async () => {
+      await runTool(runBuddyDocs, '--write')
+    })
+
+  cli
+    .command('docs:buddy:check', 'Verify the buddy command reference doc is current')
+    .action(async () => {
+      await runTool(runBuddyDocs, '--check')
+    })
+
+  cli
+    .command('docs:artifacts', 'Regenerate the generated API artifacts (OpenAPI + types)')
+    .action(async () => {
+      await runTool(runArtifacts, '--write')
+    })
+
+  cli
+    .command('docs:artifacts:check', 'Verify the generated API artifacts are current')
+    .action(async () => {
+      await runTool(runArtifacts, '--check')
+    })
+
+  cli
+    .command('docs:links', 'Report internal documentation links')
+    .action(async () => {
+      await runTool(runLinks)
+    })
+
+  cli
+    .command('docs:links:check', 'Verify internal documentation links resolve')
+    .action(async () => {
+      await runTool(runLinks, '--check')
+    })
+}

app/Commands/Docs.ts

@@ -0,0 +1,119 @@
+import type { CLI } from '@stacksjs/types'
+import { run as runConformance } from './protocol/run-conformance'
+import { run as runCraft } from './protocol/craft-evidence'
+import { run as runDesktop } from './protocol/desktop-support'
+import { run as runDrivers } from './protocol/driver-registry'
+import { run as runDriverContracts } from './protocol/run-driver-contracts'
+import { run as runPantry } from './protocol/pantry-evidence'
+import { run as runRelease } from './protocol/release-manifest'
+import { run as runManifest } from './protocol/source-manifest'
+import { run as runSync } from './protocol/sync-suite'
+import { runTool } from './run-tool'
+
+/**
+ * Repo-scoped `buddy protocol:*` commands. The governance tooling itself lives
+ * beside this file under `app/Commands/protocol/`; the protocol suite + evidence
+ * DATA stays under `.github/protocol/`. These wrap the tooling so it is
+ * discoverable via the CLI (`buddy protocol:conformance`) instead of a bare
+ * `bun app/Commands/protocol/...`.
+ */
+export default function (cli: CLI): void {
+  cli
+    .command('protocol:conformance', 'Generate the Stacks protocol conformance report')
+    .action(async () => {
+      await runConformance()
+    })
+
+  cli
+    .command('protocol:sync', 'Sync the vendored protocol suite from stacksjs/rfcs')
+    .option('--source <path>', 'Path to a local rfcs checkout', { default: undefined })
+    .action(async (options: { source?: string }) => {
+      await runTool(runSync, '--write', ...(options.source ? ['--source', options.source] : []))
+    })
+
+  cli
+    .command('protocol:check', 'Verify the vendored protocol suite is pinned + internally consistent')
+    .action(async () => {
+      await runTool(runSync, '--check')
+    })
+
+  cli
+    .command('protocol:manifest', 'Write the protocol source manifest')
+    .option('--revision <ref>', 'Source revision to pin (default HEAD)', { default: undefined })
+    .action(async (options: { revision?: string }) => {
+      await runTool(runManifest, '--write', ...(options.revision ? ['--revision', options.revision] : []))
+    })
+
+  cli
+    .command('protocol:manifest:check', 'Verify the protocol source manifest is current')
+    .action(async () => {
+      await runTool(runManifest, '--check')
+    })
+
+  cli
+    .command('protocol:release', 'Write the protocol release manifest')
+    .option('--tag <tag>', 'Release tag', { default: undefined })
+    .action(async (options: { tag?: string }) => {
+      await runTool(runRelease, '--write', ...(options.tag ? ['--tag', options.tag] : []))
+    })
+
+  cli
+    .command('protocol:release:check', 'Verify the protocol release manifest is current')
+    .action(async () => {
+      await runTool(runRelease, '--check')
+    })
+
+  cli
+    .command('protocol:drivers', 'Write the driver capability registry evidence')
+    .action(async () => {
+      await runTool(runDrivers, '--write')
+    })
+
+  cli
+    .command('protocol:drivers:check', 'Verify the driver capability registry evidence')
+    .action(async () => {
+      await runTool(runDrivers, '--check')
+    })
+
+  cli
+    .command('protocol:drivers:test', 'Run the driver contract suite')
+    .action(async () => {
+      await runTool(runDriverContracts)
+    })
+
+  cli
+    .command('protocol:desktop', 'Write the desktop support matrix evidence')
+    .action(async () => {
+      await runTool(runDesktop, '--write')
+    })
+
+  cli
+    .command('protocol:desktop:check', 'Verify the desktop support matrix evidence')
+    .action(async () => {
+      await runTool(runDesktop, '--check')
+    })
+
+  cli
+    .command('protocol:pantry', 'Write the pantry evidence')
+    .action(async () => {
+      await runTool(runPantry, '--write')
+    })
+
+  cli
+    .command('protocol:pantry:check', 'Verify the pantry evidence')
+    .action(async () => {
+      await runTool(runPantry, '--check')
+    })
+
+  cli
+    .command('protocol:craft', 'Write the Craft evidence')
+    .action(async () => {
+      await runTool(runCraft, '--write')
+    })
+
+  cli
+    .command('protocol:craft:check', 'Verify the Craft evidence')
+    .action(async () => {
+      await runTool(runCraft, '--check')
+    })
+}

app/Commands/Protocol.ts

@@ -89,7 +89,7 @@ export function renderBuddyCommandReference(inventory: BuddyInventory): string {
     'title: Buddy Command Reference',
     'description: Generated reference for every Buddy command, argument, option, alias, default, and example.',
     '---',
-    '<!-- Generated by .github/scripts/docs/buddy-commands.ts. Do not edit by hand. -->',
+    '<!-- Generated by app/Commands/docs/buddy-commands.ts. Do not edit by hand. -->',
     '',
     '# Buddy Command Reference',
     '',
@@ -125,10 +125,10 @@ export function loadBuddyInventory(): BuddyInventory {
   return inventory
 }
 
-if (import.meta.main) {
+export async function run(): Promise<void> {
   const mode = process.argv.includes('--write') ? 'write' : process.argv.includes('--check') ? 'check' : null
   if (!mode) {
-    console.error('usage: bun .github/scripts/docs/buddy-commands.ts --write | --check')
+    console.error('usage: bun app/Commands/docs/buddy-commands.ts --write | --check')
     process.exit(2)
   }
 
@@ -145,3 +145,6 @@ if (import.meta.main) {
     console.log('Buddy command reference matches the runtime registry')
   }
 }
+
+if (import.meta.main)
+  await run()

…thub/scripts/docs/buddy-commands.test.ts app/Commands/docs/buddy-commands.test.ts.github/scripts/docs/buddy-commands.test.ts renamed to app/Commands/docs/buddy-commands.test.ts .github/scripts/docs/buddy-commands.test.ts renamed to app/Commands/docs/buddy-commands.test.ts

@@ -51,12 +51,12 @@ async function check(): Promise<void> {
   console.log(`Generated API artifacts are current (${Object.keys(JSON.parse(expected.openApi).paths).length} paths)`)
 }
 
-if (import.meta.main) {
+export async function run(): Promise<void> {
   try {
     if (process.argv.includes('--write')) await write()
     else if (process.argv.includes('--check')) await check()
     else {
-      console.error('usage: bun .github/scripts/docs/generated-artifacts.ts --write | --check')
+      console.error('usage: bun app/Commands/docs/generated-artifacts.ts --write | --check')
       process.exit(2)
     }
   }
@@ -65,3 +65,6 @@ if (import.meta.main) {
     process.exit(1)
   }
 }
+
+if (import.meta.main)
+  await run()