Release dev.kit 0.14.0 user experience improvements

.rabbit/context.yaml

@@ -5,8 +5,8 @@ version: udx.dev/dev.kit/v1
 generator:
   tool: dev.kit
   repo: https://github.com/udx/dev.kit
-  version: 0.13.0
-  generated_at: 2026-05-27T18:39:54Z
+  version: 0.14.0
+  generated_at: 2026-06-26T10:41:30Z
   sources:
     homepage: https://udx.dev/kit
     repository: https://github.com/udx/dev.kit
@@ -26,10 +26,7 @@ refs:
   - ./README.md
   - ./changes.md
   - ./Makefile
-  - ./docs/references/command-surfaces.md
   - ./docs/real-repo-validation.md
-  - ./docs/references/output-schemas.md
-  - ./docs/references/repo-design.md
   - ./src/configs/archetypes.yaml
   - ./src/configs/audit-rules.yaml
   - ./src/configs/context-config.yaml
@@ -49,12 +46,6 @@ commands:
   verify:
     run: make test
     source: Makefile
-  build:
-    run: make build
-    source: docs/references/command-surfaces.md
-  run:
-    run: make run
-    source: docs/references/command-surfaces.md
 
 # Dependencies — Meaningful dependency-repo contracts such as reusable workflows, images, or versioned manifests this repo relies on.
 # Note: Capture execution-shaping behavior defined outside the current checkout.
@@ -65,7 +56,7 @@ dependencies:
   - repo: udx/reusable-workflows
     kind: reusable workflow
     resolved: true
-    archetype: workflow-repo
+    archetype: manifest-repo
     used_by:
       - .github/workflows/context7-ops.yml
       - .github/workflows/npm-release-ops.yml

changes.md

@@ -1,5 +1,12 @@
 # Changes
 
+### 0.14.0
+
+- Ignore command examples from `docs/references/` when generating repo command contracts, preventing reference docs from creating misleading `build` or `run` commands.
+- Add regression coverage for reference-only command examples so generated context stays tied to runnable repo-owned surfaces.
+- Add release verification guidance that distinguishes GitHub release, npm registry, tarball, and npmjs.com UI evidence.
+- Add `udx/rabbit-automation-action` to the real-repo validation matrix as a manifest-heavy config contract probe.
+
 ### 0.13.0
 
 - Allow repo-owned manifests to satisfy config contract coverage when they declare explicit config contract metadata or runtime config sections, avoiding forced `.env.example` files for repos with custom manifest contracts.

docs/real-repo-validation.md

@@ -29,6 +29,10 @@ The summary should be used to compare:
 
 When one repo looks noisy or inconsistent, repair the strongest repo-owned gap or dev.kit normalization issue, rerun the matrix, and verify the output changed.
 
+For config and manifest contract releases, include `udx/rabbit-automation-action`
+when it is available locally. It is a useful probe because it relies on
+repo-owned manifests instead of generic `.env.example` files.
+
 ## Public Repo Probes
 
 Public repos are useful for compatibility checks, but they should be optional and pinned when used for repeatable release evidence. Upstream repos change for reasons unrelated to dev.kit.
@@ -45,3 +49,15 @@ Do not assert exact output for moving public repos in the default suite.
 ## Write Mode
 
 `tests/real-repos.sh --write` generates `.rabbit/context.yaml` in the target repo. Use it only for temp clones or repos intentionally selected for context regeneration.
+
+## Release Verification
+
+Before reporting a release as published, verify each source precisely:
+
+- GitHub PR is merged into the release branch.
+- GitHub release and tag exist for the intended version.
+- Release workflow completed successfully.
+- npm registry API reports the intended dist-tag and version.
+- npm tarball URL returns a successful response.
+- npmjs.com package page is treated as optional UI evidence because it can lag
+  behind registry metadata.

docs/references/command-surfaces.md

@@ -30,6 +30,12 @@ Workflow and operational contracts are often packaged in:
 
 Docs should explain execution behavior, tradeoffs, and decision points. The runnable contract should stay in scripts and manifests.
 
+Repo-specific docs such as `README.md`, `changes.md`, or focused operational
+docs can still declare commands when a repo intentionally keeps its command
+surface in prose. Reusable reference docs under `docs/references/` are examples
+and interpretation guidance; they should not become generated command contracts
+unless a runnable repo surface also declares the same command.
+
 ## Build and deploy may be separate
 
 Some repos intentionally separate:

lib/modules/repo_signals.sh

