feat: add CLI help and version flags

Adds `curion --help` / `-h` and `curion --version` / `-v`
flag interception to the entrypoint so the binary prints
usage / version to stdout and exits 0 before any storage or
MCP transport startup. The flag handlers never create or
touch the project-local `.curion/` directory and never write
to stderr; normal MCP stdio behaviour for unflagged
invocations is unchanged.

The runtime server version now syncs from `package.json`
through a generated `src/version.ts`, regenerated by
`scripts/sync-version.mjs` on every `prebuild` / `pretest`.
The McpServer `serverInfo.version` field is no longer
hardcoded to the stale `0.2.0` literal. The `--version` CLI
output and the MCP `initialize` response both reflect
`package.json#version` at release time.

Adds `tests/cli-flags.test.ts` with 15 unit and end-to-end
subprocess tests covering: the `buildHelpText` shape and
content, the `VERSION` constant matching `package.json`,
`buildServer` using `VERSION` and honouring the
`options.version` override, and the four flag invocations
plus combined-flag argv-order precedence and a no-flag
regression guard.

Bumps `package.json` (and `package-lock.json`) from 0.3.5
to 0.3.6 to prep the release. The generated
`src/version.ts` is gitignored.

Changelog: moves the existing Unreleased CLI entry into a
new `[0.3.6] - 2026-06-30` section and updates the compare
links.

Author: geanatz

.gitignore

@@ -2,6 +2,10 @@
 dist/
 *.tsbuildinfo
 
+# Generated src/version.ts (synced from package.json by
+# `scripts/sync-version.mjs`; wired into prebuild/pretest).
+src/version.ts
+
 # Dependencies
 node_modules/
 

CHANGELOG.md

@@ -7,6 +7,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+Nothing yet.
+
+## [0.3.6] - 2026-06-30
+
+User-facing CLI release. Adds the two metadata flags
+(`--help` / `-h` and `--version` / `-v`) to the `curion` binary
+and replaces the previously hardcoded server version with a
+generated, package-synced version constant. No MCP tool surface
+change; no storage or controller change; no release-engineering
+change. The npm package name (`@geanatz/curion`), the Trusted
+Publishing / OIDC provenance path, and the binary name (`curion`)
+are unchanged.
+
+### Added
+
+- **`curion --help` / `-h` and `curion --version` / `-v` flag
+  interception.** Running `curion` with any of these four flags
+  now prints to stdout and exits 0 *before* any storage or MCP
+  transport startup. The flag handlers never create or touch the
+  project-local `.curion/` directory and never write to stderr
+  (logs). Normal MCP stdio behaviour for unflagged invocations is
+  unchanged. The help text (`src/cli-help.ts`) advertises the
+  two public tools, the env-var configuration contract, and a
+  docs link.
+- **Runtime server version now syncs from `package.json`.** The
+  McpServer `serverInfo.version` field is no longer hardcoded to
+  `"0.2.0"`; it is sourced from a generated `src/version.ts`
+  constant that `scripts/sync-version.mjs` regenerates from
+  `package.json#version` on every `prebuild` / `pretest`. A
+  caller can still override the value through `buildServer({
+  version })` for tests. The `--version` CLI output, the MCP
+  `serverInfo.version` field, and the published npm tarball
+  version are now guaranteed to match `package.json#version` at
+  every release.
+- **Generated version script.** `scripts/sync-version.mjs` is a
+  pure-Node, dependency-free script that writes
+  `src/version.ts` (gitignored) from `package.json#version`. It
+  is idempotent: re-running it on an in-sync tree is a no-op.
+  The `sync-version` script is wired into `prebuild` and
+  `pretest` so the generated file is always in sync before a
+  build or test run.
+
+### Changed
+
+- **`src/server.ts` no longer hardcodes `"0.2.0"`.** The previous
+  hardcoded `version: options.version ?? "0.2.0"` fallback has
+  been removed in favour of `options.version ?? VERSION`, where
+  `VERSION` is the generated constant from `src/version.ts`. This
+  is the only source-code change to the runtime server module;
+  the McpServer / MCP transport wiring, the tool surface, the
+  detector, and the storage layer are all unchanged.
+- **No behavioural change to the MCP server.** The two tools,
+  their `text` / `structuredContent` shapes, the
+  `clarification_needed` contract, and the project-local
+  `.curion/` storage shape are unchanged. The only McpServer
+  surface that changed is `serverInfo.version`.
+
+### Deprecated
+
+- Nothing in this release.
+
+### Removed
+
+- Nothing in this release.
+
+### Fixed
+
+- **`serverInfo.version` no longer reports the stale `0.2.0`
+  value.** The previous hardcoded fallback meant the MCP
+  `initialize` response advertised a server version that lagged
+  every release tag. The generated `VERSION` constant now keeps
+  it in lock-step with `package.json#version`.
+
+### Security
+
+- Nothing in this release. Provenance attestation remains enabled
+  for every published tarball via Trusted Publishing and
+  `publishConfig.provenance: true`, and no long-lived `NPM_TOKEN`
+  secret is read or required.
+
 ## [0.3.5] - 2026-06-30
 
 Documentation-only patch release. No source-code, runtime, or
