diff --git a/package-lock.json b/package-lock.json
index a8e4c44f7a..c77919714c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -2691,10 +2691,18 @@
         "@jridgewell/sourcemap-codec": "^1.4.10"
       }
     },
+    "node_modules/@jsonbored/gittensory-engine": {
+      "resolved": "packages/gittensory-engine",
+      "link": true
+    },
     "node_modules/@jsonbored/gittensory-mcp": {
       "resolved": "packages/gittensory-mcp",
       "link": true
     },
+    "node_modules/@jsonbored/gittensory-miner": {
+      "resolved": "packages/gittensory-miner",
+      "link": true
+    },
     "node_modules/@jsonbored/gittensory-ui": {
       "resolved": "apps/gittensory-ui",
       "link": true
@@ -15474,6 +15482,14 @@
         "zod": "^3.25.28 || ^4"
       }
     },
+    "packages/gittensory-engine": {
+      "name": "@jsonbored/gittensory-engine",
+      "version": "0.1.0",
+      "license": "AGPL-3.0-only",
+      "engines": {
+        "node": ">=22.0.0"
+      }
+    },
     "packages/gittensory-mcp": {
       "name": "@jsonbored/gittensory-mcp",
       "version": "0.6.0",
@@ -15488,6 +15504,20 @@
       "engines": {
         "node": ">=22.0.0"
       }
+    },
+    "packages/gittensory-miner": {
+      "name": "@jsonbored/gittensory-miner",
+      "version": "0.1.0",
+      "license": "AGPL-3.0-only",
+      "dependencies": {
+        "@jsonbored/gittensory-engine": "0.1.0"
+      },
+      "bin": {
+        "gittensory-miner": "bin/gittensory-miner.js"
+      },
+      "engines": {
+        "node": ">=22.0.0"
+      }
     }
   }
 }
