From 177b8f31da1f51e5f1c7d00900b08dc31e6af247 Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Thu, 23 Apr 2026 02:11:29 -0400 Subject: [PATCH] docs: clarify install and uninstall paths --- README.md | 69 ++++++++++++++- tests/scripts/install-readme-clarity.test.js | 88 ++++++++++++++++++++ 2 files changed, 154 insertions(+), 3 deletions(-) create mode 100644 tests/scripts/install-readme-clarity.test.js diff --git a/README.md b/README.md index d5c65da6..9005dbca 100644 --- a/README.md +++ b/README.md @@ -167,7 +167,17 @@ See the full changelog in [Releases](https://github.com/affaan-m/everything-clau Get up and running in under 2 minutes: -### Step 1: Install the Plugin +### Pick one path only + +Most Claude Code users should use exactly one install path: + +- **Recommended default:** install the Claude Code plugin, then copy only the rule folders you actually want. +- **Use the manual installer only if** you want finer-grained control, want to avoid the plugin path entirely, or your Claude Code build has trouble resolving the self-hosted marketplace entry. +- **Do not stack install methods.** The most common broken setup is: `/plugin install` first, then `install.sh --profile full` or `npx ecc-install --profile full` afterward. + +If you already layered multiple installs and things look duplicated, skip straight to [Reset / Uninstall ECC](#reset--uninstall-ecc). + +### Step 1: Install the Plugin (Recommended) > NOTE: The plugin is convenient, but the OSS installer below is still the most reliable path if your Claude Code build has trouble resolving self-hosted marketplace entries. @@ -195,9 +205,11 @@ This is intentional. Anthropic marketplace/plugin installs are keyed by a canoni > > If you already installed ECC via `/plugin install`, **do not run `./install.sh --profile full`, `.\install.ps1 --profile full`, or `npx ecc-install --profile full` afterward**. The plugin already loads ECC skills, commands, and hooks. Running the full installer after a plugin install copies those same surfaces into your user directories and can create duplicate skills plus duplicate runtime behavior. > -> For plugin installs, manually copy only the `rules/` directories you want. Use the full installer only when you are doing a fully manual ECC install instead of the plugin path. +> For plugin installs, manually copy only the `rules/` directories you want. Start with `rules/common` plus one language or framework pack you actually use. Do not copy every rules directory unless you explicitly want all of that context in Claude. > -> If your local Claude setup was wiped or reset, that does not mean you need to repurchase ECC. Start with `ecc list-installed`, then run `ecc doctor` and `ecc repair` before reinstalling anything. That usually restores ECC-managed files without rebuilding your setup. If the problem is account or marketplace access for ECC Tools, handle billing/account recovery separately. +> Use the full installer only when you are doing a fully manual ECC install instead of the plugin path. +> +> If your local Claude setup was wiped or reset, that does not mean you need to repurchase ECC. Start with `node scripts/ecc.js list-installed`, then run `node scripts/ecc.js doctor` and `node scripts/ecc.js repair` before reinstalling anything. That usually restores ECC-managed files without rebuilding your setup. If the problem is account or marketplace access for ECC Tools, handle billing/account recovery separately. ```bash # Clone the repo first @@ -231,6 +243,57 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/" For manual install instructions see the README in the `rules/` folder. When copying rules manually, copy the whole language directory (for example `rules/common` or `rules/golang`), not the files inside it, so relative references keep working and filenames do not collide. +### Fully manual install (Fallback) + +Use this only if you are intentionally skipping the plugin path: + +```bash +./install.sh --profile full +``` + +```powershell +.\install.ps1 --profile full +# or +npx ecc-install --profile full +``` + +If you choose this path, stop there. Do not also run `/plugin install`. + +### Reset / Uninstall ECC + +If ECC feels duplicated, intrusive, or broken, do not keep reinstalling it on top of itself. + +- **Plugin path:** remove the plugin from Claude Code, then delete the specific rule folders you manually copied under `~/.claude/rules/`. +- **Manual installer / CLI path:** from the repo root, preview removal first: + +```bash +node scripts/uninstall.js --dry-run +``` + +Then remove ECC-managed files: + +```bash +node scripts/uninstall.js +``` + +You can also use the lifecycle wrapper: + +```bash +node scripts/ecc.js list-installed +node scripts/ecc.js doctor +node scripts/ecc.js repair +node scripts/ecc.js uninstall --dry-run +``` + +ECC only removes files recorded in its install-state. It will not delete unrelated files it did not install. + +If you stacked methods, clean up in this order: + +1. Remove the Claude Code plugin install. +2. Run the ECC uninstall command from the repo root to remove install-state-managed files. +3. Delete any extra rule folders you copied manually and no longer want. +4. Reinstall once, using a single path. + ### Step 3: Start Using ```bash diff --git a/tests/scripts/install-readme-clarity.test.js b/tests/scripts/install-readme-clarity.test.js new file mode 100644 index 00000000..a6029eda --- /dev/null +++ b/tests/scripts/install-readme-clarity.test.js @@ -0,0 +1,88 @@ +/** + * Regression coverage for install/uninstall clarity in README.md. + */ + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); + +const README = path.join(__dirname, '..', '..', 'README.md'); + +function test(name, fn) { + try { + fn(); + console.log(` \u2713 ${name}`); + return true; + } catch (error) { + console.log(` \u2717 ${name}`); + console.log(` Error: ${error.message}`); + return false; + } +} + +function runTests() { + console.log('\n=== Testing install README clarity ===\n'); + + let passed = 0; + let failed = 0; + + const readme = fs.readFileSync(README, 'utf8'); + + if (test('README marks one default path and warns against stacked installs', () => { + assert.ok( + readme.includes('### Pick one path only'), + 'README should surface a top-level install decision section' + ); + assert.ok( + readme.includes('**Recommended default:** install the Claude Code plugin'), + 'README should name the recommended default install path' + ); + assert.ok( + readme.includes('**Do not stack install methods.**'), + 'README should explicitly warn against stacking install methods' + ); + assert.ok( + readme.includes('If you choose this path, stop there. Do not also run `/plugin install`.'), + 'README should tell manual-install users not to continue layering installs' + ); + })) passed++; else failed++; + + if (test('README documents reset and uninstall flow', () => { + assert.ok( + readme.includes('### Reset / Uninstall ECC'), + 'README should have a visible reset/uninstall section' + ); + assert.ok( + readme.includes('node scripts/uninstall.js --dry-run'), + 'README should document dry-run uninstall' + ); + assert.ok( + readme.includes('node scripts/ecc.js list-installed'), + 'README should document install-state inspection before reinstalling' + ); + assert.ok( + readme.includes('node scripts/ecc.js doctor'), + 'README should document doctor before reinstalling' + ); + assert.ok( + readme.includes('ECC only removes files recorded in its install-state.'), + 'README should explain uninstall safety boundaries' + ); + })) passed++; else failed++; + + if (test('README explains plugin-path cleanup and rules scoping', () => { + assert.ok( + readme.includes('remove the plugin from Claude Code'), + 'README should tell plugin users how to start cleanup' + ); + assert.ok( + readme.includes('Start with `rules/common` plus one language or framework pack you actually use.'), + 'README should steer users away from copying every rules directory' + ); + })) passed++; else failed++; + + console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests();