Dry run and operator handbook

docs/CONTAINER-HANDOFF.md

@@ -0,0 +1,74 @@
+# Container And Test Host Handoff
+
+Status: draft
+Created: 2026-05-08
+
+## Purpose
+
+This note captures what should move into a container or dedicated test host
+after local OpenCMIS TCK execution is stable.
+
+Containerization is not a prerequisite for WP-0002 local execution.
+
+## Candidate Runtime Image
+
+The first dedicated runtime image should include:
+
+- Python 3.11+
+- Java runtime/JDK verified against OpenCMIS TCK 1.1.0
+- Maven
+- guide-board core
+- `open-cmis-tck` extension
+
+It should not bake in secrets or target-specific profiles.
+
+## Mounts
+
+Expected mounts:
+
+```text
+/profiles      target and assessment profiles
+/credentials   optional credential files
+/runs          generated guide-board run directories
+/m2            optional Maven cache
+```
+
+For licensed or externally supplied assets, add:
+
+```text
+/assets
+```
+
+The current OpenCMIS TCK runtime uses Maven Central and does not require
+vendored assets.
+
+## Environment
+
+Useful environment variables:
+
+```text
+CMIS_TCK_USER
+CMIS_TCK_PASSWORD
+MAVEN_OPTS
+GUIDE_BOARD_EXTENSION_PATHS
+```
+
+The adapter should still prefer profile-level `credentials_ref` over implicit
+environment assumptions.
+
+## Network Assumptions
+
+The test host must reach:
+
+- the CMIS Browser Binding endpoint under test,
+- Maven Central or an internal Maven mirror during dependency resolution,
+- any internal credential source if file mounts are not used.
+
+## Handoff Criteria
+
+Move to a container or test host after:
+
+- `scripts/bootstrap_opencmis_tck.py --resolve` is ready locally,
+- at least one repository/type live run has produced guide-board evidence,
+- real TCK output normalization has been reviewed,
+- the maturity scorecard has its first evidence-backed output.

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.

docs/LOCAL-TCK-RUNTIME.md

@@ -76,6 +76,8 @@ one outside WSL.
 
 ## Guide-Board Invocation
 
+For the full local sequence, see `docs/LOCAL-RUNBOOK.md`.
+
 The baseline assessment profile now points the OpenCMIS wrapper at:
 
 ```text