From 0852fcd56356a7700266b24927d84c44a1896142 Mon Sep 17 00:00:00 2001
From: Ivan Matveev <ivan.matveev@dif.tech>
Date: Sun, 31 May 2026 14:03:41 +0200
Subject: [PATCH] docs: link README navigation

---
 .changeset/readme-nav-links.md  |  5 +++++
 README.md                       |  8 ++++----
 package.json                    |  6 ++++--
 scripts/sync-readme-version.mjs | 24 ++++++++++++++++++++++++
 4 files changed, 37 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/readme-nav-links.md
 create mode 100644 scripts/sync-readme-version.mjs

diff --git a/.changeset/readme-nav-links.md b/.changeset/readme-nav-links.md
new file mode 100644
index 0000000..a18c099
--- /dev/null
+++ b/.changeset/readme-nav-links.md
@@ -0,0 +1,5 @@
+---
+"@vndv/pi-codegraph": patch
+---
+
+Link the README navigation items to their sections.
diff --git a/README.md b/README.md
index 7e11162..6581df2 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # pi-codegraph
 ### CodeGraph tools for pi
 
-Install · Usage · How it works
+[Install](#install) · [Usage](#usage) · [How it works](#how-it-works)
 
 Ask pi structural questions about your codebase without falling back to slow grep/read loops.
 
@@ -15,7 +15,7 @@ An extension for [pi](https://pi.dev) that gives the agent access to [CodeGraph]
 npm install -g @colbymchenry/codegraph
 cd /path/to/project
 codegraph init -i
-pi install npm:@vndv/pi-codegraph@0.1.1
+pi install npm:@vndv/pi-codegraph@0.1.4
 pi
 ```
 
@@ -51,7 +51,7 @@ Extension tools only. There is no MCP setup for pi users to maintain.
 From npm:
 
 ```bash
-pi install npm:@vndv/pi-codegraph@0.1.1
+pi install npm:@vndv/pi-codegraph@0.1.4
 ```
 
 From GitHub:
@@ -160,7 +160,7 @@ That means another developer only needs the npm package, the `codegraph` CLI, an
 Remove the package using the same source shown by `pi list`:
 
 ```bash
-pi remove npm:@vndv/pi-codegraph@0.1.1
+pi remove npm:@vndv/pi-codegraph@0.1.4
 ```
 
 If you installed from GitHub or a local path, remove that exact entry instead:
diff --git a/package.json b/package.json
index 8478d4f..924d310 100644
--- a/package.json
+++ b/package.json
@@ -35,7 +35,8 @@
     ]
   },
   "scripts": {
-    "ci": "npm run typecheck && npm test && npm run compat:codegraph && npm pack --dry-run",
+    "check:readme-version": "node scripts/sync-readme-version.mjs --check",
+    "ci": "npm run typecheck && npm test && npm run compat:codegraph && npm run check:readme-version && npm pack --dry-run",
     "compat:codegraph": "codegraph --version",
     "local-release": "changeset version && changeset publish",
     "publish-packages": "node -e \"const {execSync}=require('node:child_process'); const p=require('./package.json'); const spec=p.name+'@'+p.version; try { execSync('npm view '+spec+' version', {stdio:'ignore'}); console.log(spec+' already published; skipping.'); } catch { execSync('npm publish --access public --provenance --ignore-scripts', {stdio:'inherit'}); }\"",
@@ -43,7 +44,8 @@
     "prepublishOnly": "npm run ci",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "version-packages": "changeset version && npm install --package-lock-only --ignore-scripts"
+    "sync:readme-version": "node scripts/sync-readme-version.mjs",
+    "version-packages": "changeset version && npm run sync:readme-version && npm install --package-lock-only --ignore-scripts"
   },
   "engines": {
     "node": ">=22.19.0 <25"
diff --git a/scripts/sync-readme-version.mjs b/scripts/sync-readme-version.mjs
new file mode 100644
index 0000000..41565d1
--- /dev/null
+++ b/scripts/sync-readme-version.mjs
@@ -0,0 +1,24 @@
+import { readFile, writeFile } from 'node:fs/promises';
+
+const checkOnly = process.argv.includes('--check');
+const packageJson = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+const readmeUrl = new URL('../README.md', import.meta.url);
+const readme = await readFile(readmeUrl, 'utf8');
+const packageName = packageJson.name;
+const version = packageJson.version;
+const installPattern = new RegExp(`npm:${packageName.replaceAll('/', '\\/')}@\\d+\\.\\d+\\.\\d+`, 'g');
+const expected = `npm:${packageName}@${version}`;
+const updated = readme.replace(installPattern, expected);
+
+if (updated === readme) {
+  console.log(`README package version already ${version}.`);
+  process.exit(0);
+}
+
+if (checkOnly) {
+  console.error(`README package version is stale. Run npm run sync:readme-version.`);
+  process.exit(1);
+}
+
+await writeFile(readmeUrl, updated);
+console.log(`Updated README package references to ${version}.`);