lingtai-kernel

Read-only health diagnostics for LingTai agents and bots. Use when an agent appears offline or unreachable, when a machine migration may have left stale MCP/addon command paths, when heartbeat/status/process/notification/log surfaces disagree, or before deciding whether to mail, refresh, CPR, or edit persistent configuration. Includes a bundled doctor.py script for layered local checks without exposing secrets.

Complete catalogue of environment variables consumed by the LingTai kernel, wrapper, bundled MCPs, adapters, tests, and daemon composition surfaces.

Second-layer router for LingTai's progressive-disclosure operating manuals. Read this when resident substrate/procedures are too compact and you need the right lower reference. Route here for the expanded substrate/runtime model, lifecycle and `system` tool actions, the init.json composition and preset runtime model route, action/procedure discipline and skill routing, tool-result summarization, SQLite/`log.sqlite` trace inspection and trajectory mining, runtime/kernel update checks and nudges, environment variables, goal notifications, molt/memory questions, MCP/addon ownership, collaboration topology, and resident prompt design. The nested catalog below names each reference and its exact trigger.

Mandatory repository-local development guide for LingTai's Python kernel and runtime. Use this before changing code, architecture documents, tests, packaging, capabilities, adapters, or developer documentation in lingtai-kernel. Routes each task through the exact baseline, the distributed ANATOMY/CONTRACT systems, focused validation, and pull-request safety gates.

Operational guide for LingTai's built-in file tools: read, write, edit, glob, and grep. Use when working with local text files, deciding whether to use file tools versus bash, handling large files, avoiding binary/image misuse, or reading non-UTF-8 text via explicit bash/Python/iconv instead of complicating the core read tool. Covers UTF-8 policy, safe write/edit discipline, search workflows, and examples for GBK/Shift-JIS/Latin-1 conversion.

Router for LingTai's distributed code navigation system. Use this before navigating, creating, or maintaining kernel ANATOMY.md files. The normative anatomy-of-anatomy now lives at the repository-root ANATOMY.md; this skill explains how an agent enters and descends that graph, how it pairs with the distributed CONTRACT.md interface-definition graph, and what to do when code and navigation disagree.

Thin routing manual for NoKV-controlled workbenches. Use when an agent is asked to persist task inputs, scripts, outputs, logs, provenance, or run manifests through the `workbench_*` MCP tools instead of ordinary local file writes. Covers MCP registration, directory layout, append and edit discipline, conditional reads, cross-workbench queries, commit discipline, and leased checkpoint snapshots with naming, renewal, discovery, and point-in-time history reads.

Nested notification-manual reference for LingTai's notification filesystem channel protocol, allowlist, payload envelopes and instructions, nudge routing, kernel sync, voluntary check behavior, and canonical producer state versus notification mirrors. Read after notification-manual when interpreting, producing, or debugging notification payloads; skip for dismissal policy.

Nested notification-manual reference for choosing safe atomic notification dismissal, producer-specific verbs, stale-version and force behavior, protected channels, post-molt acknowledgement, and legacy large_tool_result reminder escape hatches. Read after notification-manual before clearing a channel or diagnosing a dismissal refusal; summarization mechanics live in summarize-manual instead.

Notification filesystem and standalone notification tool router for LingTai. Read this when using notification(action='manual'|'check'|'dismiss_channel'| 'dismiss_event'|'dismiss_ref'), interpreting `.notification/<channel>.json`, or deciding between producer-specific handling and safe mirror dismissal. Routes channel/sync mechanics and dismissal safety into nested references; large-result compaction remains owned by summarize-manual.

Router and operational guide for the psyche tool — molt, pad management, session journaling, and post-wipe recovery. Read this when: you are about to molt; you need to tend the four durable stores; you want guidance on writing a good summary or session journal; you wake up after a system-performed wipe with a system-authored summary; or you need to understand keep_tool_calls, keep_last, and pad.append. Routes consequential molt handoffs to assets/molt-template.md while keeping routine guidance compact.

Complete guide for the read tool: continuation workflow, next_offset pagination, line_truncated handling, runtime tool-result spill vs read-level pagination, 100k read default / 200k runtime hard cap, and when to use bash/grep/sed for truncated lines. Use when implementing complete file-read workflows, handling large files, or understanding cap and truncation semantics.

Operational guide for the `soul` tool — your inner voice. Read this when: you call `soul(action='flow')` and get a `status: disabled` result; you want to understand why soul flow is off by default and how the operator enables it; you are tuning `delay_seconds`/`consultation_past_count` with `config` and want to know whether fires will actually happen; or you need the difference between the always-available actions (inquiry/config/voice/dismiss) and the opt-in `flow`. Covers the `LINGTAI_SOUL_FLOW_ENABLED` env gate, disabled-flow behavior, delay-vs-off-switch semantics, enabling/disabling, troubleshooting, and the privacy/cost rationale.

