docs(contributing): align test and UI guidance

tests/README.md

@@ -1,65 +1,79 @@
 # CCS Test Suite
 
-## Organization
+Root TypeScript and JavaScript tests run with Bun's test runner. Native shell,
+PowerShell, Docker, and standalone probes cover contracts that need a real
+platform or process boundary.
 
-```
-tests/
-├── unit/              # Module unit tests (Mocha)
-│   ├── glmt/          # Legacy GLMT transformer/internal compatibility tests
-│   └── delegation/    # Delegation module tests
-├── npm/               # npm package tests (Mocha)
-├── native/            # Native installation tests (bash/PowerShell)
-│   ├── unix/          # Unix/Linux/macOS tests
-│   └── windows/       # Windows PowerShell tests
-├── integration/       # Integration + smoke tests
-└── shared/            # Shared utilities
-    ├── fixtures/      # Test configuration and environment
-    ├── unit/          # Helper function tests
-    ├── helpers.sh     # Bash test utilities
-    └── test-data.js   # Test data for npm tests
-```
+## Ownership
 
-## Running Tests
+| Area | Path | Use for |
+| --- | --- | --- |
+| Unit | [`unit/`](./unit/) | Focused module and command behavior |
+| Integration | [`integration/`](./integration/) | Cross-module, process, proxy, auth, and web-server behavior |
+| End to end | [`e2e/`](./e2e/) | Packaged CLI workflows |
+| npm package | [`npm/`](./npm/) | Installation, exports, and package behavior |
+| Native | [`native/`](./native/) | Unix and Windows shell behavior |
+| Docker | [`docker/`](./docker/) | Compose and stable network/service contracts |
+| Documentation | [`docs/`](./docs/) | Repository documentation invariants |
+| Shared support | [`shared/`](./shared/) | Fixtures and helpers reused by suites |
+| Mocks | [`mocks/`](./mocks/) | Bounded test doubles and fixtures |
+
+Some source domains also keep focused tests in `src/**/__tests__/`. Follow the
+nearest established pattern and avoid moving tests solely for taxonomy.
+
+## Commands
+
+Commands are defined in [`../package.json`](../package.json). Bucket membership
+and execution live in
+[`../scripts/run-test-bucket.js`](../scripts/run-test-bucket.js).
 
 ```bash
-bun run test           # All automated tests (unit + integration + npm)
-bun run test:unit      # Unit tests only
-bun run test:npm       # npm package tests
-bun run test:native    # Native Unix tests (bash)
+bun run test:fast      # Fast Bun test bucket
+bun run test:slow      # Slow Bun test bucket
+bun run test:all       # All root non-e2e Bun test buckets
+bun run test:unit      # tests/unit
+bun run test:npm       # tests/npm
+bun run test:native    # Native Unix edge-case script
+bun run test:e2e       # tests/e2e with fail-fast and extended timeout
+bun run test           # Build, then test:all
 ```
 
-## Test Categories
+For the normal contributor gate:
 
-### Unit Tests (`unit/`)
-Module-level tests using Mocha framework:
-- `unit/glmt/` - Legacy transformer internals kept for Cursor translation compatibility
-- `unit/delegation/` - Permission mode, session manager, result formatter
+```bash
+bun run format
+bun run lint:fix
+bun run validate
+```
 
-### npm Tests (`npm/`)
-npm package functionality tests using Mocha:
-- `postinstall.test.js` - Postinstall behavior
-- `cli.test.js` - CLI argument parsing
-- `cross-platform.test.js` - Cross-platform compatibility
-- `special-commands.test.js` - Integration tests
+For the closest local equivalent to PR CI:
 
-### Native Tests (`native/`)
-Installation tests for curl|bash (Unix) and irm|iex (Windows):
-- `native/unix/edge-cases.sh` - Unix edge case tests
-- `native/windows/edge-cases.ps1` - Windows edge case tests
+```bash
+bun run validate:ci-parity
+```
 
-### Integration Tests (`integration/`)
-Integration and smoke coverage for scenarios that exercise multiple layers:
-- Automated `*.test.ts` files run as part of `bun run test:all` and CI
-- Shell and standalone probe scripts remain on-demand for targeted debugging
-- `cursor-daemon-lifecycle.test.ts` - local daemon process + HTTP smoke coverage
-- `image-analyzer-hook.test.ts` - hook integration coverage
-- `glmt-integration-test.sh` - legacy GLMT compatibility smoke probe
-- `symlink-chain-test.sh` - Symlink chain handling
-- `ux-integration-test.sh` - CLI UX integration
+Dashboard tests use Vitest and are documented in
+[`../ui/README.md`](../ui/README.md).
 
-## Adding New Tests
+## Test Isolation
 
-- **Unit tests**: Add to `unit/<module>/` for isolated module behavior
-- **npm tests**: Add to `npm/` for package behavior
-- **Native tests**: Add to `native/unix/` or `native/windows/`
-- **Integration tests**: Add automated cross-layer smoke coverage to `integration/*.test.ts`
+- Set `CCS_HOME` to a temporary directory.
+- Never read or modify a contributor's real `~/.ccs/` or `~/.claude/`.
+- Use `getCcsDir()` from
+  [`../src/utils/config-manager.ts`](../src/utils/config-manager.ts) for CCS
+  paths.
+- Keep fixtures deterministic and free of credentials or private account data.
+- Use real behavior at the boundary under test; do not weaken assertions to
+  hide regressions.
+
+## Adding Coverage
+
+- Add a focused unit test for isolated logic.
+- Add integration coverage when behavior crosses modules, processes, HTTP, or
+  persistence boundaries.
+- Add e2e coverage when command routing or packaged CLI behavior is the
+  contract.
+- Add native or Docker coverage only when platform/runtime behavior cannot be
+  represented faithfully in Bun tests.
+- Run the smallest relevant command first, then broaden to the contributor or
+  CI-parity gate when shared contracts changed.