feat(mcp): add version command and clearer unknown-command guidance

packages/gittensory-mcp/README.md

@@ -27,6 +27,8 @@ npm link --workspace @jsonbored/gittensory-mcp
 ## Commands
 
 ```sh
+gittensory-mcp version
+gittensory-mcp version --json
 gittensory-mcp login
 gittensory-mcp logout
 gittensory-mcp whoami
@@ -52,6 +54,23 @@ gittensory-mcp agent explain <run-id> --json
 gittensory-mcp --stdio
 ```
 
+`gittensory-mcp version` (aliases `--version` and `-v`) prints the installed package version, the targeted API version, and the Node.js runtime version:
+
+```text
+@jsonbored/gittensory-mcp/0.4.0 (api 0.1.0, node v22.12.0)
+```
+
+Add `--json` for machine-readable output:
+
+```json
+{
+  "name": "@jsonbored/gittensory-mcp",
+  "version": "0.4.0",
+  "apiVersion": "0.1.0",
+  "node": "v22.12.0"
+}
+```
+
 For near-term what-if scoreability, pass the situational assumptions explicitly:
 
 ```sh

packages/gittensory-mcp/bin/gittensory-mcp.js

@@ -485,6 +485,7 @@ await server.connect(new StdioServerTransport());
 async function runCli(args) {
   const command = args[0];
   if (command === "--help" || command === "help") return printHelp();
+  if (command === "--version" || command === "-v" || command === "version") return printVersion(parseOptions(args.slice(1)));
   if (command === "agent") return runAgentCli(args.slice(1));
   if (command === "cache") return runCacheCli(args.slice(1));
   const options = parseOptions(args.slice(1));
@@ -498,7 +499,7 @@ async function runCli(args) {
   if (command === "init-client") return initClient(options);
   if (command === "decision-pack") return decisionPackCli(options);
   if (command === "repo-decision") return repoDecisionCli(options);
-  if (command !== "analyze-branch" && command !== "preflight") throw new Error(`Unknown command: ${command}`);
+  if (command !== "analyze-branch" && command !== "preflight") throw new Error(`Unknown command: ${command}. Run \`gittensory-mcp --help\` to list commands.`);
   const contributorLogin = options.login ?? process.env.GITTENSORY_LOGIN ?? process.env.GITHUB_LOGIN;
   if (!contributorLogin) throw new Error("Pass --login <github-login> or set GITTENSORY_LOGIN.");
   const result = await analyzeCurrentBranch({
@@ -719,9 +720,19 @@ function isUnsafePublicPacketText(value) {
   return /\b(reward\w*|score\w*|wallet|hotkey|coldkey|mnemonic|farming|payout|ranking|raw[-_\s]?trust|trust[-_\s]?score|private[-_\s]?reviewability|reviewability)\b|\/Users\/|\/home\/|\/tmp\/|[A-Z]:\\Users\\/i.test(value);
 }
 
+function printVersion(options) {
+  const payload = { name: packageName, version: packageVersion, apiVersion: currentApiVersion, node: process.version };
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(`${packageName}/${packageVersion} (api ${currentApiVersion}, node ${process.version})\n`);
+}
+
 function printHelp() {
   process.stdout.write(`Usage:
   gittensory-mcp --stdio
+  gittensory-mcp version [--json]
   gittensory-mcp login [--profile name] [--github-token <token>] [--json]
   gittensory-mcp logout [--profile name] [--all] [--json]
   gittensory-mcp whoami [--profile name] [--json]

test/unit/mcp-cli.test.ts

@@ -900,6 +900,30 @@ describe("gittensory-mcp CLI", () => {
   it("rejects unsupported client snippets", () => {
     expect(() => run(["init-client", "--print", "other"])).toThrow(/Unsupported client/);
   });
+
+  it("reports the package version via version, --version, and -v", () => {
+    const expected = "@jsonbored/gittensory-mcp/0.4.0";
+    for (const flag of ["version", "--version", "-v"]) {
+      const plain = run([flag]).trim();
+      expect(plain).toContain(expected);
+      // The plain form reports all three values the README documents.
+      expect(plain).toContain("api 0.1.0");
+      expect(plain).toContain(`node ${process.version}`);
+    }
+  });
+
+  it("emits machine-readable version output with --json", () => {
+    const payload = JSON.parse(run(["version", "--json"])) as { name: string; version: string; apiVersion: string; node: string };
+    expect(payload.name).toBe("@jsonbored/gittensory-mcp");
+    expect(payload.version).toBe("0.4.0");
+    expect(payload.apiVersion).toBe("0.1.0");
+    expect(payload.node).toBe(process.version);
+  });
+
+  it("guides unknown commands to --help", () => {
+    expect(() => run(["bogus-command"])).toThrow(/Unknown command: bogus-command/);
+    expect(() => run(["bogus-command"])).toThrow(/gittensory-mcp --help/);
+  });
 });
 
 function run(args: string[], env: Record<string, string> = {}) {