Goal notification manual: `.notification/goal.json` source-of-truth, fields, instructions, idle reminders, protected dismiss behavior, and cancellation or completion semantics.

Nested system-manual reference for expanded LingTai procedure/action guidance. Read via the `system-manual` router when resident procedures are too compact and you need details about progressive disclosure, responsiveness, external side-effect authorization, choosing bash vs daemon vs avatar vs MCP, depositing work into pad/knowledge/skills/character, idle/lifecycle procedure, molt checklist, skill routing, web/file/media/artifact handling, standalone HTML deliverables, sharing artifacts, issue reporting, and resident procedures maintenance. This is a nested skill-reference under `system-manual`, not a standalone catalog skill; its folder may carry scripts/assets as procedure guidance grows.

Nested system-manual reference for tracing LingTai kernel update nudges: runtime/version/source identity, packaged versus editable/source behavior, heartbeat dispatch, nudge persistence and notification delivery, refresh versus installation, human confirmation, and post-refresh verification.

Nested system-manual reference for inspecting LingTai runtime traces through the additive SQLite/log.sqlite sidecar. Read via the `system-manual` router when you need `lingtai-agent log doctor|query|rebuild`, JSONL source-of-truth rules, read-only SQL safety, offline rebuild/WAL caveats, events, chat_entries, and token_entries schema, daemon/chat-history/token-ledger indexing, query recipes, runtime problem investigation workflow, trajectory mining workflow, SQL-based event metrics, cheap-model/daemon strategy, finding schema, prompt templates, digest output, or log redaction pitfalls. This is a nested skill-reference under `system-manual`, not a standalone catalog skill; its folder may carry companion scripts and assets as SQLite trace tooling grows.

Nested system-manual reference for the expanded LingTai substrate/runtime model. Read via the `system-manual` router when resident substrate is too compact and you need details about body/extensions, bash vs daemon vs avatar vs MCP, lifecycle states (ACTIVE/IDLE/STUCK/ASLEEP/SUSPENDED), the `system` tool, notification/read/dismiss discipline, communication channels, memory layers, molt model, runtime log routing, collaboration topology, MCP/addon ownership, idle/soul behavior, preset tiers, the detailed preset runtime model (raw vs resolved init.json, preset identity, TUI/library vs main-agent allowed-only catalogs, swap/revert/refresh, daemon task explicit/omitted/CLI-skip paths), and resident substrate maintenance. This is a nested skill-reference under `system-manual`, not a standalone catalog skill; its folder may carry scripts/assets as the substrate reference grows.

Detailed operational guide for tool-result summarization across LingTai's three context-compression / continuation modes: a-priori reasoning-guided (summary=true on bash/read/grep/daemon/glob), a-posteriori agent-guided (system(action="summarize")), and molt. Covers what tool-result summarization is, why it implements progressive disclosure, when to summarize urgently versus during idle cleanup, how to write good summaries, how to recover the original tool result by tool_call_id, and how summarize differs from molt.

Progressive-disclosure usage manual for the Cloud Mail REST email MCP tool. Read this when you need detail beyond the one-line action descriptions: check/search filters, the compound id (account:emailId) for read, send (needs user credentials), plain vs HTML bodies, accounts/add_user basics, and the external-email side-effect caveats. Pulled on demand via action='manual'; you do not need to call it before every send.

Progressive-disclosure usage manual for the Feishu (Lark) MCP tool. Read this when you need detail beyond the one-line action descriptions: receive_id vs receive_id_type (open_id/chat_id), send vs reply, check/read/search, placeholder + edit for long responses, contacts/accounts basics, the notification transient-hook vs persistent-context split, and side-effect caveats. Pulled on demand via action='manual'; you do not need to call it before every send.

Progressive-disclosure usage manual for the IMAP/SMTP email MCP tool. Read this when you need detail beyond the one-line action descriptions: send vs reply, check/read/search over folders, the compound email_id (account:folder:uid), attachments, move/flag/delete/folders, contacts/accounts basics, and the important external-email side-effect caveats (real outbound mail — confirm before sending). Pulled on demand via action='manual'; you do not need to call it before every send.