@@ -278,6 +278,9 @@ dev_kit_repo_command_doc_files() {
     case "$ref" in
       AGENTS.md|CLAUDE.md|.rabbit/*) continue ;;
     esac
+    case "$ref" in
+      docs/references/*) continue ;;
+    esac
     case "$ref" in
       *.md|*.markdown) printf '%s/%s\n' "$repo_dir" "$ref" ;;
     esac

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udx/dev-kit",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Context-driven engineering toolkit for AI agents and developers",
   "license": "MIT",
   "repository": {

src/configs/repo-validation.yaml

@@ -24,6 +24,9 @@ config:
     github_rabbit_action:
       repo: udx/github-rabbit-action
       purpose: action, docs, and workflow context mix
+    rabbit_automation_action:
+      repo: udx/rabbit-automation-action
+      purpose: manifest-heavy repo and config contract sanity check
     dev_kit:
       repo: udx/dev.kit
       purpose: self-hosting sanity check

tests/suite.sh

@@ -16,6 +16,7 @@ DOCKER_ACTION_REPO="$TEST_HOME/docker-action-repo"
 EMPTY_REPO="$TEST_HOME/empty-repo"
 IGNORED_ACTION_REPO="$TEST_HOME/ignored-action-repo"
 WORKFLOW_CONTRACT_REPO="$TEST_HOME/workflow-contract-repo"
+REFERENCE_DOC_COMMAND_REPO="$TEST_HOME/reference-doc-command-repo"
 AVAILABLE_TEST_GROUPS="core repo-contract"
 TEST_ONLY="${DEV_KIT_TEST_ONLY:-}"
 
@@ -163,6 +164,8 @@ if should_run_explicit "repo-contract"; then
   assert_not_contains "$repo_validation_manifest" "source_repo: udx/worker" "repo contract: does not treat probe repo values as manifest source repo"
   assert_not_contains "$self_context_yaml" ".rabbit/dev.kit/" "repo contract: excludes generated rabbit evidence"
   assert_not_contains "$self_context_yaml" ".rabbit/context.yaml.tmp." "repo contract: excludes context temp files from evidence"
+  assert_not_contains "$self_context_yaml" "run: make build" "repo contract: ignores reference-doc build command examples"
+  assert_not_contains "$self_context_yaml" "run: make run" "repo contract: ignores reference-doc run command examples"
 
   cp -R "$DOCKER_REPO" "$DOCKER_ACTION_REPO"
   rm -f "$DOCKER_ACTION_REPO/.rabbit/context.yaml"
@@ -360,6 +363,8 @@ if should_run "core"; then
   assert_not_contains "$repo_validation_manifest" "source_repo: udx/worker" "repo: does not treat probe repo values as manifest source repo"
   assert_not_contains "$self_context_yaml" ".rabbit/dev.kit/" "repo: excludes generated rabbit evidence"
   assert_not_contains "$self_context_yaml" ".rabbit/context.yaml.tmp." "repo: excludes context temp files from evidence"
+  assert_not_contains "$self_context_yaml" "run: make build" "repo: ignores reference-doc build command examples"
+  assert_not_contains "$self_context_yaml" "run: make run" "repo: ignores reference-doc run command examples"
 
   cp -R "$SIMPLE_REPO" "$SIMPLE_ACTION_REPO"
   rm -rf "$SIMPLE_ACTION_REPO/.dev-kit"
@@ -456,6 +461,28 @@ EOF
   assert_not_contains "$(cat "$workflow_context_yaml")" "path: .github/workflows/ci.yml" "workflow repo: excludes marketplace-only workflow manifest"
   assert_contains "$(cat "$workflow_context_yaml")" "repo: udx/reusable-workflows" "workflow repo: traces reusable workflow dependency"
 
+  mkdir -p "$REFERENCE_DOC_COMMAND_REPO/docs/references"
+  git -C "$REFERENCE_DOC_COMMAND_REPO" init >/dev/null 2>&1
+  cat > "$REFERENCE_DOC_COMMAND_REPO/README.md" <<'EOF'
+# Reference Doc Command Repo
+
+This repo has no build or run command.
+EOF
+  cat > "$REFERENCE_DOC_COMMAND_REPO/docs/references/command-surfaces.md" <<'EOF'
+# Command Surfaces
+
+Examples only:
+
+- `make build`
+- `make run`
+EOF
+
+  reference_doc_json="$(cd "$REFERENCE_DOC_COMMAND_REPO" && dev.kit repo --json)"
+  assert_contains "$reference_doc_json" "\"context\":" "reference docs repo: reports context path"
+  reference_doc_context_yaml="${REFERENCE_DOC_COMMAND_REPO}/.rabbit/context.yaml"
+  assert_not_contains "$(cat "$reference_doc_context_yaml")" "run: make build" "reference docs repo: ignores reference-only build example"
+  assert_not_contains "$(cat "$reference_doc_context_yaml")" "run: make run" "reference docs repo: ignores reference-only run example"
+
   mkdir -p "$EMPTY_REPO"
   git -C "$EMPTY_REPO" init >/dev/null 2>&1