Upload files to "/"

README.md

@@ -1,2 +1,70 @@
-# TS-CUCUMBER-WDIO-QK
+# QKForce Framework CWQ
 
+The QKForce browser-automation template is the fixed `TypeScript + Cucumber + WebdriverIO + QKTestAnalytics` profile.
+
+## Contract status
+
+CWQ consumes the central v1.1 run config and optional package-local version-locked CSV inputs before WDIO starts. It does not create packages or receive results; those are API/Client responsibilities. The remaining documentation/operational concern is a verifiable required CI check, tracked in [CWQ #6](https://github.com/QACGBDT/QKForce-Framework-CWQ/issues/6).
+
+## Run
+
+```bash
+npm ci
+npm run qkforce:test
+npm run qkforce:report
+```
+
+`qkforce:test` is the only execution entry point used by QKForce Client. Results belong under `qreport-results/`; raw test-data CSV files must not be copied into results archives.
+
+## Immutable run configuration
+
+Every v1.1 workspace contains `qkforce.config.json` with numeric `schemaVersion: 1`, fixed profile id `qkforce-wdio-cucumber-qkta`, and `run.targetUrl`. The loader rejects unknown fields, non-fixed profiles, credentials/query/fragment URLs, non-HTTPS non-loopback targets, and target URLs over 2048 UTF-8 bytes.
+
+```json
+{
+  "schemaVersion": 1,
+  "profile": {
+    "id": "qkforce-wdio-cucumber-qkta",
+    "language": "typescript",
+    "bdd": "cucumber",
+    "runner": "webdriverio",
+    "adapter": "webdriverio-cucumber-node",
+    "reporter": "qk-test-analytics"
+  },
+  "run": { "targetUrl": "https://example.test" }
+}
+```
+
+## Version-locked CSV test data
+
+When test data is bound, QKForce materializes only immutable selected CSV versions below `test-data/` and writes `qkforce.test-data.lock.json`. No lock is required for executions without bound test data. The framework preflights every present lock before WDIO starts and never fetches live data.
+
+Validation covers schema version, unknown/duplicate metadata, safe package-local `test-data/*.csv` paths, regular-file/symlink checks, SHA-256, UTF-8, RFC-4180 quoting, unique headers and declared row count.
+
+Use the typed step-definition helper:
+
+```ts
+import { Given } from '@wdio/cucumber-framework';
+import { loadTestData } from '../support/test-data.js';
+
+const testData = loadTestData();
+
+Given('I use customer {string}', async (id: string) => {
+  const customer = testData.dataset('customers').first({ id });
+  await $('#username').setValue(customer.name);
+});
+```
+
+Rows are immutable and scenario selection is never stored in global mutable state. Use `row(index)`, `where({...})` or `first({...})` for deterministic addressing. `typedRow(index, schema)` supports `string`, `integer`, `number`, `boolean` (`true`/`false`) and ISO `date` (`YYYY-MM-DD`); `{ type, nullable: true }` maps an empty cell to `null`.
+
+Diagnostics identify dataset/version, row and column without printing cell contents. `provenance()` returns only `testDataLockSha256` and `{datasetId, versionId, sha256}` entries, matching the QKForce results-manifest contract without raw CSV values.
+
+Starter positive/negative fixtures live under `test/fixtures/test-data/`. Execution-specific CSV files are generated by QKForce and should not be hand-edited in the template.
+
+Run non-browser validation with:
+
+```bash
+npm run check
+```
+
+Active development is performed on `develop`.