nexarch 0.12.34 → 0.12.36

package/dist/lib/skills.js

@@ -104,18 +104,30 @@ skill is the check-in → claim → complete loop for working that queue.
 - \`nexarch_check_in\` previews pending commands and draft/proposed
   applications for this agent. It does **not** claim or change anything —
   safe to call any time, including proactively at the start of a session.
-- If you already know which application you're operating in — you're
-  working inside its repo, or it was named earlier in this conversation —
-  pass it as \`applicationContext: { accessibleApplicationRefs: ["application:<ref>"] }\`
-  on this **first** call. Without it, every command comes back
-  \`claimable: false\` (\`claimReason: "application_context_required_for_claim"\`)
-  even if you could otherwise claim it, and you'll need a second check-in
-  call with that same ref before \`nexarch_claim_command_by_id\` will work —
-  a wasted round trip when the application was knowable up front.
-- If you don't yet know the application, call check-in bare first. Each
-  returned command carries \`target_entity_key\` (e.g.
-  \`"application:veri_viva_platform_website"\`) — call check-in again with
-  that as \`accessibleApplicationRefs\` before trying to claim it.
+- If you have a **confirmed** ref — returned by an earlier tool call in this
+  session (\`target_entity_key\` from a prior check-in, \`nexarch_list_entities\`,
+  \`nexarch_resolve_reference\`), or the human gave you the exact ref — pass
+  it as \`applicationContext: { accessibleApplicationRefs: ["<ref>"] }\` on
+  this **first** call to skip a redundant round trip.
+- **A project ref works here too, and is often the one you actually have.**
+  You're usually registered against the repository's \`project:\` ref, not
+  any specific \`application:\` ref inside it — passing the project ref is
+  fine; check-in expands it to every application \`sourced_from\` it and
+  scopes to all of them. A monorepo project can source several
+  applications, so this is different from — and safer than — guessing which
+  single application ref applies: don't construct an application ref by
+  pattern-matching the project/repo name (\`project:veri_viva_platform\` does
+  not imply \`application:veri_viva_platform\` exists; the real one might be
+  \`application:veri_viva_platform_website\` or something else entirely).
+  Pass the project ref you actually have, not a guessed application ref.
+- If a scoped call's response includes \`project_ref_expanded_to_applications\`,
+  that's normal — it's telling you which application(s) a project ref
+  resolved to. \`application_context_ref_unresolved\` means a ref you passed
+  matched nothing at all. \`pending_commands_outside_requested_scope\` means
+  the resolved scope still didn't cover everything pending — call check-in
+  again with no \`applicationContext\` to see the rest.
+- Calling bare (no \`applicationContext\`) is always safe and returns every
+  pending command's real \`target_entity_key\` if you have no ref at all yet.
 - Report exactly what check-in found. Don't reinterpret "check in" as
   registration (\`init-agent\`) or as a general health check
   (\`nexarch_get_governance_summary\`) — they're different actions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.12.34",
+  "version": "0.12.36",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",