Progressive-disclosure usage manual for the Telegram MCP tool. Read this when you need detail beyond the one-line action descriptions: media.type='document' vs 'photo' for charts/reports/generated artifacts, placeholder/live-status messages, reply vs send, read/check/search, parse_mode/entities, chat_action, dynamic slash commands, the programmable Task Card (task_card tool) — including task-specific watcher design for meaningful long-running work — and error surfacing. Pulled on demand via action='manual'; you do not need to call it before every send.

Nested telegram-mcp-manual reference for the programmable Telegram Task Card (`task_card` tool). Read this when a task needs a truthful, task-specific watcher: inspect the actual task and producer evidence, design a small renderer, and use the start | inspect | retry | stop lifecycle without prescribing a fixed layout or data source.

Progressive-disclosure usage manual for the WeChat MCP tool. Read this when you need detail beyond the one-line action descriptions: user_id targeting, send vs reply, check/read/search, media_path attachments (image/video/voice/file), contacts/accounts basics, and external-delivery side-effect caveats. Pulled on demand via action='manual'; you do not need to call it before every send.

Progressive-disclosure usage manual for the WhatsApp Cloud API MCP tool. Read this when you need detail beyond the one-line action descriptions: the 24-hour customer-service window and approved templates, send vs reply vs react, check/read/search, media attachments, contacts/accounts/status basics, the notification transient-hook vs persistent-context split, and external-delivery side-effect caveats. Pulled on demand via action='manual'; you do not need to call it before every send.

Complete operational guide for the avatar tool — spawning, managing, and communicating with 他我 (alter-ego agents). Read this when: you are about to spawn an avatar; an avatar you spawned goes quiet; you need to decide between avatar, daemon, or bash; or you are an avatar and need to know how to escalate to your parent. Covers spawn types, naming rules, discipline, escalation protocol, and the parent_prompt contract.

Nested shell-manual reference for Aider CLI. Read this when you need to run, validate, or document `aider` as a long-running shell subprocess or LingTai daemon harness candidate.

Nested shell-manual reference for Claude Code CLI. Delegate code implementation, patch writing, documentation, and refactoring to Claude Code CLI (Anthropic's coding agent). Runs non-interactively from bash, uses the human's Claude Max subscription (no additional API costs), and supports quality/effort/budget controls. Use this when you need to write code, generate patches, refactor files, create documentation, or do any multi-file code work that would be faster delegated than done manually.

Nested shell-manual reference for Charm Crush CLI. Read this when you need to run, validate, or document `crush` as a long-running shell subprocess or LingTai daemon harness candidate.

Nested shell-manual reference for Cursor Agent CLI. Read this when you need to run, validate, or document `cursor-agent` as a long-running shell subprocess or LingTai daemon harness candidate.

Nested shell-manual reference for Gemini CLI. Read this when you need to run, validate, or document `gemini` as a long-running shell subprocess or LingTai daemon harness candidate.

Nested shell-manual reference for Goose CLI. Read this when you need to run, validate, or document `goose` as a long-running shell subprocess or LingTai daemon harness candidate.

Nested shell-manual reference for Kimi Code CLI. Read this when you need to run, validate, or document `kimicode / kimi` as a long-running shell subprocess or LingTai daemon harness candidate.

Nested shell-manual reference for MiMo Code CLI. Read this when you need to run, validate, or document `mimocode / mimo` as a long-running shell subprocess or LingTai daemon harness candidate.

Nested shell-manual reference for Oh-My-Pi CLI. Read this when you need to run, validate, or document `omp` as a long-running shell subprocess or LingTai daemon harness candidate.

Nested shell-manual reference for OpenAI Codex CLI. Manual (not a tool) for OpenAI Codex CLI — OpenAI's coding agent that runs locally from your terminal. Built in Rust for speed and efficiency. Supports headless remote control, Vim editing, plugin management, hooks, and Chrome browser integration. Read this when the human asks to use OpenAI Codex CLI, wants to compare it with Claude Code, or needs help with installation and configuration.

Nested shell-manual reference for OpenCode CLI. Manual (not a tool) for OpenCode CLI — an open-source terminal coding agent that runs locally, supports 75+ LLM providers through Models.dev, and can be scripted with `opencode run` or served through a reusable headless backend. Read this when the human asks to use OpenCode as a CLI tool, compare it with Claude Code or Codex, configure providers/agents/MCPs, or run non-interactive coding tasks from bash.

Nested shell-manual reference for OpenHands CLI. Read this when you need to run, validate, or document `openhands` as a long-running shell subprocess or LingTai daemon harness candidate.

Nested shell-manual reference for Qwen Code CLI. Read this when you need to run, validate, or document `qwen-code / qwen` as a long-running shell subprocess or LingTai daemon harness candidate.