docs: align contributor quick-start and cypress command parity (#154)

Author: rendall

README.md

@@ -181,6 +181,13 @@ You can get your own free-tier MongoDB-in-the-cloud by [following these instruct
 
 Assumes a unix-like environment, like Ubuntu.
 
+### Contributor quick-start (canonical)
+
+- Use this `README.md` section as the canonical contributor entry point for install, run, and validation commands.
+- Use deeper docs as secondary references when needed:
+  - [`docs/norms/ci-parity.md`](./docs/norms/ci-parity.md) for CI/local parity governance details.
+  - [`docs/CYPRESS.md`](./docs/CYPRESS.md) for Cypress configuration and troubleshooting specifics.
+
 ### Installation
 
 1. Install [nvm](https://github.com/nvm-sh/nvm#installing-and-updating)
@@ -200,7 +207,17 @@ Assumes a unix-like environment, like Ubuntu.
 4. `yarn run ci:local`
    - Canonical parity reference for contributors: this command mirrors the required PR-gate validation path in `.github/workflows/netlify-api-test.yml`.
    - Intentionally not mirrored by this command: CodeQL/security-analysis workflows and CI runner/bootstrap steps (`actions/checkout`, `actions/setup-node`, global `npm install yarn@^1 -g`).
-5. `yarn run test:e2e`
+5. `yarn run test:cypress`
+
+### Validation matrix
+
+- **Required PR gate (parity path):**
+  - `yarn run ci:local`
+- **Deeper optional checks:**
+  - `yarn run test:cypress`
+- **Intentionally excluded from parity path:**
+  - CodeQL/security-analysis workflows.
+  - CI runner/bootstrap setup steps (for example `actions/checkout`, `actions/setup-node`, and global `npm install yarn@^1 -g`).
 
 ### Usage
 

docs/CYPRESS.md

@@ -2,6 +2,9 @@
 
 Simple Comment uses <https://cypress.io> for frontend browser validation.
 
+- Canonical script name: `yarn run test:cypress`
+- Primary contributor quick-start lives in `README.md`; this page is a deeper Cypress-specific reference.
+
 ## Current Layout
 
 - Cypress config: [cypress.config.ts](../cypress.config.ts)

docs/norms/ci-parity.md

@@ -8,6 +8,11 @@ Goal: prevent drift between PR-gate validation behavior and local pre-push valid
 
 Local parity in this repository applies to dependency-resolution + validation behavior.
 
+## Contributor Entry Point
+
+- Canonical quick-start and contributor command entry point: `README.md` (Local development section).
+- Secondary references: this document for parity governance details and `docs/CYPRESS.md` for Cypress-specific guidance.
+
 ## Required Parity
 
 - Local parity commands MUST run install with the same lockfile/options as the mirrored CI workflow.
@@ -25,3 +30,9 @@ Local parity in this repository applies to dependency-resolution + validation be
 - PR-gate workflow: `.github/workflows/netlify-api-test.yml`
 - Local parity script: `scripts/ci-local.sh`
 - Local parity command: `yarn run ci:local`
+
+## Validation Matrix
+
+- **Required PR gate (parity path):** `yarn run ci:local`
+- **Deeper optional checks:** `yarn run test:cypress`
+- **Intentionally excluded from parity path:** CI runner/bootstrap setup (`actions/checkout`, `actions/setup-node`, global tool install) and separate security-analysis workflows (for example CodeQL).

docs/plans/ValidationAndDocumentationTrustDraft.md

@@ -77,8 +77,7 @@ We likely want README and nearby contributor guidance to stop referencing stale
 
 Known examples worth checking during formal planning:
 
-- `README.md` references `yarn run test:e2e`
-- `package.json` currently exposes `test:cypress` rather than `test:e2e`
+- Historical drift to resolve: keep Cypress command references normalized to `yarn run test:cypress` across contributor docs and scripts.
 
 ### 4. Clear Separation Between Required and Optional Validation