fix: add to bootstrap check and init

Author: ivklgn

skills/bootstrap/SKILL.md

@@ -54,6 +54,12 @@ Each mode additionally runs hotspot capture-candidate proposal (Step 6) and opti
 
 ## Execution
 
+### Step -1: Ensure initialization
+
+Call `mcp__archcore__init_project()` before any other MCP operation. It is idempotent — safe on an already-initialized project (returns existing settings). It creates `.archcore/` and the settings file if they do not exist.
+
+Do NOT ask the user to run `archcore init` in the terminal — `mcp__archcore__init_project` is the correct path in a plugin session.
+
 ### Step 0: Check state
 
 Call `mcp__archcore__list_documents()`. Derive:

test/structure/agents.bats

@@ -112,3 +112,16 @@ setup() {
     grep -q 'subagent-knowledge-tree-bootstrap.adr' "$file" || fail "$f: missing ADR reference"
   done
 }
+
+@test "all agent files document the archcore init CLI recovery path" {
+  # When MCP tools are unavailable (CLI not installed or unresolvable on PATH),
+  # mcp__archcore__init_project cannot fire. Agents must fall back to telling
+  # the user how to recover: install the CLI and run `archcore init` in the
+  # terminal. This must be present in every agent surface across hosts —
+  # .md (Claude/Cursor) and .toml (Codex) — or the fallback drifts silently.
+  for f in archcore-assistant.md archcore-auditor.md archcore-assistant.toml archcore-auditor.toml; do
+    local file="$PLUGIN_ROOT/agents/$f"
+    grep -q 'archcore init' "$file" \
+      || fail "$f: missing 'archcore init' recovery instruction for MCP-unavailable case"
+  done
+}

test/structure/hooks.bats

@@ -176,3 +176,23 @@ setup() {
     fail "Script sets differ between Claude Code and Codex"
   }
 }
+
+@test "every host hook config registers bin/session-start on its session-start event" {
+  # bin/session-start emits the init_project nudge on first-time / empty-state
+  # sessions. If any host loses this wiring, onboarding silently breaks on that
+  # host. Event keys differ by casing per host: SessionStart (Claude/Codex,
+  # PascalCase) vs sessionStart (Cursor, camelCase).
+  local entries=(
+    "hooks/hooks.json:SessionStart"
+    "hooks/codex.hooks.json:SessionStart"
+    "hooks/cursor.hooks.json:sessionStart"
+  )
+  local entry file event cmds
+  for entry in "${entries[@]}"; do
+    file="${entry%:*}"
+    event="${entry#*:}"
+    cmds=$(jq -r --arg e "$event" '.hooks[$e][]?.hooks[]?.command // empty' "$PLUGIN_ROOT/$file")
+    echo "$cmds" | grep -q 'bin/session-start$' \
+      || fail "$file: '$event' event must invoke bin/session-start; got: $cmds"
+  done
+}

test/structure/json-configs.bats

@@ -51,6 +51,15 @@ setup() {
 }
 
 @test "cursor plugin.json has skills, agents, hooks paths" {
+  # NOTE: Cursor plugin manifests intentionally do NOT carry an `mcpServers`
+  # field, and we ship no `.cursor.mcp.json`. This is by design: at the time
+  # of writing, Cursor manages MCP servers via the user's `~/.cursor/mcp.json`
+  # (host-level), not via plugin manifests, so the archcore MCP server must
+  # be configured by the user in their host config separately. As a result,
+  # `mcp__archcore__init_project` is reachable in Cursor only when the user
+  # has wired it themselves — there is no plugin-level guarantee, and no
+  # structural test enforces one. Before adding an `.cursor.mcp.json`, verify
+  # current Cursor actually supports plugin-level MCP injection.
   run jq -e '.skills and .agents and .hooks' "$PLUGIN_ROOT/.cursor-plugin/plugin.json"
   assert_success
 }

test/structure/skills.bats

@@ -53,3 +53,17 @@ setup() {
   done | sort | uniq -d)
   [ -z "$dupes" ] || fail "Duplicate skill names: $dupes"
 }
+
+@test "bootstrap skill calls init_project before operating on uninitialized projects" {
+  grep -q "mcp__archcore__init_project" "$PLUGIN_ROOT/skills/bootstrap/SKILL.md" \
+    || fail "bootstrap/SKILL.md must instruct the agent to call mcp__archcore__init_project for uninitialized projects"
+}
+
+@test "help skill documents the archcore init CLI recovery path" {
+  # /archcore:help is a likely first stop when MCP tools fail; it must explain
+  # how to install the CLI and run `archcore init` to recover. This is the
+  # MCP-unavailable fallback (distinct from the in-session init_project call
+  # that bootstrap uses when MCP works but .archcore/ is empty).
+  grep -q 'archcore init' "$PLUGIN_ROOT/skills/help/SKILL.md" \
+    || fail "help/SKILL.md must include 'archcore init' recovery instruction"
+}