diff --git a/packages/gittensory-engine/lib/index.d.ts b/packages/gittensory-engine/lib/index.d.ts
new file mode 100644
index 0000000000..cb0ff5c3b5
--- /dev/null
+++ b/packages/gittensory-engine/lib/index.d.ts
@@ -0,0 +1 @@
+export {};
diff --git a/packages/gittensory-engine/lib/index.js b/packages/gittensory-engine/lib/index.js
new file mode 100644
index 0000000000..cb0ff5c3b5
--- /dev/null
+++ b/packages/gittensory-engine/lib/index.js
@@ -0,0 +1 @@
+export {};
diff --git a/packages/gittensory-engine/package.json b/packages/gittensory-engine/package.json
new file mode 100644
index 0000000000..972c7a8bcd
--- /dev/null
+++ b/packages/gittensory-engine/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@jsonbored/gittensory-engine",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "description": "Shared pure engine helpers for Gittensory miner and gate logic.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JSONbored/gittensory.git",
+    "directory": "packages/gittensory-engine"
+  },
+  "homepage": "https://github.com/JSONbored/gittensory#readme",
+  "bugs": {
+    "url": "https://github.com/JSONbored/gittensory/issues"
+  },
+  "keywords": [
+    "gittensor",
+    "gittensory",
+    "engine",
+    "shared",
+    "miner"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./lib/index.js",
+  "exports": "./lib/index.js",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "node --check lib/index.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}
diff --git a/packages/gittensory-miner/README.md b/packages/gittensory-miner/README.md
new file mode 100644
index 0000000000..fac922663d
--- /dev/null
+++ b/packages/gittensory-miner/README.md
@@ -0,0 +1,33 @@
+# @jsonbored/gittensory-miner
+
+Foundation CLI for the local Gittensory miner runtime.
+
+This package is the future home of the autonomous discover → analyze → plan → prepare → create → manage miner workflow. In this foundation phase it only provides the package scaffold and a minimal CLI surface for `--help` and `--version`.
+
+## Status
+
+Current scope is intentionally small:
+
+- workspace package wiring
+- CLI entry point
+- `--help` and `version` commands
+
+Real miner commands land in follow-up issues.
+
+## Install
+
+From a local checkout:
+
+```sh
+npm install
+npm --workspace @jsonbored/gittensory-miner run build
+```
+
+## Commands
+
+```sh
+gittensory-miner --help
+gittensory-miner help
+gittensory-miner --version
+gittensory-miner version
+```
diff --git a/packages/gittensory-miner/bin/gittensory-miner.js b/packages/gittensory-miner/bin/gittensory-miner.js
new file mode 100755
index 0000000000..f04e105069
--- /dev/null
+++ b/packages/gittensory-miner/bin/gittensory-miner.js
@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { printHelp, printVersion, runCli } from "../lib/cli.js";
+
+const cliArgs = process.argv.slice(2);
+const require = createRequire(import.meta.url);
+const packageName = "@jsonbored/gittensory-miner";
+const packageVersion = require("../package.json").version;
+
+if (cliArgs.length === 0 || cliArgs.includes("--help") || cliArgs.includes("-h") || cliArgs[0] === "help") {
+  printHelp({ packageName });
+  process.exit(0);
+}
+
+if (cliArgs.includes("--version") || cliArgs.includes("-v") || cliArgs[0] === "version") {
+  printVersion({ packageName, packageVersion });
+  process.exit(0);
+}
+
+const exitCode = runCli(cliArgs, { packageName });
+process.exit(exitCode);
diff --git a/packages/gittensory-miner/lib/cli.d.ts b/packages/gittensory-miner/lib/cli.d.ts
new file mode 100644
index 0000000000..d2e718b111
--- /dev/null
+++ b/packages/gittensory-miner/lib/cli.d.ts
@@ -0,0 +1,12 @@
+export type VersionPrintInput = {
+  packageName: string;
+  packageVersion: string;
+};
+
+export type HelpPrintInput = {
+  packageName: string;
+};
+
+export declare function printVersion(input: VersionPrintInput): void;
+export declare function printHelp(input: HelpPrintInput): void;
+export declare function runCli(cliArgs: string[], input: HelpPrintInput): number;
diff --git a/packages/gittensory-miner/lib/cli.js b/packages/gittensory-miner/lib/cli.js
new file mode 100644
index 0000000000..426e019275
--- /dev/null
+++ b/packages/gittensory-miner/lib/cli.js
@@ -0,0 +1,25 @@
+export function printVersion(input) {
+  console.log(`${input.packageName}/${input.packageVersion} (node ${process.version})`);
+}
+
+export function printHelp(input) {
+  console.log(
+    [
+      input.packageName,
+      "",
+      "Foundation CLI for the local Gittensory miner runtime.",
+      "",
+      "Usage:",
+      "  gittensory-miner --help",
+      "  gittensory-miner --version",
+      "  gittensory-miner help",
+      "  gittensory-miner version",
+    ].join("\n"),
+  );
+}
+
+export function runCli(cliArgs, input) {
+  const command = cliArgs[0] ?? "";
+  console.error(`Unknown command: ${command}. Run ${input.packageName} --help.`);
+  return 1;
+}
diff --git a/packages/gittensory-miner/package.json b/packages/gittensory-miner/package.json
new file mode 100644
index 0000000000..74b8075d8b
--- /dev/null
+++ b/packages/gittensory-miner/package.json
@@ -0,0 +1,42 @@
+{
+  "name": "@jsonbored/gittensory-miner",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "description": "Foundation CLI for the local Gittensory miner runtime.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JSONbored/gittensory.git",
+    "directory": "packages/gittensory-miner"
+  },
+  "homepage": "https://github.com/JSONbored/gittensory#readme",
+  "bugs": {
+    "url": "https://github.com/JSONbored/gittensory/issues"
+  },
+  "keywords": [
+    "gittensor",
+    "gittensory",
+    "miner",
+    "cli",
+    "agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "gittensory-miner": "bin/gittensory-miner.js"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "scripts": {
+    "build": "node --check bin/gittensory-miner.js && node --check lib/cli.js"
+  },
+  "dependencies": {
+    "@jsonbored/gittensory-engine": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}
diff --git a/test/unit/miner-cli.test.ts b/test/unit/miner-cli.test.ts
new file mode 100644
index 0000000000..b800eb21f0
--- /dev/null
+++ b/test/unit/miner-cli.test.ts
@@ -0,0 +1,34 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { printHelp, printVersion, runCli } from "../../packages/gittensory-miner/lib/cli.js";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("gittensory-miner CLI helpers", () => {
+  it("prints the package version with the node runtime", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    printVersion({ packageName: "@jsonbored/gittensory-miner", packageVersion: "0.1.0" });
+    expect(log).toHaveBeenCalledWith(expect.stringContaining("@jsonbored/gittensory-miner/0.1.0"));
+    expect(log).toHaveBeenCalledWith(expect.stringContaining(process.version));
+  });
+
+  it("prints help text with the supported commands", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    printHelp({ packageName: "@jsonbored/gittensory-miner" });
+    const text = log.mock.calls[0]?.[0];
+    expect(text).toContain("gittensory-miner --help");
+    expect(text).toContain("gittensory-miner version");
+  });
+
+  it("returns exit code 1 for unknown commands", () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    expect(runCli(["mystery"], { packageName: "@jsonbored/gittensory-miner" })).toBe(1);
+    expect(error).toHaveBeenCalledWith("Unknown command: mystery. Run @jsonbored/gittensory-miner --help.");
+  });
+
+  it("keeps the CLI version source aligned with package metadata", async () => {
+    const packageJson = await import("../../packages/gittensory-miner/package.json", { with: { type: "json" } });
+    expect(packageJson.default.version).toBe("0.1.0");
+  });
+});
diff --git a/test/unit/miner-package-contract.test.ts b/test/unit/miner-package-contract.test.ts
new file mode 100644
index 0000000000..14e1b8b34e
--- /dev/null
+++ b/test/unit/miner-package-contract.test.ts
@@ -0,0 +1,8 @@
+import { describe, expect, it } from "vitest";
+
+describe("miner package workspace contracts", () => {
+  it("allows importing @jsonbored/gittensory-engine by package name", async () => {
+    const mod = await import("@jsonbored/gittensory-engine");
+    expect(Object.keys(mod)).toEqual([]);
+  });
+});