@bradheitmann/odin-sentinel 0.4.5 → 0.4.7

package/dist/src/telemetry/report.d.ts

@@ -12,6 +12,109 @@ export type ModelSignal = {
     model: string;
     violations: number;
 };
+export type DiagnosticStatus = "verified" | "missing" | "blocked" | "unknown" | "not_applicable";
+export type DiagnosticCheck = {
+    status: DiagnosticStatus;
+    detail?: string;
+    evidence?: string;
+};
+export type PromptType = "full_protocol" | "short_boot_prompt" | "handoff" | "unknown";
+export type ReadinessStatus = "ready" | "degraded" | "blocked" | "unknown";
+export type ReceiptStatus = "emitted" | "missing" | "invalid" | "unknown" | "not_applicable";
+export type WatchStatus = "active" | "passive" | "idle" | "blocked" | "unknown" | "not_applicable";
+export type BlockerClassification = "none" | "stale_mcp_version" | "missing_skill" | "short_prompt" | "passive_odin" | "split_workspace" | "tab_heavy_layout" | "auth_blocker" | "permission_blocker" | "local_inference_stall" | "role_refusal" | "missing_protocol_text" | "operator_authority_confusion" | "receipt_missing" | "runbook_improvisation" | "readiness_gate_skipped";
+export type RoleSlotLocator = {
+    workspace?: string;
+    pane?: string;
+    surface?: string;
+};
+export type RoleSlotDiagnostic = {
+    role: string;
+    team: string;
+    harness: string;
+    model: string;
+    locator: RoleSlotLocator;
+    mcpAccess: DiagnosticCheck;
+    mcpVersion?: string;
+    minimumCompatibleMcpVersion?: string;
+    skillAccess: DiagnosticCheck;
+    fullProtocolTextReceived: DiagnosticCheck;
+    promptType: PromptType;
+    operatorAuthorityRecognized: DiagnosticCheck;
+    readinessStatus: ReadinessStatus;
+    bootReceiptStatus: ReceiptStatus;
+    activeWatchStatus: WatchStatus;
+    blockerClassification: BlockerClassification[];
+    childContextText?: string;
+    notes?: string[];
+};
+export type HarnessFailureDiagnostics = {
+    openHandsAuthApiCredentials: DiagnosticCheck;
+    kiloCodeLogin: DiagnosticCheck;
+    gooseLocalInferenceStall: DiagnosticCheck;
+    crushPermissionPrompt: DiagnosticCheck;
+    piRoleRefusal: DiagnosticCheck;
+    staleMcpVersion: DiagnosticCheck;
+};
+export type LayoutDiagnostics = {
+    sameWorkspace: boolean | "unknown";
+    splitWorkspace: boolean;
+    spatialPodLayout: boolean | "unknown";
+    tabHeavyLayout: boolean;
+    cmuxAvailable: boolean | "unknown";
+    degradedLayoutWarnings: string[];
+};
+export type LaunchRunbookDiagnostics = {
+    deterministicRunbookFollowed: boolean | "unknown";
+    firstImprovisationPoint?: string;
+    missingPrompts: string[];
+    missingTools: string[];
+    missingSchemas: string[];
+};
+export type ReadinessGateDiagnostics = {
+    childMcpVerified: DiagnosticCheck;
+    skillVerified: DiagnosticCheck;
+    authVerified: DiagnosticCheck;
+    firstRunPromptVerified: DiagnosticCheck;
+    modelSmokeVerified: DiagnosticCheck;
+    roleCompatibilityVerified: DiagnosticCheck;
+};
+export type ReleaseVersionDiagnostics = {
+    currentServerVersion: string;
+    minimumCompatibleVersion: string;
+    childReportedMcpVersions: Array<{
+        role: string;
+        version: string;
+    }>;
+    driftWarnings: string[];
+};
+export type ArtifactDiagnostics = {
+    planningArtifactsLocalOnly: boolean | "unknown";
+    publicTemplatesSanitized: boolean | "unknown";
+    privateArtifactWarnings: string[];
+};
+export type ChildContextWindow = {
+    role: string;
+    text: string;
+};
+export type AxDiagnostics = {
+    roleSlots: RoleSlotDiagnostic[];
+    childAgentQuestions: string[];
+    odinQuestions: string[];
+    harnessFailures: HarnessFailureDiagnostics;
+    layout: LayoutDiagnostics;
+    launchRunbook: LaunchRunbookDiagnostics;
+    readinessGates: ReadinessGateDiagnostics;
+    versions: ReleaseVersionDiagnostics;
+    artifacts: ArtifactDiagnostics;
+    pastedChildContextWindows?: ChildContextWindow[];
+};
+export type AxSummary = {
+    roleSlotCount: number;
+    blockerClassifications: BlockerClassification[];
+    degradedLayout: boolean;
+    driftWarningCount: number;
+};
 export type SessionReportInput = {
     teamCount: number;
     violations: ViolationEntry[];
@@ -20,11 +123,16 @@ export type SessionReportInput = {
     peakContextPct: number;
     closeoutClean: boolean;
     modelSignals: ModelSignal[];
+    ax?: Partial<AxDiagnostics>;
 };
 export type SessionReport = SessionReportInput & {
     version: string;
     compiledAt: string;
     violationCount: number;
     haltCount: number;
+    axSummary?: AxSummary;
 };
+export declare const CHILD_AGENT_DIAGNOSTIC_QUESTIONS: readonly ["What role slot, team, harness, model, workspace, pane, and surface were you assigned?", "Did you have ODIN Sentinel MCP access, and what MCP version did you see?", "Did you have native skill access for the requested role, or was a required skill missing?", "Did you receive the full protocol text, a handoff, or only a short boot prompt?", "Did you recognize A/EXEC-PM operator authority and your own implementation/QA limits?", "Did you emit the required boot receipt or explain why receipt emission was blocked?", "What blocker or confusion stopped progress, using the closest standard classification?", "What exact prompt, tool, schema, layout, auth, or runbook change would make launch smoother next time?"];
+export declare const ODIN_DIAGNOSTIC_QUESTIONS: readonly ["Were you explicitly instructed to poll actively, or did you interpret the role as passive observation?", "Which workspaces, panes, surfaces, agents, files, queues, or receipts were you watching?", "Did plan mode, read-only mode, permission prompts, or role boundaries conflict with active intervention?", "What exact polling prompt or cadence would have made the watch loop unambiguous?", "Which terminal states did you detect: idle, blocked, still thinking, input-bar-only, delivered-no-ack, or done?", "What intervention would you have issued if active polling authority had been clear?"];
+export declare function getAxDiagnosticQuestions(scope?: "child" | "odin" | "all"): string[];
 export declare function compileSessionReport(input: SessionReportInput, version: string): SessionReport;

package/dist/src/telemetry/report.js

@@ -1,10 +1,90 @@
+import { redactPayload } from "./redactor.js";
+export const CHILD_AGENT_DIAGNOSTIC_QUESTIONS = [
+    "What role slot, team, harness, model, workspace, pane, and surface were you assigned?",
+    "Did you have ODIN Sentinel MCP access, and what MCP version did you see?",
+    "Did you have native skill access for the requested role, or was a required skill missing?",
+    "Did you receive the full protocol text, a handoff, or only a short boot prompt?",
+    "Did you recognize A/EXEC-PM operator authority and your own implementation/QA limits?",
+    "Did you emit the required boot receipt or explain why receipt emission was blocked?",
+    "What blocker or confusion stopped progress, using the closest standard classification?",
+    "What exact prompt, tool, schema, layout, auth, or runbook change would make launch smoother next time?"
+];
+export const ODIN_DIAGNOSTIC_QUESTIONS = [
+    "Were you explicitly instructed to poll actively, or did you interpret the role as passive observation?",
+    "Which workspaces, panes, surfaces, agents, files, queues, or receipts were you watching?",
+    "Did plan mode, read-only mode, permission prompts, or role boundaries conflict with active intervention?",
+    "What exact polling prompt or cadence would have made the watch loop unambiguous?",
+    "Which terminal states did you detect: idle, blocked, still thinking, input-bar-only, delivered-no-ack, or done?",
+    "What intervention would you have issued if active polling authority had been clear?"
+];
+const HARNESS_BLOCKER_MAP = [
+    ["openHandsAuthApiCredentials", "auth_blocker"],
+    ["kiloCodeLogin", "auth_blocker"],
+    ["gooseLocalInferenceStall", "local_inference_stall"],
+    ["crushPermissionPrompt", "permission_blocker"],
+    ["piRoleRefusal", "role_refusal"],
+    ["staleMcpVersion", "stale_mcp_version"]
+];
+function uniq(values) {
+    return [...new Set(values)];
+}
+function isBlocking(status) {
+    return status === "missing" || status === "blocked";
+}
+function summarizeAx(ax) {
+    if (!ax)
+        return undefined;
+    const blockers = [];
+    for (const roleSlot of ax.roleSlots ?? []) {
+        blockers.push(...roleSlot.blockerClassification.filter((entry) => entry !== "none"));
+        if (roleSlot.promptType === "short_boot_prompt")
+            blockers.push("short_prompt");
+        if (roleSlot.fullProtocolTextReceived.status === "missing")
+            blockers.push("missing_protocol_text");
+        if (roleSlot.skillAccess.status === "missing")
+            blockers.push("missing_skill");
+        if (roleSlot.activeWatchStatus === "passive" || roleSlot.activeWatchStatus === "idle")
+            blockers.push("passive_odin");
+        if (roleSlot.bootReceiptStatus === "missing")
+            blockers.push("receipt_missing");
+    }
+    if (ax.harnessFailures) {
+        for (const [key, classification] of HARNESS_BLOCKER_MAP) {
+            if (isBlocking(ax.harnessFailures[key].status))
+                blockers.push(classification);
+        }
+    }
+    if (ax.layout?.splitWorkspace)
+        blockers.push("split_workspace");
+    if (ax.layout?.tabHeavyLayout)
+        blockers.push("tab_heavy_layout");
+    if (ax.launchRunbook?.deterministicRunbookFollowed === false)
+        blockers.push("runbook_improvisation");
+    if ((ax.versions?.driftWarnings.length ?? 0) > 0)
+        blockers.push("stale_mcp_version");
+    return {
+        roleSlotCount: ax.roleSlots?.length ?? 0,
+        blockerClassifications: uniq(blockers),
+        degradedLayout: Boolean(ax.layout?.splitWorkspace || ax.layout?.tabHeavyLayout || (ax.layout?.degradedLayoutWarnings.length ?? 0) > 0),
+        driftWarningCount: ax.versions?.driftWarnings.length ?? 0
+    };
+}
+export function getAxDiagnosticQuestions(scope = "all") {
+    if (scope === "child")
+        return [...CHILD_AGENT_DIAGNOSTIC_QUESTIONS];
+    if (scope === "odin")
+        return [...ODIN_DIAGNOSTIC_QUESTIONS];
+    return [...CHILD_AGENT_DIAGNOSTIC_QUESTIONS, ...ODIN_DIAGNOSTIC_QUESTIONS];
+}
 export function compileSessionReport(input, version) {
+    const redacted = redactPayload(input);
     return {
-        ...input,
+        ...redacted,
         version,
         compiledAt: new Date().toISOString(),
-        violationCount: input.violations.length,
-        haltCount: input.halts.length
+        violationCount: redacted.violations.length,
+        haltCount: redacted.halts.length,
+        axSummary: summarizeAx(redacted.ax)
     };
 }
 //# sourceMappingURL=report.js.map

package/dist/src/telemetry/report.js.map

@@ -1 +1 @@
-{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/telemetry/report.ts"],"names":[],"mappings":"AAkCA,MAAM,UAAU,oBAAoB,CAAC,KAAyB,EAAE,OAAe;IAC7E,OAAO;QACL,GAAG,KAAK;QACR,OAAO;QACP,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,cAAc,EAAE,KAAK,CAAC,UAAU,CAAC,MAAM;QACvC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;KAC9B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/telemetry/report.ts"],"names":[],"mappings":"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"}

package/dist/src/telemetry/submit.d.ts

@@ -10,5 +10,7 @@ export type SubmitOptions = {
     config?: TelemetryConfig;
     fetchImpl?: typeof fetch;
     timeoutMs?: number;
+    userConsentConfirmed?: boolean;
 };
+export declare function toTelemetryPayload(report: Record<string, unknown>): Record<string, unknown>;
 export declare function submitSessionReport(report: Record<string, unknown>, options?: SubmitOptions): Promise<SubmitResult>;

package/dist/src/telemetry/submit.js

@@ -1,7 +1,80 @@
-import { readTelemetryConfig } from "./config.js";
-import { redactPayload } from "./redactor.js";
+import { readTelemetryConfig, redactTelemetryEndpoint } from "./config.js";
+import { redactPayload, redactString } from "./redactor.js";
 const DEFAULT_TIMEOUT_MS = 8000;
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function safeString(value, maxLen = 96) {
+    if (typeof value !== "string")
+        return "";
+    const redacted = redactString(value).trim();
+    return redacted.length > maxLen ? redacted.slice(0, maxLen) : redacted;
+}
+function safeInt(value, fallback, min, max) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    const integer = Math.trunc(value);
+    if (integer < min)
+        return min;
+    if (integer > max)
+        return max;
+    return integer;
+}
+function safeStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.map((entry) => safeString(entry)).filter(Boolean))];
+}
+function violationClasses(report) {
+    const direct = safeStringArray(report.violationClasses);
+    if (direct.length > 0)
+        return direct;
+    if (!Array.isArray(report.violations))
+        return [];
+    return [...new Set(report.violations.flatMap((entry) => isRecord(entry) ? [safeString(entry.class)] : []).filter(Boolean))];
+}
+function blockerClassifications(report) {
+    const axSummary = isRecord(report.axSummary) ? report.axSummary : {};
+    return safeStringArray(axSummary.blockerClassifications);
+}
+function modelSignals(report) {
+    if (!Array.isArray(report.modelSignals))
+        return [];
+    return report.modelSignals.flatMap((entry) => {
+        if (!isRecord(entry))
+            return [];
+        return [{
+                role: safeString(entry.role),
+                model: safeString(entry.model),
+                violations: safeInt(entry.violations, 0, 0, 10_000)
+            }];
+    });
+}
+export function toTelemetryPayload(report) {
+    const axSummary = isRecord(report.axSummary) ? report.axSummary : {};
+    return {
+        version: safeString(report.version, 32),
+        teamCount: safeInt(report.teamCount, 0, 0, 26),
+        violationCount: safeInt(report.violationCount, Array.isArray(report.violations) ? report.violations.length : 0, 0, 10_000),
+        haltCount: safeInt(report.haltCount, Array.isArray(report.halts) ? report.halts.length : 0, 0, 10_000),
+        layoutDriftEvents: safeInt(report.layoutDriftEvents, 0, 0, 10_000),
+        peakContextPct: safeInt(report.peakContextPct, 0, 0, 100),
+        closeoutClean: report.closeoutClean === true,
+        modelSignals: modelSignals(report),
+        violationClasses: violationClasses(report),
+        blockerClassifications: blockerClassifications(report),
+        roleSlotCount: safeInt(axSummary.roleSlotCount, 0, 0, 10_000),
+        driftWarningCount: safeInt(axSummary.driftWarningCount, 0, 0, 10_000),
+        degradedLayout: axSummary.degradedLayout === true
+    };
+}
 export async function submitSessionReport(report, options = {}) {
+    if (options.userConsentConfirmed !== true) {
+        return {
+            submitted: false,
+            reason: "explicit user consent required for telemetry submission"
+        };
+    }
     const config = options.config ?? readTelemetryConfig();
     if (!config.enabled || !config.endpoint) {
         return {
@@ -9,7 +82,7 @@ export async function submitSessionReport(report, options = {}) {
             reason: "telemetry not configured (set ODIN_TELEMETRY_ENDPOINT to opt in)"
         };
     }
-    const redacted = redactPayload(report);
+    const redacted = redactPayload(toTelemetryPayload(report));
     const fetchImpl = options.fetchImpl ?? fetch;
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const controller = new AbortController();
@@ -30,7 +103,7 @@ export async function submitSessionReport(report, options = {}) {
         }
         return {
             submitted: response.ok,
-            endpoint: config.endpoint,
+            endpoint: redactTelemetryEndpoint(config.endpoint),
             status: response.status,
             id: typeof parsed.id === "string" ? parsed.id : undefined,
             reason: response.ok ? undefined : `HTTP ${response.status}`
@@ -39,8 +112,8 @@ export async function submitSessionReport(report, options = {}) {
     catch (error) {
         return {
             submitted: false,
-            endpoint: config.endpoint,
-            reason: error instanceof Error ? error.message : "network error"
+            endpoint: redactTelemetryEndpoint(config.endpoint),
+            reason: error instanceof Error ? redactString(error.message) : "network error"
         };
     }
     finally {

package/dist/src/telemetry/submit.js.map

@@ -1 +1 @@
-{"version":3,"file":"submit.js","sourceRoot":"","sources":["../../../src/telemetry/submit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAwB,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAgB9C,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAA+B,EAC/B,UAAyB,EAAE;IAE3B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,mBAAmB,EAAE,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxC,OAAO;YACL,SAAS,EAAE,KAAK;YAChB,MAAM,EAAE,kEAAkE;SAC3E,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC7C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC;IAE1D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAE9D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,QAAQ,EAAE;YAChD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;YAC9B,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,IAAI,MAAM,GAAmC,EAAE,CAAC;QAChD,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAmC,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;QACxE,CAAC;QAED,OAAO;YACL,SAAS,EAAE,QAAQ,CAAC,EAAE;YACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,EAAE,EAAE,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS;YACzD,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,QAAQ,CAAC,MAAM,EAAE;SAC5D,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,SAAS,EAAE,KAAK;YAChB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;SACjE,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}
+{"version":3,"file":"submit.js","sourceRoot":"","sources":["../../../src/telemetry/submit.ts"],"names":[],"mappings":"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"}

package/docs/guides/quick-start.md

@@ -1,74 +1,142 @@
 # Quick Start
 
-ODIN Sentinel runs as a local MCP server over stdio.
+ODIN Sentinel runs as a local MCP server over stdio. It returns protocol
+resources, startup packets, validation results, delegation envelopes, closeout
+checklists, and optional telemetry redaction helpers.
 
-It does not provide model inference. It does not host a backend. Your MCP client
-starts the process, calls ODIN tools, and reads ODIN protocol resources.
+Plain version: install the package, connect it to an agent app, run one smoke
+test, then check that each selected agent can sign in, use its model, and follow
+the role instructions. If any step blocks, stop there and choose the safest next
+step. You are still in control.
 
-## From Source
+## Which Path Should I Choose?
+
+- New to this: use the global install path, then run the global smoke test.
+- Avoid global installs: use the zero-install `npx` command everywhere.
+- Using Claude Code plugin support: use the plugin README, then come back here
+  for readiness checks.
+- Local model users: run the normal smoke test and a separate local inference
+  smoke test before launching agents.
+
+## 1. Prerequisites
+
+- Node.js `>=22.13.0`
+- npm or pnpm
+- at least one MCP-capable harness
+- CMUX for governed team mode
+- account/auth readiness for each selected harness
+- local model endpoint readiness if you plan to use local inference
+
+## 2. Install
 
 ```bash
-pnpm install
-pnpm run build
-node dist/src/bin/index.js
+npm i -g @bradheitmann/odin-sentinel
 ```
 
-## Client Configuration
-
-Use the built server as a stdio command:
+Or use zero-install from MCP configs:
 
-```json
-{
-  "mcpServers": {
-    "odin-sentinel": {
-      "command": "node",
-      "args": ["/absolute/path/to/odin-sentinel/dist/src/bin/index.js"]
-    }
-  }
-}
+```bash
+npx -y -p @bradheitmann/odin-sentinel odin-sentinel-mcp
 ```
 
-For local development:
+## 3. Configure MCP
+
+Point each selected harness at the `odin-sentinel-mcp` stdio command. Restart the
+harness after editing config.
 
 ```json
 {
   "mcpServers": {
     "odin-sentinel": {
-      "command": "pnpm",
-      "args": ["exec", "tsx", "/absolute/path/to/odin-sentinel/src/bin/index.ts"]
+      "command": "npx",
+      "args": ["-y", "-p", "@bradheitmann/odin-sentinel", "odin-sentinel-mcp"]
     }
   }
 }
 ```
 
-## First Calls
-
-Ask the client to call:
+## 4. Install Skill Or Fallback Context
 
-1. `odin.get_version`
-2. `odin.get_runtime_notice`
-3. `odin.get_startup_packet`
+Use the best available context path for each harness:
 
-Then read:
+1. Native skill, if the harness supports it.
+2. Plugin/install path that bundles the skill and MCP server, if available.
+3. Full prompt injection from `odin.get_bootstrap_skill`, if skill/plugin support
+   is unavailable.
+4. Protocol snapshot from `odin.export_protocol_snapshot` for non-MCP or bridge
+   clients.
 
-1. `odin://protocol/main`
-2. `odin://protocol/roles`
-3. `odin://protocol/topology`
-4. `odin://protocol/delegation`
+MCP supplies tools/resources. Native skill context improves automatic invocation.
+Prompt injection is fallback only.
 
-That is enough for a client to understand the default team shape and how to
-start cleanly.
+## 5. Smoke Test
 
-For a suggested starter team, see
-[recommended-starter-team.md](recommended-starter-team.md).
+Global install smoke test:
 
-## Local State
+```bash
+printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}\n' \
+  | odin-sentinel-mcp
+```
 
-ODIN may point agents at these project-local locations:
+Zero-install smoke test:
 
-- `docs/handoffs/`
-- `.odin/handoffs/`
-- `.odin/audit/`
+```bash
+printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}\n' \
+  | npx -y -p @bradheitmann/odin-sentinel odin-sentinel-mcp
+```
 
-They are not bundled state. Create them in the project where your agents are
-working if you want persistent handoffs or audit notes.
+Expect `serverInfo.name = odin-sentinel` and `serverInfo.version = 0.4.7`.
+Minimum compatible child MCP version: `0.4.5`.
+
+## 6. Auth And Provider Readiness
+
+Ask whether selected harnesses are already provisioned. Do not ask users to paste
+API keys into prompts or docs. Verify provider status without printing secret
+values. Common secret/provider paths include Doppler, 1Password CLI, environment
+variables, direnv, mise, and dotenv-style files.
+
+If those names are unfamiliar, use this safer question instead: "Is this agent
+already signed in or configured outside this chat?" If the answer is no, pause
+launch and either sign in through the tool's normal UI, ask someone to configure
+the provider outside chat, choose another harness, or keep the role slot empty.
+
+For local inference, endpoint reachability is not enough. The selected model must
+return visible content within the timeout and must not return only
+`reasoning_content`.
+
+## 7. CMUX Governed-Team Launch
+
+Governed team mode requires CMUX. Keep EXEC PM in the same CMUX workspace as the
+rest of the team by default. Use spatial/pod organization, not tab-only layouts,
+for the canonical operator surface.
+
+Slot provisioning may happen before readiness is complete. Do not launch role
+occupants until readiness passes or EXEC PM records a waiver/substitution.
+
+## 8. Deterministic Bootstrap Order
+
+1. Confirm Node.js and package version.
+2. Configure and smoke-test ODIN MCP.
+3. Install native skill or prepare full prompt fallback.
+4. Open CMUX and compute the target layout.
+5. Select harnesses and check auth/account readiness.
+6. Smoke-test local inference if used.
+7. Run role-compatibility smoke tests.
+8. Launch EXEC PM in the CMUX workspace.
+9. Stage role slots and collect boot receipts.
+10. Activate work only after the manifest validates.
+
+## Troubleshooting
+
+| Symptom | Action |
+| --- | --- |
+| MCP unavailable | Restart the host, re-check config path, and run the stdio smoke test. |
+| Skill missing | Install the native skill where supported or use `odin.get_bootstrap_skill` as full prompt fallback. |
+| Auth/login required | Ask the user to provision the provider; verify status without printing secrets. |
+| Permission prompt | Stop and route to PM/user; do not bypass silently. |
+| Stale MCP version | Reinstall with `@latest`, restart host, and confirm `0.4.7`. |
+| Local inference stall | Require visible content within timeout; endpoint-only success is insufficient. |
+| Role refusal | Mark the role `NON_GOVERNED_ONE_SHOT_ONLY` unless MCP/skill/full protocol proof is established. |
+
+`NON_GOVERNED_ONE_SHOT_ONLY` means the agent may help with one bounded task, but
+is not suitable for a persistent governed role.