nano-core-debug

name	nano-core-debug
description	Diagnose nano-core runtime failures. Use for provider/model errors, Pi launch or skill-discovery failures, Telegram/WhatsApp routing, singleton locks, service state, IPC, SQLite state, scheduler behavior, or per-group logs; not for installation or feature work.

nano-core Debug

Diagnose from evidence before changing state. Paths and commands vary by install mode, so verify them in the checkout and runtime configuration.

When to use this skill

• Use when nano-core is failing, degraded, inconsistent, or unable to discover a configured capability.
• Use to collect a reproducible symptom, relevant logs, and the smallest failing boundary.

When not to use this skill

• Do not use for first-time installation; use nano-core-setup.
• Do not use for ordinary feature implementation or speculative cleanup.
• Do not delete locks, sessions, databases, containers, or state as a diagnostic shortcut.

Diagnostic order

1. Capture the exact symptom, channel, group, request time, and whether the installed service or a foreground process owns the runtime.
2. Run the read-only health path first: nano-core doctor --json when the CLI is linked, otherwise npm run doctor from the checkout.
3. Check service status and confirm only one host process owns data/nano-core.lock; a second host process racing the same lock causes Telegram getUpdates conflicts.
4. Inspect the relevant per-group logs under groups/<group>/logs/. Use LOG_LEVEL=debug only when more detail is required; it logs container args and mounts.
5. Verify the provider and model identifiers (PI_API/PI_MODEL, or the active provider preset) and that the required credential variable is passed through to the container. Redact secret values.
6. For skill issues, compare the managed set under data/pi/<group>/.pi/skills/ with Pi's configured agent skill directory under data/pi/<group>/.pi/agent-fft/skills/; both are synced from skills/runtime/ on each container run.
7. For routing issues, verify the registered group, main-chat assignment, trigger word, and channel-specific command scope.
8. Reproduce with the narrowest safe check. NANO_CORE_DRY_RUN=1 can exercise routing without a live model call.
9. State the root cause, evidence, and smallest proposed fix. Do not implement a fix unless requested.

Common evidence patterns

• "No models available": the provider credential was not passed through to the container, or no provider is configured.
• Provider/model not found: PI_API/PI_MODEL (or the active provider preset) do not match an available model.
• Telegram polling conflict: another bot instance is polling the same token, or two host processes are racing data/nano-core.lock.
• Docker connection error: the daemon is unavailable, unhealthy, or inaccessible to the current user.
• Skill visible through nano-core but not Pi: the managed and configured-agent skill directories differ, or the Pi session predates the latest skill sync.

Guardrails

• Never run destructive git commands unless explicitly requested.
• Preserve unrelated worktree changes.
• Privileged diagnostics and service controls are main/admin chat only.
• Do not expose tokens, API keys, message contents, or private database records in reports.