Dry run and operator handbook

docs/LOCAL-RUNBOOK.md

@@ -0,0 +1,167 @@
+# Local OpenCMIS TCK Runbook
+
+Status: draft
+Created: 2026-05-08
+
+## Purpose
+
+This runbook is the workstation path from a clean checkout to the first local
+OpenCMIS TCK run through guide-board.
+
+The local path has two stages:
+
+1. Prove the guide-board/OpenCMIS adapter wiring with the dry-run profile.
+2. Install Java/Maven, resolve the OpenCMIS TCK runtime, and run the real
+   ConsoleRunner profile.
+
+## Prerequisites
+
+The extension and guide-board repositories should be siblings:
+
+```text
+/home/worsch/guide-board
+/home/worsch/open-cmis-tck
+```
+
+The guide-board core is used from source:
+
+```sh
+cd /home/worsch/guide-board
+PYTHONPATH=src python3 -m guide_board --extension-dir ../open-cmis-tck extensions validate
+```
+
+## Dry-Run Adapter Check
+
+The dry-run profile verifies profile resolution, CMIS preflight, wrapper
+invocation, ConsoleRunner adapter argument expansion, session file generation,
+artifact references, mapping, and report creation. It does not require Java or
+Maven.
+
+Start or point to a CMIS Browser Binding endpoint, then run:
+
+```sh
+cd /home/worsch/guide-board
+PYTHONPATH=src python3 -m guide_board \
+  --extension-dir ../open-cmis-tck \
+  run \
+  --target ../open-cmis-tck/profiles/targets/kontextual-cmis-compat.json \
+  --assessment ../open-cmis-tck/profiles/assessments/cmis-browser-local-dry-run.json \
+  --output-dir /tmp/open-cmis-tck-dry-run
+```
+
+Expected dry-run artifacts:
+
+```text
+/tmp/open-cmis-tck-dry-run/reports/report.md
+/tmp/open-cmis-tck-dry-run/reports/assessment-package.json
+/tmp/open-cmis-tck-dry-run/normalized/evidence.json
+/tmp/open-cmis-tck-dry-run/artifacts/open-cmis-tck/tck/repository-type/session.properties.redacted
+/tmp/open-cmis-tck-dry-run/artifacts/open-cmis-tck/tck/repository-type/groups.txt
+```
+
+If preflight fails, fix the target profile or endpoint before continuing.
+
+## Install Java And Maven
+
+The current WSL environment needs Java and Maven before the real TCK can run:
+
+```sh
+sudo apt-get update
+sudo apt-get install -y openjdk-17-jdk maven
+```
+
+Use a managed local Java/Maven installation instead if preferred. The bootstrap
+only requires `java` and `mvn` on `PATH`.
+
+## Resolve The TCK Runtime
+
+```sh
+cd /home/worsch/open-cmis-tck
+PYTHONPATH=src python3 scripts/bootstrap_opencmis_tck.py --resolve
+```
+
+This resolves:
+
+```text
+org.apache.chemistry.opencmis:chemistry-opencmis-test-tck:1.1.0
+```
+
+into the local Maven cache and writes:
+
+```text
+.local/opencmis-tck/runtime-summary.json
+```
+
+The `.local/` directory is ignored and must not be committed.
+
+## Real TCK Run
+
+After bootstrap reports `ready`, run the baseline assessment:
+
+```sh
+cd /home/worsch/guide-board
+PYTHONPATH=src python3 -m guide_board \
+  --extension-dir ../open-cmis-tck \
+  run \
+  --target ../open-cmis-tck/profiles/targets/kontextual-cmis-compat.json \
+  --assessment ../open-cmis-tck/profiles/assessments/cmis-browser-baseline.json \
+  --output-dir /tmp/open-cmis-tck-live
+```
+
+The baseline currently selects:
+
+- `repository-type`
+- `object-content`
+
+Expand selected check groups only after the repository/type run produces useful
+output.
+
+## Authenticated Targets
+
+For environment credentials:
+
+```sh
+export CMIS_TCK_USER='cmis-user'
+export CMIS_TCK_PASSWORD='local-secret'
+```
+
+Use a target profile with:
+
+```json
+"credentials_ref": "env:CMIS_TCK_USER,CMIS_TCK_PASSWORD"
+```
+
+The adapter uses a private session file during execution and retains only a
+redacted session file as an artifact.
+
+## Troubleshooting
+
+`java is not available on PATH`:
+
+Install a JDK or expose an existing JDK to WSL.
+
+`maven is not available on PATH`:
+
+Install Maven or expose an existing Maven executable to WSL.
+
+Maven dependency resolution fails:
+
+Check network access to Maven Central or rerun with a populated Maven cache.
+
+Preflight returns `infrastructure_error`:
+
+Check endpoint URL, server process, firewall, credentials, and timeout.
+
+Repository ID mismatch:
+
+Use the repository IDs reported by preflight and update
+`runtime_policy.opencmis_tck.repository_id`.
+
+TCK command times out:
+
+Increase `runtime_policy.timeout_seconds` or narrow selected check groups.
+
+Formal boundary:
+
+These runs generate preparation evidence only. They do not issue CMIS
+certification.