@@ -683,7 +763,8 @@ no semantic enrichment, no multi-project awareness. Lexical-only
 match scoring on the controller. Provider adapter for a single
 OpenAI-compatible endpoint.
 
-[Unreleased]: https://github.com/geanatz/curion/compare/v0.3.5...HEAD
+[Unreleased]: https://github.com/geanatz/curion/compare/v0.3.6...HEAD
+[0.3.6]: https://github.com/geanatz/curion/compare/v0.3.5...v0.3.6
 [0.3.5]: https://github.com/geanatz/curion/compare/v0.3.4...v0.3.5
 [0.3.4]: https://github.com/geanatz/curion/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/geanatz/curion/compare/v0.3.2...v0.3.3

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@geanatz/curion",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Curion — project-local memory layer for AI agents",
   "type": "module",
   "license": "Apache-2.0",
@@ -38,7 +38,10 @@
     "access": "public"
   },
   "scripts": {
+    "sync-version": "node scripts/sync-version.mjs",
+    "prebuild": "npm run sync-version",
     "build": "tsc -p tsconfig.json",
+    "pretest": "npm run sync-version",
     "prepublishOnly": "npm run build && npm test",
     "test": "node --import tsx --test tests/*.test.ts --test 'tests/diagnostics/*.test.ts'",
     "test:contracts": "node --import tsx --test tests/contracts.test.ts",

package.json

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Regenerate `src/version.ts` from `package.json`.
+ *
+ * The package version is the single source of truth — this script
+ * reads `package.json#version` and writes a small generated
+ * TypeScript module that exports a `VERSION` constant. The file is
+ * intentionally short and dependency-free so it can be required
+ * from both the runtime entrypoint (`src/index.ts`) and the
+ * server-wiring module (`src/server.ts`).
+ *
+ * Wired into `prebuild` and `pretest` in `package.json` so the
+ * generated file is always in sync before a build or test run.
+ *
+ * Idempotent: if the existing `src/version.ts` already matches the
+ * generated content, the file is left untouched. This keeps
+ * incremental builds and re-runs cheap and avoids touching mtime
+ * unnecessarily.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const REPO_ROOT = path.resolve(__dirname, "..");
+const pkgPath = path.join(REPO_ROOT, "package.json");
+const outPath = path.join(REPO_ROOT, "src", "version.ts");
+
+const pkgRaw = fs.readFileSync(pkgPath, "utf8");
+let pkg;
+try {
+  pkg = JSON.parse(pkgRaw);
+} catch (err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  // Build-time tool — stderr is fine here; this is not the curion
+  // server runtime.
+  process.stderr.write(`[curion] sync-version: failed to parse package.json: ${msg}\n`);
+  process.exit(1);
+}
+const version = pkg.version;
+if (typeof version !== "string" || version.length === 0) {
+  process.stderr.write(
+    "[curion] sync-version: package.json is missing a non-empty `version` field\n"
+  );
+  process.exit(1);
+}
+
+const header = [
+  "/**",
+  " * Generated from package.json. Do not edit by hand.",
+  " *",
+  " * Regenerated by `scripts/sync-version.mjs`, wired into",
+  " * `prebuild` and `pretest` in `package.json`.",
+  " * The source of truth is `package.json#version`.",
+  " */",
+  "",
+].join("\n");
+
+// JSON.stringify produces a safely-escaped, quoted string literal
+// that TypeScript accepts verbatim.
+const body = `export const VERSION = ${JSON.stringify(version)};\n`;
+const newContent = header + body;
+
+let existing = null;
+try {
+  existing = fs.readFileSync(outPath, "utf8");
+} catch {
+  // file doesn't exist yet — that's fine, we'll create it
+}
+
+if (existing !== newContent) {
+  fs.writeFileSync(outPath, newContent);
+  process.stdout.write(`[curion] sync-version: wrote src/version.ts (${version})\n`);
+} else {
+  process.stdout.write(`[curion] sync-version: src/version.ts already up to date (${version})\n`);
+}

scripts/sync-version.mjs

@@ -0,0 +1,61 @@
+/**
+ * CLI help text for the `curion` binary.
+ *
+ * The `curion` binary is primarily an MCP stdio server. A user
+ * running `curion --help` from a shell sees this help. A user
+ * running `curion --version` sees just the version on its own
+ * line (so it can be embedded in scripts / CI).
+ *
+ * This module is the single source of truth for the help text.
+ * The flag interception in `src/index.ts` calls
+ * `buildHelpText(VERSION)` and writes the result to stdout.
+ *
+ * Output conventions:
+ *   - Single trailing newline.
+ *   - Pure: no I/O. The caller decides where to write the text.
+ *   - Self-contained: a user can understand what `curion` is
+ *     from this text alone, including the env-var contract and
+ *     where to find more docs.
+ *
+ * The `version` argument is injected so the function stays pure
+ * and testable without importing `./version.js`. The
+ * entrypoint passes the runtime `VERSION` constant; tests pass
+ * a stable fixture.
+ */
+
+const DOCS_URL = "https://github.com/geanatz/curion#readme";
+
+/**
+ * Build the help text for `curion --help`. Pure function.
+ */
+export function buildHelpText(version: string): string {
+  return [
+    "curion — project-local memory layer for AI agents",
+    "",
+    "Usage:",
+    "  curion                  Start the MCP stdio server (default). Speaks",
+    "                          JSON-RPC over stdin/stdout; logs travel on",
+    "                          stderr. Always launch through an MCP client",
+    "                          that manages the stdio transport.",
+    "",
+    "Options:",
+    "  -h, --help              Show this help and exit.",
+    "  -v, --version           Print the version and exit.",
+    "",
+    "Tools (over MCP):",
+    "  remember(text)          Store a piece of project memory.",
+    "  recall(text)            Retrieve the relevant pieces.",
+    "",
+    "Configuration:",
+    "  Curion is configured through environment variables passed by the",
+    "  parent process. It does not load .env files. The minimum is a",
+    "  primary provider:",
+    "    CURION_PRIMARY_API_KEY, CURION_PRIMARY_BASE_URL,",
+    "    CURION_PRIMARY_MODEL",
+    "  Optional: a fallback provider, semantic retrieval",
+    "  (CURION_SEMANTIC_ENABLED), and log level (CURION_LOG_LEVEL).",
+    "",
+    `Docs: ${DOCS_URL}`,
+    "",
+  ].join("\n");
+}

src/cli-help.ts

@@ -6,16 +6,76 @@
  * travel on stderr; this file is the single place where stdio is
  * wired up. Anything written to stdout will corrupt the MCP protocol
  * stream, so we use the stderr-only logger throughout.
+ *
+ * CLI flag interception:
+ *   - `--help` / `-h` print the help text (see `src/cli-help.ts`)
+ *     to stdout and exit 0.
+ *   - `--version` / `-v` print the package version (see
+ *     `src/version.js`) to stdout and exit 0.
+ *   - Both flag paths short-circuit BEFORE `initStorage()` so the
+ *     project-local `.curion/` directory is NEVER created for a
+ *     help/version invocation. The MCP stdio transport is also
+ *     never started for these invocations, so the JSON-RPC framing
+ *     on stdout is never contaminated by help/version output.
+ *   - The flag handlers do not call the logger (stderr stays
+ *     empty) so the help/version output is the only thing the
+ *     shell sees on either stream.
  */
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildHelpText } from "./cli-help.js";
 import { logger } from "./logging/logger.js";
 import { PUBLIC_TOOL_NAMES, buildServer } from "./server.js";
 import { closeStorage, initStorage } from "./storage/storage.js";
 import { setStorageProvider as setRecallStorageProvider } from "./tools/recall.js";
 import { setStorageProvider } from "./tools/remember.js";
