docs: align rules README install namespace (#1916)

docs: align rules README install namespace

rules/README.md

@@ -55,25 +55,40 @@ rules/
 > Flattening them into one directory causes language-specific files to overwrite
 > common rules, and breaks the relative `../common/` references used by
 > language-specific files.
+>
+> Use the ECC-owned namespace below for user-level Claude installs. Flat
+> package-level destinations can collide with non-ECC rule packs and do not
+> match the main README guidance.
 
 ```bash
+# Create the ECC rule namespace once.
+mkdir -p ~/.claude/rules/ecc
+
 # Install common rules (required for all projects)
-cp -r rules/common ~/.claude/rules/common
+cp -r rules/common ~/.claude/rules/ecc/
 
 # Install language-specific rules based on your project's tech stack
-cp -r rules/typescript ~/.claude/rules/typescript
-cp -r rules/angular ~/.claude/rules/angular
-cp -r rules/python ~/.claude/rules/python
-cp -r rules/golang ~/.claude/rules/golang
-cp -r rules/web ~/.claude/rules/web
-cp -r rules/swift ~/.claude/rules/swift
-cp -r rules/php ~/.claude/rules/php
-cp -r rules/ruby ~/.claude/rules/ruby
-cp -r rules/arkts ~/.claude/rules/arkts
+cp -r rules/typescript ~/.claude/rules/ecc/
+cp -r rules/angular ~/.claude/rules/ecc/
+cp -r rules/python ~/.claude/rules/ecc/
+cp -r rules/golang ~/.claude/rules/ecc/
+cp -r rules/web ~/.claude/rules/ecc/
+cp -r rules/swift ~/.claude/rules/ecc/
+cp -r rules/php ~/.claude/rules/ecc/
+cp -r rules/ruby ~/.claude/rules/ecc/
+cp -r rules/arkts ~/.claude/rules/ecc/
 
 # Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only.
 ```
 
+For project-local rules, use the same namespace under the project root:
+
+```bash
+mkdir -p .claude/rules/ecc
+cp -r rules/common .claude/rules/ecc/
+cp -r rules/typescript .claude/rules/ecc/
+```
+
 ## Rules vs Skills
 
 - **Rules** define standards, conventions, and checklists that apply broadly (e.g., "80% test coverage", "no hardcoded secrets").

tests/scripts/install-readme-clarity.test.js

@@ -7,6 +7,7 @@ const fs = require('fs');
 const path = require('path');
 
 const README = path.join(__dirname, '..', '..', 'README.md');
+const RULES_README = path.join(__dirname, '..', '..', 'rules', 'README.md');
 
 function test(name, fn) {
   try {
@@ -27,6 +28,7 @@ function runTests() {
   let failed = 0;
 
   const readme = fs.readFileSync(README, 'utf8');
+  const rulesReadme = fs.readFileSync(RULES_README, 'utf8');
 
   if (test('README marks one default path and warns against stacked installs', () => {
     assert.ok(
@@ -138,6 +140,29 @@ function runTests() {
     );
   })) passed++; else failed++;
 
+  if (test('rules README mirrors ECC namespaced install path', () => {
+    assert.ok(
+      rulesReadme.includes('mkdir -p ~/.claude/rules/ecc'),
+      'rules README should create the ECC-owned user-level rules namespace'
+    );
+    assert.ok(
+      rulesReadme.includes('cp -r rules/common ~/.claude/rules/ecc/'),
+      'rules README should copy common rules under ~/.claude/rules/ecc/'
+    );
+    assert.ok(
+      rulesReadme.includes('cp -r rules/typescript ~/.claude/rules/ecc/'),
+      'rules README should copy language rules under ~/.claude/rules/ecc/'
+    );
+    assert.ok(
+      rulesReadme.includes('mkdir -p .claude/rules/ecc'),
+      'rules README should document the project-local ECC namespace'
+    );
+    assert.ok(
+      !rulesReadme.includes('~/.claude/rules/typescript'),
+      'rules README should not recommend flat user-level rule destinations'
+    );
+  })) passed++; else failed++;
+
   console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
   process.exit(failed > 0 ? 1 : 0);
 }