feat: npm publish readiness — version, update-check, install scripts (#286–#289)

.reuse/dep5

@@ -1,7 +1,7 @@
 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Upstream-Name: git-mind
 Upstream-Contact: James Ross <james@flyingrobots.dev>
-Source: https://github.com/neuroglyph/git-mind
+Source: https://github.com/flyingrobots/git-mind
 
 Files: *
 Copyright: 2025-2026 James Ross

CHANGELOG.md

@@ -357,10 +357,10 @@ Complete rewrite from C23 to Node.js on `@git-stunts/git-warp`.
 - Docker-based CI/CD
 - All C-specific documentation
 
-[3.1.0]: https://github.com/neuroglyph/git-mind/releases/tag/v3.1.0
-[3.0.0]: https://github.com/neuroglyph/git-mind/releases/tag/v3.0.0
-[2.0.0-alpha.5]: https://github.com/neuroglyph/git-mind/releases/tag/v2.0.0-alpha.5
-[2.0.0-alpha.4]: https://github.com/neuroglyph/git-mind/releases/tag/v2.0.0-alpha.4
-[2.0.0-alpha.3]: https://github.com/neuroglyph/git-mind/releases/tag/v2.0.0-alpha.3
-[2.0.0-alpha.2]: https://github.com/neuroglyph/git-mind/releases/tag/v2.0.0-alpha.2
-[2.0.0-alpha.0]: https://github.com/neuroglyph/git-mind/releases/tag/v2.0.0-alpha.0
+[3.1.0]: https://github.com/flyingrobots/git-mind/releases/tag/v3.1.0
+[3.0.0]: https://github.com/flyingrobots/git-mind/releases/tag/v3.0.0
+[2.0.0-alpha.5]: https://github.com/flyingrobots/git-mind/releases/tag/v2.0.0-alpha.5
+[2.0.0-alpha.4]: https://github.com/flyingrobots/git-mind/releases/tag/v2.0.0-alpha.4
+[2.0.0-alpha.3]: https://github.com/flyingrobots/git-mind/releases/tag/v2.0.0-alpha.3
+[2.0.0-alpha.2]: https://github.com/flyingrobots/git-mind/releases/tag/v2.0.0-alpha.2
+[2.0.0-alpha.0]: https://github.com/flyingrobots/git-mind/releases/tag/v2.0.0-alpha.0

CONTRIBUTING.md

@@ -11,7 +11,7 @@ Thanks for your interest in contributing. This document covers the essentials.
 ## Setup
 
 ```bash
-git clone https://github.com/neuroglyph/git-mind.git
+git clone https://github.com/flyingrobots/git-mind.git
 cd git-mind
 npm install
 npm test

GUIDE.md

@@ -51,7 +51,7 @@ git-mind captures those relationships explicitly, so you can query them, visuali
 ### From source
 
 ```bash
-git clone https://github.com/neuroglyph/git-mind.git
+git clone https://github.com/flyingrobots/git-mind.git
 cd git-mind
 npm install
 ```
@@ -484,7 +484,7 @@ Status values are normalized on read — `Done`, `DONE`, `complete`, `finished`
 ### Custom views (programmatic)
 
 ```javascript
-import { defineView, renderView, loadGraph } from '@neuroglyph/git-mind';
+import { defineView, renderView, loadGraph } from '@flyingrobots/git-mind';
 
 defineView('my-view', (nodes, edges) => ({
   nodes: nodes.filter(n => n.startsWith('feature:')),
@@ -544,7 +544,7 @@ git mind import graph.yaml --dry-run
 ### Programmatic import
 
 ```javascript
-import { importFile, loadGraph } from '@neuroglyph/git-mind';
+import { importFile, loadGraph } from '@flyingrobots/git-mind';
 
 const graph = await loadGraph('.');
 const result = await importFile(graph, 'graph.yaml', { dryRun: false });
@@ -586,7 +586,7 @@ Edges created from directives get a confidence of **0.8** — high, but flagged
 ### Processing commits programmatically
 
 ```javascript
-import { processCommit, loadGraph } from '@neuroglyph/git-mind';
+import { processCommit, loadGraph } from '@flyingrobots/git-mind';
 
 const graph = await loadGraph('.');
 await processCommit(graph, {
@@ -641,7 +641,7 @@ When you run `git mind at <ref>`:
 ### Programmatic usage
 
 ```javascript
-import { loadGraph, getEpochForRef, computeStatus, getCurrentTick, recordEpoch } from '@neuroglyph/git-mind';
+import { loadGraph, getEpochForRef, computeStatus, getCurrentTick, recordEpoch } from '@flyingrobots/git-mind';
 
 const graph = await loadGraph('.');
 
@@ -745,7 +745,7 @@ import {
   defineView, renderView, listViews, classifyStatus,
   // Hooks
   parseDirectives, processCommit,
-} from '@neuroglyph/git-mind';
+} from '@flyingrobots/git-mind';
 ```
 
 ### Initialize and load

bin/git-mind.js

@@ -9,13 +9,29 @@ import { init, link, view, list, remove, nodes, status, at, importCmd, importMar
 import { parseDiffRefs, collectDiffPositionals } from '../src/diff.js';
 import { createContext } from '../src/context-envelope.js';
 import { registerBuiltinExtensions } from '../src/extension.js';
+import { VERSION, NAME } from '../src/version.js';
+import { createUpdateChecker, defaultPorts } from '../src/update-check.js';
 
 const args = process.argv.slice(2);
 const command = args[0];
 const cwd = process.cwd();
+const jsonMode = args.includes('--json');
+
+// Wire update checker — real adapters in production, no-op when suppressed
+const updateController = new AbortController();
+const checker = process.env.GIT_MIND_DISABLE_UPGRADE_CHECK
+  ? { getNotification: () => null, triggerCheck: () => {} }
+  : createUpdateChecker({
+    ...defaultPorts(`https://registry.npmjs.org/${NAME}/latest`),
+    currentVersion: VERSION,
+    packageName: NAME,
+  });
+checker.triggerCheck(updateController.signal);
 
 function printUsage() {
-  console.log(`Usage: git mind <command> [options]
+  console.log(`git-mind v${VERSION}
+
+Usage: git mind <command> [options]
 
 Context flags (read commands: view, nodes, status, export, doctor):
   --at <ref>                    Show graph as-of a git ref (HEAD~N, branch, SHA)
@@ -170,6 +186,12 @@ function extractPositionals(args) {
   return positionals;
 }
 
+// Handle --version / -v before the command switch
+if (command === '--version' || command === '-v') {
+  console.log(VERSION);
+  process.exit(0);
+}
+
 switch (command) {
   case 'init':
     await init(cwd);
@@ -499,3 +521,12 @@ switch (command) {
     process.exitCode = command ? 1 : 0;
     break;
 }
+
+// Cancel background fetch — don't hold the process open
+updateController.abort();
+
+// Show update notification on stderr (never in --json mode)
+if (!jsonMode) {
+  const note = checker.getNotification();
+  if (note) process.stderr.write(note);
+}

docs/contracts/cli/at.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/at.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/at.schema.json",
   "title": "git-mind at --json",
   "description": "Time-travel output from `git mind at <ref> --json`",
   "type": "object",

docs/contracts/cli/content-delete.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/content-delete.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/content-delete.schema.json",
   "title": "git-mind content delete --json",
   "description": "Content deletion result from `git mind content delete --json`",
   "type": "object",

docs/contracts/cli/content-meta.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/content-meta.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/content-meta.schema.json",
   "title": "git-mind content meta --json",
   "description": "Content metadata result from `git mind content meta --json`",
   "type": "object",

docs/contracts/cli/content-set.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/content-set.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/content-set.schema.json",
   "title": "git-mind content set --json",
   "description": "Content attachment result from `git mind content set --json`",
   "type": "object",

docs/contracts/cli/content-show.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/content-show.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/content-show.schema.json",
   "title": "git-mind content show --json",
   "description": "Content display result from `git mind content show --json`",
   "type": "object",

docs/contracts/cli/diff.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/diff.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/diff.schema.json",
   "title": "git-mind diff --json",
   "description": "Graph diff result from `git mind diff <ref-a>..<ref-b> --json`",
   "type": "object",

docs/contracts/cli/doctor.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/doctor.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/doctor.schema.json",
   "title": "git-mind doctor --json",
   "description": "Graph integrity check result from `git mind doctor --json`",
   "type": "object",

docs/contracts/cli/export-data.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/export-data.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/export-data.schema.json",
   "title": "git-mind export --json (stdout)",
   "description": "Graph data export from `git mind export --json` (stdout mode)",
   "type": "object",

docs/contracts/cli/export-file.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/export-file.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/export-file.schema.json",
   "title": "git-mind export --file --json",
   "description": "File export result from `git mind export --file <path> --json`",
   "type": "object",

docs/contracts/cli/extension-add.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/extension-add.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/extension-add.schema.json",
   "title": "git-mind extension add --json",
   "description": "Extension registration result from `git mind extension add --json`",
   "type": "object",

docs/contracts/cli/extension-list.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/extension-list.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/extension-list.schema.json",
   "title": "git-mind extension list --json",
   "description": "Registered extensions from `git mind extension list --json`",
   "type": "object",

docs/contracts/cli/extension-remove.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/extension-remove.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/extension-remove.schema.json",
   "title": "git-mind extension remove --json",
   "description": "Extension removal result from `git mind extension remove --json`",
   "type": "object",

docs/contracts/cli/extension-validate.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/extension-validate.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/extension-validate.schema.json",
   "title": "git-mind extension validate --json",
   "description": "Extension manifest validation result from `git mind extension validate --json`",
   "type": "object",

docs/contracts/cli/import.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/import.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/import.schema.json",
   "title": "git-mind import --json",
   "description": "Import result from `git mind import --json` or `git mind import --from-markdown --json`",
   "type": "object",

docs/contracts/cli/merge.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/merge.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/merge.schema.json",
   "title": "git-mind merge --json",
   "description": "Merge result from `git mind merge --json`",
   "type": "object",

docs/contracts/cli/node-detail.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/node-detail.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/node-detail.schema.json",
   "title": "git-mind nodes --id --json",
   "description": "Single node detail output from `git mind nodes --id <id> --json`",
   "type": "object",

docs/contracts/cli/node-list.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/node-list.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/node-list.schema.json",
   "title": "git-mind nodes --json",
   "description": "Node list output from `git mind nodes --json`",
   "type": "object",

docs/contracts/cli/review-batch.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/review-batch.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/review-batch.schema.json",
   "title": "git-mind review --batch --json",
   "description": "Batch review result from `git mind review --batch <action> --json`",
   "type": "object",

docs/contracts/cli/review-list.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/review-list.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/review-list.schema.json",
   "title": "git-mind review --json",
   "description": "Pending review list from `git mind review --json`",
   "type": "object",

docs/contracts/cli/set.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/set.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/set.schema.json",
   "title": "git-mind set --json",
   "description": "Output from `git mind set <nodeId> <key> <value> --json`",
   "type": "object",

docs/contracts/cli/status.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/status.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/status.schema.json",
   "title": "git-mind status --json",
   "description": "Graph status dashboard output from `git mind status --json`",
   "type": "object",

docs/contracts/cli/suggest.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/suggest.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/suggest.schema.json",
   "title": "git-mind suggest --json",
   "description": "AI-powered edge suggestion result from `git mind suggest --json`",
   "type": "object",

docs/contracts/cli/unset.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/unset.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/unset.schema.json",
   "title": "git-mind unset --json",
   "description": "Output from `git mind unset <nodeId> <key> --json`",
   "type": "object",

docs/contracts/cli/view-lens.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/view-lens.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/view-lens.schema.json",
   "title": "git-mind view with lenses --json",
   "description": "View output with lens chaining from `git mind view <name>:<lens1>:<lens2> --json`",
   "type": "object",

docs/contracts/cli/view-progress.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/neuroglyph/git-mind/docs/contracts/cli/view-progress.schema.json",
+  "$id": "https://github.com/flyingrobots/git-mind/docs/contracts/cli/view-progress.schema.json",
   "title": "git-mind view progress --json",
   "description": "Progress view output from `git mind view progress --json`",
   "type": "object",