---
phase: 29-default-provider
plan: 01
subsystem: ui
tags: [hermes, adapter, onboarding, probe, wizard, agents]

# Dependency graph
requires:
  - phase: 27-hermes-adapter
    provides: hermes_local adapter with testEnvironment method
  - phase: 28-ollama-integration
    provides: Hermes session and heartbeat integration
provides:
  - Board-auth GET /adapters/:type/probe route with no companyId required
  - agentsApi.probeAdapter(type) client method
  - NexusOnboardingWizard auto-detects Hermes and falls back to hermes_local
  - Directory input optional when hermes_local is selected
  - NewAgentDialog AGENT_TEMPLATES adapter-neutral (role+name only, no adapterType)
affects: [30-agent-templates, default-provider-ux, onboarding]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - Board-auth probe route pattern for adapter availability detection without companyId
    - useEffect probe-on-open pattern for runtime adapter detection in wizard
    - Adapter-neutral template navigation (role+name only, no adapterType in URL)

key-files:
  created: []
  modified:
    - server/src/routes/agents.ts
    - ui/src/api/agents.ts
    - ui/src/components/NexusOnboardingWizard.tsx
    - ui/src/components/NewAgentDialog.tsx

key-decisions:
  - "Probe route uses board auth (not company-scoped) — adapter availability is instance-level, not company-level"
  - "graceful probe failure keeps claude_local default — network errors or missing adapter don't break onboarding"
  - "hermes_local makes directory optional (not required) — Hermes doesn't need a cwd to operate"
  - "AGENT_TEMPLATES in NewAgentDialog are now adapter-neutral — /agents/new form handles its own adapter default logic"

patterns-established:
  - "Probe-on-open pattern: useEffect with effectiveOnboardingOpen trigger for lazy adapter detection"
  - "Board-auth adapter route: /adapters/:type/probe — no companyId, board auth guard only"

requirements-completed: [DFLT-01, DFLT-02]

# Metrics
duration: 8min
completed: 2026-04-02
---

# Phase 29 Plan 01: Default Provider Summary

**Board-auth hermes probe route + NexusOnboardingWizard Hermes fallback + adapter-neutral agent templates in NewAgentDialog**

## Performance

- **Duration:** ~8 min
- **Started:** 2026-04-02T17:29:41Z
- **Completed:** 2026-04-02T17:37:00Z
- **Tasks:** 2
- **Files modified:** 4

## Accomplishments
- Added GET /adapters/:type/probe route with board auth guard — returns {available, status, checks} without requiring a companyId
- Added agentsApi.probeAdapter(type) client method that calls the new probe route
- NexusOnboardingWizard now probes for hermes_local on open and uses it as defaultAdapter when available
- Directory input is optional when hermes_local is selected; description text updated for local AI path
- NewAgentDialog AGENT_TEMPLATES no longer hardcode adapterType — handleTemplateSelect navigates with role+name only

## Task Commits

Each task was committed atomically:

1. **Task 1: Add board-auth adapter probe route and frontend client** - `f85ced58` (feat)
2. **Task 2: Update NexusOnboardingWizard and NewAgentDialog** - `a2f54282` (feat)

## Files Created/Modified
- `server/src/routes/agents.ts` - Added GET /adapters/:type/probe with board auth guard
- `ui/src/api/agents.ts` - Added agentsApi.probeAdapter(type) method
- `ui/src/components/NexusOnboardingWizard.tsx` - Hermes probe on open, defaultAdapter state, optional directory, updated UI text
- `ui/src/components/NewAgentDialog.tsx` - Removed adapterType from AGENT_TEMPLATES, updated handleTemplateSelect

## Decisions Made
- Probe route uses board auth only (no companyId) — adapter availability is an instance-level concern
- Probe failure is silent (catches error, keeps claude_local) — graceful degradation for missing adapter or network issues
- hermes_local makes directory optional, not required — Hermes runtime doesn't need cwd
- AGENT_TEMPLATES stripped of adapterType — /agents/new form is responsible for resolving the adapter default

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None. Pre-existing TypeScript module resolution errors (missing @paperclipai/shared, @paperclipai/adapter-utils etc.) were already present in the codebase and unrelated to these changes.

## Known Stubs

None. All data paths are wired — probeAdapter calls the real route, defaultAdapter flows into all three agent creates.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness
- Probe route is ready; Plan 02 can use it for any additional default provider logic
- NexusOnboardingWizard now self-selects hermes_local when Hermes is installed
- NewAgentDialog templates are adapter-neutral and ready for any future adapter default logic in /agents/new

---
*Phase: 29-default-provider*
*Completed: 2026-04-02*