From 276856937ebb26dda9ea5ed0a16b919d25053e4e Mon Sep 17 00:00:00 2001
From: James Sesler <James.sesler@pm.me>
Date: Sun, 2 Aug 2026 12:51:42 -0400
Subject: [PATCH] docs: align npm package metadata with the new positioning
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

npm is the largest discovery surface here (~1,800 installs/month) and its
description still carried the pre-#77 pitch: "Evidence-backed reverse
engineering and human-gated software planning for Pi and MCP coding agents."
Same stale positioning already fixed in the README, the website, and the MCP
Registry entry.

Also adds the five keywords set as GitHub repo topics in #77 — codebase,
ai-agent, context-engineering, code-understanding, spec-driven — so the npm
and GitHub discovery surfaces match.

The test asserted the literal marketing sentence, which is why the copy went
stale: updating the description looked like breaking a test, so nobody did.
It now asserts the two product directions the check actually cares about
(analysis and planning) rather than exact phrasing, and requires the new
keywords. Verified the keyword check fails when one is removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 package.json                    |  9 +++++++--
 tests/release-metadata.test.mjs | 18 ++++++++++++++++--
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/package.json b/package.json
index 3836b5f..e321a0f 100644
--- a/package.json
+++ b/package.json
@@ -2,7 +2,7 @@
   "name": "codecartographer-pi",
   "version": "0.12.11",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
-  "description": "Evidence-backed reverse engineering and human-gated software planning for Pi and MCP coding agents.",
+  "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -13,7 +13,12 @@
     "mcp",
     "software-planning",
     "code-analysis",
-    "synthesis"
+    "synthesis",
+    "codebase",
+    "ai-agent",
+    "context-engineering",
+    "code-understanding",
+    "spec-driven"
   ],
   "license": "MIT",
   "author": "James Sesler",
diff --git a/tests/release-metadata.test.mjs b/tests/release-metadata.test.mjs
index e0be68b..96c2e2a 100644
--- a/tests/release-metadata.test.mjs
+++ b/tests/release-metadata.test.mjs
@@ -47,8 +47,15 @@ test("MCP Registry metadata identifies the published stdio package", () => {
 });
 
 test("npm metadata describes both product directions and preserves discovery terms", () => {
-	assert.match(pkg.description, /evidence-backed reverse engineering/i);
-	assert.match(pkg.description, /software planning/i);
+	// Assert on the two product directions, not on exact marketing phrasing —
+	// pinning the literal sentence means every copy change is a test edit, and
+	// the description then rots because updating it looks like breaking a test.
+	assert.match(
+		pkg.description,
+		/codebase|reverse[- ]engineer/i,
+		"description must cover the analysis direction",
+	);
+	assert.match(pkg.description, /plan/i, "description must cover the planning/synthesis direction");
 
 	const requiredKeywords = [
 		"codecartographer",
@@ -57,6 +64,13 @@ test("npm metadata describes both product directions and preserves discovery ter
 		"software-planning",
 		"code-analysis",
 		"synthesis",
+		// Mirror the GitHub repo topics set in #77 so the two discovery
+		// surfaces stay aligned.
+		"codebase",
+		"ai-agent",
+		"context-engineering",
+		"code-understanding",
+		"spec-driven",
 	];
 	for (const keyword of requiredKeywords) {
 		assert.ok(pkg.keywords?.includes(keyword), `package.json keywords must include ${keyword}`);