| 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
- Capture the exact symptom, channel, group, request time, and whether the installed service or a foreground process owns the runtime.
- Run the read-only health path first:
nano-core doctor --json when the CLI is linked, otherwise npm run doctor from the checkout.
- 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.
- 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.
- 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.
- 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.
- For routing issues, verify the registered group, main-chat assignment, trigger word, and channel-specific command scope.
- Reproduce with the narrowest safe check.
NANO_CORE_DRY_RUN=1 can exercise routing without a live model call.
- 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.
