Restore the published npm package identity users already install (#266)

Changing package.json from @imdeadpool/guardex to @imdeadpool/gitguardex created a separate npm package identity instead of renaming the existing registry entry. This restores the manifest, install/update copy, tutorial/docs assets, and regression tests to the package users can actually install today, and bumps the version so the next publish can succeed against the existing @imdeadpool/guardex release line.

Constraint: npm package names are immutable registry identities; changing name publishes a different package
Constraint: @imdeadpool/guardex@7.0.16 is already published on npm, so the revert must advance the version
Rejected: Keep @imdeadpool/gitguardex and only tweak docs | npm view returns 404 so install and self-update guidance would still point at a non-existent package
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Do not change package.json.name again without confirming the target package exists on npm and the next version is publishable
Tested: node --test --test-name-pattern "(default invocation checks for update and can auto-approve latest install|self-update verifies on-disk version after @latest install and retries with pinned version when stale|self-update restarts into the installed CLI after a successful on-disk upgrade|status --json returns cli, services, and repo summary|prompt outputs AI setup instructions|prompt --exec outputs command-only checklist|deprecated copy-commands alias still works and warns)" test/install.test.js; node --check bin/multiagent-safety.js; npm pack --dry-run; openspec validate agent-codex-restore-guardex-npm-package-name-2026-04-22-00-02 --type change --strict; openspec validate --specs; npm test
Not-tested: live npm publish; live GitHub release flow

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

README.md

@@ -1,9 +1,9 @@
 # GitGuardex — Guardian T-Rex for your repo
 
-[![npm version](https://img.shields.io/npm/v/%40imdeadpool%2Fgitguardex?label=npm&color=cb3837&logo=npm)](https://www.npmjs.com/package/@imdeadpool/gitguardex)
-[![npm downloads](https://img.shields.io/npm/dm/%40imdeadpool%2Fgitguardex?label=downloads&color=0b76c5)](https://www.npmjs.com/package/@imdeadpool/gitguardex)
+[![npm version](https://img.shields.io/npm/v/%40imdeadpool%2Fguardex?label=npm&color=cb3837&logo=npm)](https://www.npmjs.com/package/@imdeadpool/guardex)
+[![npm downloads](https://img.shields.io/npm/dm/%40imdeadpool%2Fguardex?label=downloads&color=0b76c5)](https://www.npmjs.com/package/@imdeadpool/guardex)
 [![GitHub stars](https://img.shields.io/github/stars/recodeee/gitguardex?label=stars&color=d4ac0d)](https://github.com/recodeee/gitguardex/stargazers)
-[![License](https://img.shields.io/npm/l/%40imdeadpool%2Fgitguardex?label=License&color=97ca00)](./LICENSE)
+[![License](https://img.shields.io/npm/l/%40imdeadpool%2Fguardex?label=License&color=97ca00)](./LICENSE)
 
 [![CI](https://img.shields.io/github/actions/workflow/status/recodeee/gitguardex/ci.yml?branch=main&label=CI)](https://github.com/recodeee/gitguardex/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/actions/workflow/status/recodeee/gitguardex/release.yml?label=Release)](https://github.com/recodeee/gitguardex/actions/workflows/release.yml)
@@ -44,7 +44,7 @@ GitGuardex exists to stop that loop. Every agent gets its own worktree, claims t
 <h3 align="center">Install in one line</h3>
 
 ```bash
-npm i -g @imdeadpool/gitguardex
+npm i -g @imdeadpool/guardex
 ```
 
 <p align="center">
@@ -55,8 +55,8 @@ npm i -g @imdeadpool/gitguardex
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@imdeadpool/gitguardex"><img alt="npm" src="https://img.shields.io/npm/v/%40imdeadpool%2Fgitguardex?label=latest&style=flat-square&color=cb3837&logo=npm&logoColor=white"></a>
-  <a href="https://www.npmjs.com/package/@imdeadpool/gitguardex"><img alt="downloads" src="https://img.shields.io/npm/dm/%40imdeadpool%2Fgitguardex?label=downloads&style=flat-square&color=0b76c5"></a>
+  <a href="https://www.npmjs.com/package/@imdeadpool/guardex"><img alt="npm" src="https://img.shields.io/npm/v/%40imdeadpool%2Fguardex?label=latest&style=flat-square&color=cb3837&logo=npm&logoColor=white"></a>
+  <a href="https://www.npmjs.com/package/@imdeadpool/guardex"><img alt="downloads" src="https://img.shields.io/npm/dm/%40imdeadpool%2Fguardex?label=downloads&style=flat-square&color=0b76c5"></a>
   <a href="https://github.com/recodeee/gitguardex/stargazers"><img alt="stars" src="https://img.shields.io/github/stars/recodeee/gitguardex?style=flat-square&color=d4ac0d"></a>
 </p>
 
@@ -83,12 +83,12 @@ Coming soon: [recodee.com](https://recodee.com) — live account health, usage,
 ## Quick start
 
 ```sh
-npm i -g @imdeadpool/gitguardex
+npm i -g @imdeadpool/guardex
 cd /path/to/your/repo
 gx setup
 ```
 
-That's it. New installs should use `@imdeadpool/gitguardex` so the published package matches the GitGuardex name. Setup installs hooks, scripts, templates, and scaffolds OpenSpec/caveman/OMX wiring. Aliases: `gx` (preferred), `gitguardex` (full), `guardex` (legacy compatibility).
+That's it. Install and update via `@imdeadpool/guardex`. Setup installs hooks, scripts, templates, and scaffolds OpenSpec/caveman/OMX wiring. Aliases: `gx` (preferred), `gitguardex` (full), `guardex` (legacy compatibility).
 
 ---
 
@@ -641,6 +641,11 @@ npm pack --dry-run
 <details>
 <summary><strong>v7.x</strong></summary>
 
+### v7.0.17
+- Restored the published npm package name to `@imdeadpool/guardex` after the `@imdeadpool/gitguardex` rename only changed the package identity locally and could not rename the existing npm registry entry.
+- README/install/tutorial/self-update surfaces now point back at `@imdeadpool/guardex` while keeping GitGuardex as the product/repo brand and `gitguardex` as the long-form command.
+- Bumped the release from `7.0.16` → `7.0.17` because `@imdeadpool/guardex@7.0.16` is already published on npm.
+
 ### v7.0.16
 - GitGuardex now publishes under the matching npm package name `@imdeadpool/gitguardex`, and install/help/docs surfaces point at the renamed package instead of the older `@imdeadpool/guardex` scope.
 - `gx doctor` now keeps nested repo repair runs visibly progressing, and overlapping integration work stays off the protected base branch instead of trying to merge back on `main`.

docs/images/install-hero.svg

@@ -4,7 +4,7 @@ Source baseline: [`README.md`](../README.md)
 
 Project links:
 - GitHub: https://github.com/recodeecom/multiagent-safety
-- npm: https://www.npmjs.com/package/@imdeadpool/gitguardex
+- npm: https://www.npmjs.com/package/@imdeadpool/guardex
 
 ## Recommended Title Options
 
@@ -29,7 +29,7 @@ What it does:
 Quick start:
 
 ```bash
-npm i -g @imdeadpool/gitguardex
+npm i -g @imdeadpool/guardex
 gx setup
 ```
 
@@ -45,7 +45,7 @@ bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)
 If you run Codex/Claude-style parallel workflows, I would value feedback on edge cases your team hits in production.
 
 GitHub: https://github.com/recodeecom/multiagent-safety  
-npm: https://www.npmjs.com/package/@imdeadpool/gitguardex
+npm: https://www.npmjs.com/package/@imdeadpool/guardex
 
 ## Copy-Ready Reddit Post (short)
 
@@ -54,12 +54,12 @@ I open-sourced **GitGuardex** for safer multi-agent Git workflows.
 It adds branch/worktree guardrails, protected-branch enforcement, file-lock ownership, and repair scripts (`gx setup` / `gx doctor`) so parallel agent execution is safer by default.
 
 ```bash
-npm i -g @imdeadpool/gitguardex
+npm i -g @imdeadpool/guardex
 gx setup
 ```
 
 GitHub: https://github.com/recodeecom/multiagent-safety  
-npm: https://www.npmjs.com/package/@imdeadpool/gitguardex
+npm: https://www.npmjs.com/package/@imdeadpool/guardex
 
 ## Images to include in the Reddit post
 

docs/images/setup-success.svg

@@ -126,7 +126,7 @@ interface ModeGuide {
 }
 
 const MODE_ORDER: ModeKey[] = ['execute', 'plan', 'merge', 'installation']
-const INSTALL_COMMAND = 'npm i -g @imdeadpool/gitguardex'
+const INSTALL_COMMAND = 'npm i -g @imdeadpool/guardex'
 const PRODUCT_LABEL = 'Recodee'
 const EDITOR_LABEL = 'recodee — VS Code'
 
@@ -1697,7 +1697,7 @@ const INSTALL_STEPS: TutorialStep[] = [
         sub: '· global install',
         elapsed: '3.8s',
         rows: [
-          { kind: 'shell', label: 'bash:', value: 'npm i -g @imdeadpool/gitguardex' },
+          { kind: 'shell', label: 'bash:', value: 'npm i -g @imdeadpool/guardex' },
         ],
       },
     ],
@@ -1712,7 +1712,7 @@ const INSTALL_STEPS: TutorialStep[] = [
     ],
     worktrees: [],
     codeLines: [
-      { parts: [c('$ npm i -g @imdeadpool/gitguardex', 'c')] },
+      { parts: [c('$ npm i -g @imdeadpool/guardex', 'c')] },
       { parts: [c('added 1 package in 3.8s')] },
       { parts: [c('')] },
       { parts: [c('$ gx --version')] },

docs/images/status-tools-logs.svg

@@ -0,0 +1,17 @@
+## Why
+
+- The repo changed `package.json.name` to `@imdeadpool/gitguardex`, but npm treats a package name change as a different package identity, not a rename of the existing registry entry.
+- The live npm registry still serves `@imdeadpool/guardex@7.0.16`, while `npm view @imdeadpool/gitguardex version` returns `404`.
+- README, tutorial, Reddit kit, and self-update expectations now point at a package name that is not the install target users actually have.
+
+## What Changes
+
+- Restore the published package metadata to `@imdeadpool/guardex`.
+- Bump the package version from `7.0.16` to `7.0.17` so the next publish is valid against the existing `@imdeadpool/guardex@7.0.16` release.
+- Refresh install, self-update, tutorial, and README-linked asset surfaces to reference `@imdeadpool/guardex`.
+
+## Compatibility
+
+- Keep `gx` as the preferred short command.
+- Keep `gitguardex` as the long-form command and product/repo brand.
+- Keep `guardex` as the legacy compatibility bin alias.

docs/images/workflow-gx-terminal-status.svg

@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: Published npm package name stays on the existing guardex registry entry
+The system SHALL publish and document the primary npm package as `@imdeadpool/guardex`.
+
+#### Scenario: package metadata advertises the existing package
+- **WHEN** the root `package.json` metadata is inspected
+- **THEN** `name` equals `@imdeadpool/guardex`
+- **AND** downstream package metadata snapshots use the same package name.
+
+#### Scenario: the next release stays publishable on npm
+- **WHEN** the package metadata is prepared for the next publish
+- **THEN** the version is greater than the already-published `@imdeadpool/guardex@7.0.16`
+- **AND** the package can publish without colliding with the existing registry version.
+
+### Requirement: Install and update guidance references the real npm package
+The README, tutorial UI, and self-update/install guidance SHALL use `@imdeadpool/guardex` while keeping GitGuardex as the product brand.
+
+#### Scenario: install and self-update prompts use the restored package
+- **WHEN** a user reads CLI install/setup guidance or the self-update flow
+- **THEN** the npm command examples reference `@imdeadpool/guardex`
+- **AND** the CLI keeps `gx`, `gitguardex`, and `guardex` command compatibility.
+
+#### Scenario: docs and README-linked assets are aligned
+- **WHEN** the README, tutorial page, Reddit kit, or README-linked SVG assets are inspected
+- **THEN** install commands, npm badges, and package-name callouts reference `@imdeadpool/guardex`
+- **AND** GitGuardex remains the visible product/repo name.

docs/redditpost.md

@@ -0,0 +1,23 @@
+## 1. Spec
+
+- [x] 1.1 Capture why the npm package rename has to revert and the versioning constraint for the next publish.
+
+## 2. Tests
+
+- [x] 2.1 Update the package-name-dependent install/self-update/status assertions back to `@imdeadpool/guardex`.
+
+## 3. Implementation
+
+- [x] 3.1 Restore package metadata to `@imdeadpool/guardex` and bump the package version to `7.0.17`.
+- [x] 3.2 Refresh README, tutorial, Reddit kit, and README-linked assets to reference `@imdeadpool/guardex`.
+
+## 4. Verification
+
+- [x] 4.1 Run targeted package-name verification (`node --test --test-name-pattern "(default invocation checks for update and can auto-approve latest install|self-update verifies on-disk version after @latest install and retries with pinned version when stale|self-update restarts into the installed CLI after a successful on-disk upgrade|status --json returns cli, services, and repo summary|prompt outputs AI setup instructions|prompt --exec outputs command-only checklist|deprecated copy-commands alias still works and warns)" test/install.test.js`, `node --check bin/multiagent-safety.js`, `npm pack --dry-run`) and record the results. Result: targeted package-name verification passed `7/7`; `node --check bin/multiagent-safety.js` passed; `npm pack --dry-run` produced `imdeadpool-guardex-7.0.17.tgz`.
+- [x] 4.2 Run `openspec validate agent-codex-restore-guardex-npm-package-name-2026-04-22-00-02 --type change --strict`. Result: `Change 'agent-codex-restore-guardex-npm-package-name-2026-04-22-00-02' is valid`.
+- [x] 4.3 Run `openspec validate --specs`. Result: `No items found to validate.`
+- [x] 4.4 Run `npm test` after the package-name revert to confirm broader repo integrity. Result: full suite passed `163/163`.
+
+## 5. Cleanup
+
+- [ ] 5.1 Finish branch via PR merge + cleanup and record final `MERGED` evidence.