Opt-in and advisory

Use AI Diagnose as a local sidecar, not as the system truth.

AI Diagnose reads the existing local diagnostics surface and turns it into a more human explanation. It does not replace status, doctor, verify, or log-health. It also does not read exported note content in v1.

What it reads

  • ./notesctl status --json
  • ./notesctl doctor --json
  • ./notesctl log-health --json
  • ./notesctl aggregate --tail N

What it does not read in v1

  • No Apple Notes body content
  • No exported markdown or attachments
  • No remote GitHub control-plane state
  • No write actions into the snapshot workflow

How to enable it

# config/notes_snapshot.env
# opt-in required; AI Diagnose now routes through a local Switchyard runtime
# NOTES_SNAPSHOT_AI_ENABLE="1"
# NOTES_SNAPSHOT_AI_PROVIDER="gemini"
# NOTES_SNAPSHOT_AI_MODEL="gemini-2.5-flash"
# Optional Switchyard service root or invoke URL override
# NOTES_SNAPSHOT_AI_BASE_URL="http://127.0.0.1:4010"

./notesctl ai-diagnose
./notesctl ai-diagnose --json

When AI is disabled or misconfigured, the command still returns a deterministic fallback summary instead of breaking the rest of the system.

Apple Notes Snapshot does not forward provider credentials into Switchyard for you. The local Switchyard service itself must already be running with a provider credential name it recognizes. For the current Gemini BYOK path, that means one of SWITCHYARD_GEMINI_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY on the Switchyard side.

How to read the output

  • Observed Facts: deterministic evidence copied from the existing diagnostics surface
  • Run / Change Summary: recent-run trend, streak, failure clustering, and operator-safe change framing built from structured operational state
  • Recoverability: a compact state that tells you whether you are looking at bootstrap, recoverable failure handling, a watch window, stable monitoring, or a manual-review case
  • Workflow Hint: the suggested order for the next operator checks, so the output reads more like a control-room handoff than a loose bag of commands
  • Operator Advisory: a priority-oriented control-room summary that explains whether you are looking at a first-run gap, an active failure cluster, a stale loop, or a healthy/watch-only state
  • Likely Diagnosis: advisory interpretation of those facts
  • Recommended Next Steps: concrete commands to run next
  • Confidence / Limitations: what was inferred, and what stayed outside scope

Best-fit AI role

  • Operator next-step assistant: explain what the current local control room is already telling you
  • Run-change summarizer: turn recent-run metadata, streaks, grouped failures, and recoverability into a calmer handoff for operators without opening exported note content
  • Failure and recovery explainer: translate status, doctor, log-health, and recent-run evidence into calmer operator language
  • Workflow sequencing hint: suggest the next deterministic checks in order instead of leaving operators with a flat command pile
  • Not a generic notes assistant: v1 does not answer note-content questions or replace the deterministic runbook path

Provider notes

  • Switchyard local runtime: AI Diagnose now hands model invocation to a local Switchyard service instead of talking to providers directly from this repo
  • Current best-supported live path here: Gemini BYOK through the local Switchyard runtime
  • Credential boundary: provider keys live on the Switchyard side, not in Apple Notes Snapshot

Hard boundaries that still hold

  • AI Diagnose is advisory only
  • The canonical system truth is still the deterministic repo-owned command surface
  • Phase 2 still works from structured operational state and recent-run metadata, not default note-content analysis
  • AI Diagnose does not enter the run/install/verify hot path
  • Note content stays out of scope in v1