fix(unit-only): Write docs/harness.md on main, porting/adapting git show ... (#1580)

[aidandaly24]

Refs aws#1580

Issues

• docs: write docs/harness.md aws/agentcore-cli#1580 — The README Harness section (README.md:170-189, added by docs: cover payments, policies/guardrails, insights, harness, datasets, web-search aws/agentcore-cli#1577) documents the preview-only harness command surface and the mandatory EXPORT_NOTES.md follow-up, but there is no companion docs/harness.md guide on the main line. A 263-line guide exists only on the preview branch and was never merged to HEAD. Impact is limited: harness is a [preview]-gated feature that does not even register in the v0.20.2 latest build, so only preview-channel users hit the documentation gap, and the README plus the vended AGENTS.md asset already cover the essentials.

Root cause

docs/harness.md absent at HEAD v0.20.2 (verified ls-tree/ls empty). README.md:170-189 (from aws#1577, an ancestor of HEAD) documents the preview-gated harness surface + EXPORT_NOTES.md but links no guide; no broken link (README:326 -> docs/tui-harness.md, which exists). The 263-line preview doc (commit 1a1de9b) is NOT an ancestor of HEAD (merge-base --is-ancestor false). Feature is implemented but preview-gated: harnessPrimitive undefined unless isPreviewEnabled() (registry.ts:26); export/add tool/add skill register only under isPreviewEnabled() (cli.ts:126-141); PREVIEW baked via BUILD_PREVIEW (esbuild.config.mjs:56), set only on the @Preview publish, so harness commands are dark in v0.20.2 latest. No commit/PR references aws#1580.

The fix

Write docs/harness.md on main, porting/adapting git show 1a1de9b:docs/harness.md. Reconcile command surface: foreground add harness/add tool --harness/add skill --harness/export harness per README:183-186; scope or drop the preview doc's agentcore create --name myharness harness-project flow to match what the main-line CLI registers. Cover the declarative config model, the export->Strands app/ workflow, and the mandatory EXPORT_NOTES.md follow-up (README:188; AGENTS.md:138-146). Mark the doc preview-only to mirror README:170 [preview]. Optionally link into the README docs index near line 326.

Files touched: New file: /local/home/aidandal/workplace/issues/agentcore-cli/docs/harness.md. Reference sources at HEAD: README.md:170-189; src/cli/commands/export/harness-action.ts:187-206,297-336; src/cli/commands/export/index.ts:17; src/cli/commands/export/constants.ts:1; src/cli/primitives/HarnessPrimitive.ts (registerCommands at :647); src/cli/primitives/registry.ts:26; src/cli/cli.ts:125-141; src/assets/agents/AGENTS.md:138-146. Prior art to port: docs/harness.md at git commit 1a1de9b (preview branch only).

Validation evidence

The fix was verified by reproducing the original symptom and re-running after the change:

BEFORE (HEAD 9b2fcc5, fix not applied): git show HEAD:docs/harness.md -> MISSING; git show HEAD:README.md | grep docs/harness.md -> no Harness entry in docs index. README:170-189 references the harness commands (add harness / add tool / add skill / export harness) and the mandatory EXPORT_NOTES.md follow-up, but there is no dedicated guide to follow. Symptom reproduced.

AFTER (branch fix/1580): docs/harness.md exists (151 lines) + README docs index gains exactly one line "- Harness" (git diff README.md = 1 insertion, surgical). Pass conditions verified:
(1) Config model section at line 24 (runtime+model, memory --memory-mode managed/existing/--memory-name/--memory-arn, execution limits, --network-mode PUBLIC|VPC, observability); Export->Strands app// workflow section at line 94; dedicated "Read EXPORT_NOTES.md before you deploy" section at line 123 with the mandatory follow-up guidance.
(2) Command-surface table documents ONLY add harness / add tool --harness / add skill --harness / export harness (+ remove harness). All four verified REGISTERED at HEAD via the built CLI: node dist/cli/index.mjs add harness|add tool|add skill|export harness --help all exit 0. Tool types in doc (agentcore_browser, agentcore_code_interpreter, remote_mcp, agentcore_gateway, inline_function) match tool-action.ts. EXPORT_NOTES.md path app// matches harness-action.ts:336.
(3) Forbidden grep all ABSENT: 'create --name myharness', '--no-har

Test suite: green.

---

Staged on the fork as a draft for human review. Promote to aws/agentcore-cli after vetting.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	37.16%	13593 / 36577
🔵	Statements	36.43%	14452 / 39667
🔵	Functions	31.8%	2333 / 7336
🔵	Branches	31.1%	9000 / 28932

Generated in workflow #111 for commit f37018d by the Vitest Coverage Report Action