+import { VERSION } from "./version.js";
+
+/**
+ * Recognized CLI flags. Each entry is a token that, when present
+ * in `argv`, triggers the matching handler. The order of this
+ * table defines the "first match wins" precedence when multiple
+ * recognized flags are passed in the same invocation.
+ */
+const HELP_FLAGS = new Set(["--help", "-h"]);
+const VERSION_FLAGS = new Set(["--version", "-v"]);
+
+/**
+ * Apply the help/version short-circuit. Returns `true` if a flag
+ * was handled (and `process.exit(0)` was called); `false` if the
+ * caller should continue with normal startup. Centralizing the
+ * short-circuit here keeps the entrypoint flow readable and lets
+ * the unit tests assert the helper in isolation from the rest of
+ * `main()`.
+ *
+ * The function intentionally calls `process.exit(0)` directly so
+ * no side effect from `main()` runs after a flag is matched.
+ */
+function maybeHandleCliFlags(argv: readonly string[]): boolean {
+  for (const arg of argv) {
+    if (HELP_FLAGS.has(arg)) {
+      process.stdout.write(buildHelpText(VERSION));
+      process.exit(0);
+    }
+    if (VERSION_FLAGS.has(arg)) {
+      // Plain version on a single line so scripts / CI can parse it.
+      process.stdout.write(`${VERSION}\n`);
+      process.exit(0);
+    }
+  }
+  return false;
+}
 
 async function main(): Promise<void> {
+  // CLI flag interception: --help / -h / --version / -v must
+  // short-circuit BEFORE any storage side effect (`.curion/`
+  // creation) or stdio transport setup. `maybeHandleCliFlags`
+  // calls `process.exit(0)` directly when a recognized flag is
+  // present, so no further code in `main()` runs for those
+  // invocations. Normal MCP stdio behavior is unchanged when no
+  // flag is passed.
+  maybeHandleCliFlags(process.argv.slice(2));
+
   // Initialize project-local storage. Side effect: creates .curion/ if
   // missing. Failures here are fatal — the server cannot run without
   // its data directory.

src/index.ts

@@ -71,6 +71,7 @@ import {
   buildRememberStructuredContent,
 } from "./tools/remember-projection.js";
 import { logger } from "./logging/logger.js";
+import { VERSION } from "./version.js";
 
 export const PUBLIC_TOOL_NAMES = ["remember", "recall"] as const;
 export type PublicToolName = (typeof PUBLIC_TOOL_NAMES)[number];
@@ -98,7 +99,12 @@ export function buildServer(options: BuildServerOptions = {}): McpServer {
   const server = new McpServer(
     {
       name: options.name ?? "curion",
-      version: options.version ?? "0.2.0",
+      // The package version is the single source of truth. `VERSION`
+      // is generated from `package.json#version` by
+      // `scripts/sync-version.mjs`, wired into `prebuild`/`pretest`
+      // so this value can never drift from a release tag. A caller
+      // may still override it via `options.version` for tests.
+      version: options.version ?? VERSION,
     },
     {
       capabilities: {