code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/code_puppy_agent/AGENTS_AND_TOOLS.md

@@ -0,0 +1,155 @@
+# Agent & Tool System
+
+> Part of the `code-puppy-agent` skill. Read this when you need to
+> understand how agents are structured/discovered, or how tools get
+> registered and wired to an agent. See `SKILL.md` for the overview and
+> the full reference map.
+
+---
+
+## Agent System
+
+### BaseAgent (`agents/base_agent.py`)
+
+All agents inherit from `BaseAgent` (ABC). Key interface:
+
+| Member | Purpose |
+|--------|---------|
+| `name` (abstract property) | Stable machine identifier, e.g. `"code-puppy"` |
+| `display_name` (abstract property) | Human name with emoji |
+| `description` (abstract property) | One-line summary |
+| `get_system_prompt()` (abstract) | The authored system prompt (identity is appended separately at runtime) |
+| `get_available_tools()` (abstract) | List of tool-name strings from `TOOL_REGISTRY` |
+| `get_model_name()` | Effective model: runtime override > pinned > global |
+| `get_full_system_prompt()` | Authored prompt + `load_prompt` plugin fragments + identity ID |
+
+`BaseAgent` is a **thin conductor**. Real logic lives in sibling modules:
+- `_builder.py` — builds the pydantic-ai `Agent`, wires MCP toolsets
+- `_runtime.py` — `run_with_mcp()` orchestration, cancellation, retries
+- `_history.py` — token estimation, hashing, orphan pruning
+- `_compaction.py` — summarization/truncation when context overflows
+
+### Agent Types
+
+**Python agents** — classes in `agents/` discovered automatically by
+`agent_manager._discover_agents()` via `pkgutil.iter_modules`. Any
+`BaseAgent` subclass (excluding `JSONAgent` itself) in a non-underscore
+module gets registered.
+
+**JSON agents** — `JSONAgent` loads from `~/.code_puppy/agents/*.json`
+(user) and `<CWD>/.code_puppy/agents/*.json` (project). Project overrides
+user on name collision. Required fields: `name`, `description`,
+`system_prompt`, `tools`. Optional: `display_name`, `user_prompt`,
+`tools_config`, `model`, `mcp_servers`.
+
+**Plugin agents** — registered via the `register_agents` callback, which
+returns `[{"name": "...", "class": SomeAgentClass}]` (or
+`{"name": ..., "json_path": ".../agent.json"}`).
+
+**Discovery & precedence** — `_discover_agents()` runs three phases:
+
+1. Builtin Python classes (`pkgutil` scan of `agents/`).
+2. JSON agents via `discover_json_agents()`: the **user** dir is scanned
+   first, then the **project** dir overwrites it on collision, so **project
+   wins over user**. Both are skipped if a builtin Python agent already owns
+   the name (builtin beats JSON).
+3. Plugin-registered agents via `on_register_agents()` — these overwrite
+   `_AGENT_REGISTRY` **unconditionally**, so a plugin agent can shadow a
+   builtin. Register under a unique name.
+
+Net precedence: **builtin Python > JSON project > JSON user**; plugin
+agents are last-writer-wins (handled after the others, no collision guard).
+
+### Agent Manager (`agents/agent_manager.py`)
+
+- `get_current_agent()` — returns the active `BaseAgent` instance
+- `set_current_agent(name)` — switches agent, preserves history
+- `get_available_agents()` — dict of `name → display_name`
+- `clone_agent()` — creates a copy of the current agent
+
+Agent selection persists per **terminal session** (keyed by PPID) in
+`terminal_sessions.json` so different terminals can run different agents.
+
+---
+
+## Tool System
+
+### TOOL_REGISTRY (`tools/__init__.py`)
+
+A flat dict mapping tool-name strings to registration functions:
+
+```python
+TOOL_REGISTRY = {
+    "read_file": register_read_file,
+    "create_file": register_create_file,
+    "replace_in_file": register_replace_in_file,
+    # ... 60+ tools
+}
+```
+
+Each `register_*` function takes a pydantic-ai `agent` and calls
+`@agent.tool` to wire the tool's JSON schema.
+
+### How tools are assigned
+
+`register_tools_for_agent(agent, tool_names, agent_name=...)` is called
+during agent build. It:
+
+1. Loads plugin-registered tools via `on_register_tools()` → merges into `TOOL_REGISTRY`
+2. Merges plugin-advertised tools via `on_register_agent_tools(agent_name)` → unions into the requested list
+3. Expands compound tools (e.g. `"edit_file"` → `["create_file", "replace_in_file", "delete_snippet"]`)
+4. Registers each tool by calling its `register_func(agent)`
+
+### Built-in tool categories
+
+| Category | Tools |
+|----------|-------|
+| **File ops** | `list_files`, `read_file`, `grep` |
+| **File mods** | `create_file`, `replace_in_file`, `delete_snippet`, `delete_file` |
+| **Shell** | `agent_run_shell_command`, `agent_share_your_reasoning` |
+| **Sub-agents** | `list_agents`, `invoke_agent`, `invoke_agent_with_model` |
+| **Skills** | `activate_skill`, `list_or_search_skills` |
+| **User** | `ask_user_question`, `load_image_for_analysis` |
+| **Browser** | 30+ `browser_*` tools (Playwright-backed) |
+| **Models** | `list_available_models` |
+| **UC** | `universal_constructor` (dynamic tool factory) |
+
+### Plugin tools: two hooks, both required
+
+```python
+# 1. Define the tool (adds to TOOL_REGISTRY)
+def _register_tools():
+    return [{"name": "my_tool", "register_func": register_my_tool}]
+register_callback("register_tools", _register_tools)
+
+# 2. Advertise it to agents (adds to agent's tool list)
+def _advertise(agent_name=None):
+    return ["my_tool"]
+register_callback("register_agent_tools", _advertise)
+```
+
+Step 1 makes the tool *exist*; step 2 makes agents *see* it. Both are
+needed. `namespace_skill_search` (`code_puppy/plugins/namespace_skill_search/`)
+is a small, complete example of this pattern for a single tool
+(`browse_skill_namespace`) — see `SKILLS_SYSTEM.md` for what it does and
+`PLUGINS_AND_CALLBACKS.md` for the callback-safety reasoning behind how
+it's wired.
+
+### Async tool functions and blocking I/O
+
+Tool functions taking a `RunContext` (`activate_skill`,
+`list_or_search_skills`, `browse_skill_namespace`) are conventionally
+`async def` in this codebase. That matters for one non-obvious reason:
+pydantic-ai only auto-offloads **synchronous** tool functions to a worker
+thread (via `anyio.to_thread`); an `async def` tool runs directly on the
+event loop. If your async tool does blocking filesystem/network I/O
+(e.g. scanning a large directory tree), wrap the blocking call
+explicitly:
+
+```python
+result = await asyncio.to_thread(blocking_function, *args)
+```
+
+`namespace_skill_search/search_tool.py` does exactly this around its
+`build_namespaces()` call — a good reference implementation if you're
+writing a new async tool with real I/O in it.

code_puppy_core_plugins/code_puppy_agent/MODELS_AND_MCP.md

@@ -0,0 +1,104 @@
+# Model System & MCP Integration
+
+> Part of the `code-puppy-agent` skill. Read this when working with model
+> selection/config, or external MCP tool servers. See `SKILL.md` for the
+> overview and the full reference map.
+
+---
+
+## Model System
+
+### ModelFactory (`model_factory.py`)
+
+Resolves a model-name string into a pydantic-ai `Model` object.
+Supports providers: OpenAI, Anthropic, Gemini, Cerebras, OpenRouter,
+Azure, and custom OpenAI/Anthropic/Gemini-compatible endpoints.
+
+### Model configuration
+
+Models are defined in three places (merged at runtime):
+
+1. **Built-in defaults** — hardcoded in the factory
+2. **`~/.code_puppy/extra_models.json`** — user-defined custom models
+3. **Plugin injection** — `load_models_config` callback returns a dict
+
+Example `extra_models.json`:
+```json
+{
+  "my-model": {
+    "type": "custom_openai",
+    "name": "gpt-4o",
+    "custom_endpoint": {
+      "url": "https://api.example.com/v1",
+      "api_key": "$MY_API_KEY"
+    },
+    "context_length": 128000
+  }
+}
+```
+
+### Model types
+
+| Type | Provider |
+|------|----------|
+| `openai` / `openai_responses` | OpenAI |
+| `anthropic` | Anthropic (Claude) |
+| `gemini` | Google Gemini |
+| `cerebras` | Cerebras (via CerebrasProvider) |
+| `custom_openai` | Any OpenAI-compatible endpoint |
+| `custom_anthropic` | Anthropic-compatible endpoint |
+| `round_robin` | Cycle through N models (rate-limit mitigation) |
+| Plugin types | Registered via `register_model_type` callback |
+
+### Model selection precedence
+
+For any agent: **runtime override > agent-pinned model > agent's `model`
+field (JSON agents) > global model name**.
+
+The global model is set via `/model` and stored in config.
+
+---
+
+## MCP Integration
+
+### MCP Manager (`mcp_/manager.py`)
+
+Code Puppy manages external MCP (Model Context Protocol) servers that
+provide additional tools to agents. Key components:
+
+- **Registry** (`mcp_/registry.py`) — server definitions (stdio/SSE/streamable-http)
+- **Manager** (`mcp_/manager.py`) — lifecycle: start, stop, health checks
+- **Agent bindings** (`mcp_/agent_bindings.py`) — which agents get which servers
+- **Circuit breaker** (`mcp_/circuit_breaker.py`) — auto-disables flaky servers
+
+### How MCP servers attach to agents
+
+Servers can be:
+1. **Globally started** — available to all agents
+2. **Agent-bound** — declared in a JSON agent's `mcp_servers` field, or
+   bound via the `/mcp bind` menu
+3. **Auto-started** — bound servers with `auto_start: true` start when the
+   agent runs
+
+The `pre_mcp_autostart` hook fires before auto-start, letting plugins
+refresh tokens or mint credentials.
+
+### Managing MCP servers
+
+Use `/mcp` in the TUI:
+- `/mcp list` — show configured servers
+- `/mcp start <name>` / `/mcp stop <name>`
+- `/mcp status` — health dashboard
+- `/mcp bind` — attach servers to agents
+
+### MCP servers as skill providers — a known gap, not yet implemented
+
+Skills today are discovered only by filesystem scan (see
+`SKILLS_SYSTEM.md`) or via the `register_skills` callback. There is
+currently **no** mechanism for a bound MCP server to advertise skills of
+its own (e.g. a hypothetical `skill_provider` capability exposing
+`list_skills`/`get_skill`/`search_skills`) — skills served that way would
+just look like ordinary tool results, not first-class skills appearing in
+`/skills list` or `activate_skill`-able. If you're evaluating whether to
+build this, that's new platform work, not something `namespace_skill_search`
+or the existing skill-discovery code already covers.

code_puppy_core_plugins/code_puppy_agent/PLUGINS_AND_CALLBACKS.md

@@ -0,0 +1,147 @@
+# Plugin & Callback System
+
+> Part of the `code-puppy-agent` skill. Read this before writing a new
+> plugin, or when debugging why a hook isn't firing / is being
+> overwritten. See `SKILL.md` for the overview and the full reference map.
+
+---
+
+## Plugin discovery (three tiers)
+
+| Tier | Location | Load order |
+|------|----------|------------|
+| **Builtin** | `code_puppy/plugins/<name>/register_callbacks.py` | 1st |
+| **User** | `~/.code_puppy/plugins/<name>/register_callbacks.py` | 2nd |
+| **Project** | `<CWD>/.code_puppy/plugins/<name>/register_callbacks.py` | 3rd (highest precedence) |
+
+Each plugin is a directory containing `register_callbacks.py`. The loader
+auto-discovers it. Project plugins shadow user plugins on name collision.
+
+## The callback hook system
+
+`register_callback(phase, func)` at module scope. The callback engine
+(`callbacks.py`) stores functions per phase and fires them at the right
+time. All hooks accept sync or async functions.
+
+**Most important hooks for extending Code Puppy:**
+
+| Hook | When | Return value |
+|------|------|-------------|
+| `startup` | Once, at process start | (no return value used) — do one-time setup/migrations here, NOT at module import time (see below) |
+| `register_tools` | Tool registration | `list[dict]` with `name`, `register_func` |
+| `register_agent_tools` | Per-agent tool advertisement | `list[str]` of tool names |
+| `register_skills` | Skill catalogue | `list[dict]` with `name` + `skill_md`/`skill_md_path`/`frontmatter`+`body` |
+| `register_agents` | Agent catalogue | `list[dict]` with `name`, `class` |
+| `load_prompt` | System prompt assembly | `str` fragment or `None` |
+| `get_model_system_prompt` | Per-model prompt patch | `dict` with `instructions`/`handled` or `None` |
+| `custom_command` | Unknown `/slash` command | `True` (handled), `str` (message), or `None` (not mine) |
+| `pre_tool_call` | Before tool executes | Can modify args |
+| `post_tool_call` | After tool finishes | Observes result + duration |
+| `run_shell_command` | Before shell exec | Return `{"blocked": True}` to block |
+| `file_permission` | Before file op | `bool` — allow/deny |
+| `agent_run_start` / `agent_run_end` | Agent lifecycle | Observes name, model, session |
+
+The full list is in `callbacks.py` — `PhaseType` has ~45 phases.
+
+## Minimal plugin example
+
+```
+my_plugin/
+  __init__.py          # (can be empty)
+  register_callbacks.py
+```
+
+```python
+from code_puppy.callbacks import register_callback
+
+def _on_load_prompt():
+    return "\n## Project Rules\nAlways use type hints."
+
+register_callback("load_prompt", _on_load_prompt)
+```
+
+That's it. The loader handles discovery, import, and registration.
+
+---
+
+## Two gotchas that will bite you, both discovered building `namespace_skill_search`
+
+`namespace_skill_search` (`code_puppy/plugins/namespace_skill_search/`)
+groups skills into namespaces and replaces the flat per-skill list in the
+system prompt with a compact directory + a `browse_skill_namespace` tool
+(see `SKILLS_SYSTEM.md` for what it does from a user's perspective). It's
+also a good reference implementation for two hook-system pitfalls that
+are easy to hit and don't fail loudly when you do:
+
+### 1. `get_model_system_prompt` is last-write-wins, not additive
+
+If two plugins register a `get_model_system_prompt` callback, the second
+one processed can silently overwrite the first one's `instructions` —
+`model_utils.prepare_prompt_for_model` threads augmenter results through
+sequentially, and whichever callback runs last on a given key wins. This
+is *not* a merge; the built-in `agent_skills` plugin's own contribution
+(the flat skill list) can be clobbered by a badly-timed second callback
+on the same phase.
+
+**If you need to add content to the system prompt, use `load_prompt`
+instead whenever possible.** `load_prompt` fragments from every plugin
+are simply newline-joined by `base_agent.py::get_full_system_prompt` —
+there's no merge conflict possible, by construction. This is exactly why
+`namespace_skill_search` injects its namespace directory via
+`load_prompt` and explicitly avoids `get_model_system_prompt`, even
+though the content it's replacing (the flat skill list) is itself
+injected through `get_model_system_prompt`.
+
+### 2. Don't mutate config (or do any other real work) at import time
+
+A plugin's `register_callbacks.py` module body runs once, at import —
+which happens during every plugin scan, including in test collection.
+Anything at module scope that does real work (writes to
+`~/.code_puppy/puppy.cfg`, hits the filesystem, calls out to a network)
+is:
+
+- **Hard to test** — you'd need `importlib.reload()` gymnastics to
+  exercise it in isolation, and reloading re-runs *every* top-level
+  statement in the module, not just the one you wanted to test.
+- **Not observable** — it just happens silently whenever the module
+  happens to get imported, with no log line tied to a specific lifecycle
+  event.
+- **A pattern already solved by the `startup` callback.** See
+  `code_puppy/plugins/theme/register_callbacks.py`'s
+  `_apply_default_theme_on_first_run`, registered via
+  `register_callback("startup", _apply_default_theme_on_first_run)`.
+
+`namespace_skill_search` follows this pattern for its one piece of real
+setup work (turning off the built-in flat skill list the first time it
+ever runs): the config mutation lives in a plain function,
+`_maybe_disable_frontmatter()`, registered on `startup` — not executed
+as a bare statement in the module body. That function is directly
+callable and testable with mocked config, exactly like the theme
+plugin's equivalent.
+
+If you're doing a **one-time migration** (config flip, cache rebuild,
+etc.), also consider a dedicated marker config key to record "this
+plugin already ran its migration," independent of whatever value the
+thing you migrated currently holds — otherwise you can't distinguish
+"never ran yet" from "user changed it back after we ran." See
+`_MIGRATION_MARKER_KEY` in `namespace_skill_search/register_callbacks.py`
+for a worked example.
+
+---
+
+## Plugin structure convention
+
+```
+my_plugin/
+├── __init__.py              # docstring (can be minimal)
+├── register_callbacks.py    # entry point: register_callback() calls
+├── helpers.py               # optional: logic split out
+└── README.md                # optional: documentation
+```
+
+For a plugin that also ships a builtin skill via `register_skills`
+(rather than, or in addition to, tools/prompt fragments), see
+`code_puppy/plugins/code_puppy_agent/` (this skill's own plugin) or
+`namespace_skill_search`'s README for a fuller worked example of
+justifying design decisions in-repo rather than only in a PR
+description.

code_puppy_core_plugins/code_puppy_agent/SESSIONS_AND_HISTORY.md

@@ -0,0 +1,39 @@
+# Session & History System
+
+> Part of the `code-puppy-agent` skill. Read this when debugging context
+> window / compaction issues, or working with session save/load. See
+> `SKILL.md` for the overview and the full reference map.
+
+---
+
+## Message history
+
+Each `BaseAgent` maintains `_message_history` — a list of pydantic-ai
+`ModelMessage` objects (alternating `ModelRequest`/`ModelResponse`).
+History is the conversation context sent to the LLM on each turn.
+
+## Context window management
+
+When the conversation grows too large:
+1. **Token estimation** (`_history.py`) — estimates tokens per message
+2. **Compaction** (`_compaction.py`) — summarizes older messages using a
+   dedicated summarization agent, preserving recent messages
+3. **Protected tokens** — the most recent N tokens are never compacted
+   (configurable via `protected_token_count`)
+
+## Session persistence
+
+Sessions are saved as pickle files in the state directory:
+- `session_storage.py` handles serialization
+- `/save <name>` and `/load <name>` commands
+- Auto-save on exit
+
+## Useful history commands
+
+| Command | Effect |
+|---------|--------|
+| `/save <name>` | Save current session |
+| `/load <name>` | Load a saved session |
+| `/pop [N]` | Remove N most recent messages |
+| `/truncate <N>` | Keep only N most recent messages |
+| `/prune` | Interactive context pruning UI |

code_puppy_core_plugins/code_puppy_agent/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: code-puppy-agent
+description: How Code Puppy itself is built — its internal architecture, structure, codebase layout, and source modules. Explains agents, tools, the plugin/callback hook system, models, MCP, sessions and history/context windows, skills (including skill namespaces for large catalogs), slash commands, config, messaging/UI, system-prompt assembly, and i18n. Activate for ANY question about how Code Puppy works internally, why it behaves a certain way, where something lives in the code, how a feature is implemented, or how to navigate, debug, or extend the codebase (add a tool, agent, plugin, command, skill, model, or MCP server).
+version: "2.0"
+author: code-puppy
+tags:
+  - code-puppy
+  - architecture
+  - structure
+  - internals
+  - codebase
+  - source
+  - how-it-works
+  - self-awareness
+  - agents
+  - tools
+  - plugins
+  - hooks
+  - callbacks
+  - models
+  - mcp
+  - sessions
+  - history
+  - skills
+  - namespaces
+  - commands
+  - config
+  - messaging
+  - i18n
+  - extend
+  - debug
+  - reference
+---
+
+# Code Puppy — Architecture & Internals
+
+This skill is a **self-awareness document**. When activated it teaches the
+LLM how Code Puppy is structured under the hood so it can navigate the
+codebase, debug issues, and extend the product without guessing.
+
+> **Philosophy:** Code Puppy is plugin-first. Nearly all new functionality
+> should be a plugin under `code_puppy/plugins/` that hooks into core via
+> `code_puppy/callbacks.py`. Don't edit `code_puppy/command_line/` or core
+> agent files unless a hook genuinely doesn't exist.
+
+This skill is split across multiple files so activating it doesn't force
+the full ~30KB of internals into context on every use — this SKILL.md is
+the index. **Read the reference file for the topic you actually need**;
+each one is self-contained and cites real file paths so you can jump
+straight to source. All reference files are plain repo paths under
+`code_puppy/plugins/code_puppy_agent/` — read them with `read_file`.
+
+---
+
+## Layered Architecture
+
+```
+┌──────────────────────────────────────────────────┐
+│  TUI / CLI  (command_line/, tui/)                 │
+│    user input → slash commands → agent dispatch   │
+├──────────────────────────────────────────────────┤
+│  Agent Layer  (agents/)                           │
+│    BaseAgent → system prompt, tools, history      │
+│    _builder, _runtime, _compaction, _history      │
+├──────────────────────────────────────────────────┤
+│  Tool Layer  (tools/)                             │
+│    TOOL_REGISTRY → register_tools_for_agent()     │
+├──────────────────────────────────────────────────┤
+│  Plugin Layer  (plugins/, callbacks.py)           │
+│    register_callback("hook", fn) at import time   │
+├──────────────────────────────────────────────────┤
+│  Model Layer  (model_factory.py, config.py)       │
+│    ModelFactory → pydantic-ai Model objects       │
+├──────────────────────────────────────────────────┤
+│  pydantic-ai  (external)                          │
+│    Agent.run(), streaming, tool schemas           │
+└──────────────────────────────────────────────────┘
+```
+
+The TUI collects user input. It delegates to the **agent manager** which
+loads the current agent. The agent builds a pydantic-ai `Agent` with a
+system prompt + tool set, then `run_with_mcp()` streams the LLM response.
+Plugins hook into every stage via callbacks.
+
+---
+
+## Reference Map
+
+| File | Read this for |
+|------|----------------|
+| `AGENTS_AND_TOOLS.md` | How agents are structured/discovered (Python, JSON, plugin agents, precedence). How tools get registered and wired to an agent. Async-tool blocking-I/O gotcha. |
+| `PLUGINS_AND_CALLBACKS.md` | Plugin discovery tiers, the full callback hook table, a minimal plugin example, and **two hook-system gotchas** (`get_model_system_prompt` last-write-wins; don't do real work at import time) worth reading before writing any new plugin. |
+| `MODELS_AND_MCP.md` | ModelFactory, model config precedence, model types. MCP server lifecycle, agent bindings, and a known gap (MCP servers can't yet provide skills). |
+| `SESSIONS_AND_HISTORY.md` | Message history, context-window compaction, session save/load commands. |
+| `SKILLS_SYSTEM.md` | Skill discovery/activation, bundled-resource-file gotcha for plugin-registered skills, and **skill namespaces** — how `namespace_skill_search` groups large skill catalogs and replaces the flat prompt list. |
+| `SYSTEM_PROMPT_CONFIG_AND_I18N.md` | Exact system-prompt assembly order (which layer skills/rules/patches land in), `puppy.cfg` + key directories, the messaging bus, and an i18n quick-reference (full guide: `docs/I18N.md`). |
+
+Don't guess which file has what you need — the table above is exhaustive
+for this skill's scope. If a question doesn't map cleanly to one row, it's
+probably answered by combining two (e.g. "why did my plugin's prompt
+addition get silently dropped" is a `PLUGINS_AND_CALLBACKS.md` +
+`SYSTEM_PROMPT_CONFIG_AND_I18N.md` question).
+
+---
+
+## Development Conventions
+
+### Golden rules
+
+1. **Plugins over core** — if a callback hook exists, use it. Don't edit
+   `command_line/` or core agent files.
+2. **One `register_callbacks.py` per plugin** — register at module scope.
+3. **600-line hard cap** per file — split into submodules. (This very
+   skill was split for exactly this reason — it was 632 lines as one file.)
+4. **Fail gracefully** — plugins must never crash the app. Wrap external
+   calls in try/except.
+5. **Return `None`** from hooks/commands you don't own.
+6. **Always run linters** — `ruff check --fix`, `ruff format .`
+7. **Wrap user-facing strings** in `t()`/`ngettext` (see
+   `SYSTEM_PROMPT_CONFIG_AND_I18N.md`) — don't hardcode English display
+   text. Model-facing system prompt content is explicitly exempt.
+8. **Never allow a Claude co-author commit.**
+
+### Plugin structure
+
+```
+my_plugin/
+├── __init__.py              # docstring (can be minimal)
+├── register_callbacks.py    # entry point: register_callback() calls
+├── helpers.py               # optional: logic split out
+└── README.md                # optional: documentation
+```
+
+### Zen of Code Puppy
+
+- Simple is better than complex.
+- Flat is better than nested.
+- If a hook exists for it, use it.
+- Files should be readable in one sitting.
+- The plugin system is the API surface; the core is the engine.
+
+---
+
+## Quick Reference: Key File Map
+
+| File | Responsibility |
+|------|---------------|
+| `agents/base_agent.py` | Abstract agent base — thin conductor |
+| `agents/_builder.py` | Builds pydantic-ai Agent + MCP wiring |
+| `agents/_runtime.py` | `run_with_mcp()` — streaming, retries, cancellation |
+| `agents/_compaction.py` | Context summarization |
+| `agents/agent_manager.py` | Agent registry, switching, discovery |
+| `agents/json_agent.py` | JSON-config agent loader |
+| `tools/__init__.py` | `TOOL_REGISTRY`, `register_tools_for_agent()` |
+| `plugins/__init__.py` | Plugin loader (builtin → user → project) |
+| `callbacks.py` | Hook engine — 45+ phases |
+| `config.py` | Config read/write, directories, model settings |
+| `model_factory.py` | Model-name → pydantic-ai Model |
+| `mcp_/manager.py` | MCP server lifecycle |
+| `session_storage.py` | Session pickle save/load |
+| `plugins/agent_skills/` | Skills discovery, activation, UI |
+| `plugins/namespace_skill_search/` | Namespace grouping + on-demand browse tool for large skill catalogs |
+| `i18n/` | Internationalization: catalogs, `t()`/`ngettext`, locale detection, formatting |
+| `i18n/locales/*.json` | Message catalogs (source of truth: `en-US.json`) |
+| `pydantic_patches.py` | Startup monkey-patches (clipboard fix, etc.) |
+
+---
+
+## When to use this skill
+
+Activate this skill when you need to:
+- Understand **how a feature works internally** before modifying it
+- **Create a new plugin** and need to know which hooks to use
+- **Debug** an agent, tool, model, skill, or MCP issue
+- **Navigate the codebase** and need to find the right file
+- **Extend Code Puppy** with custom tools, agents, skills, or commands
+
+Then read the specific reference file(s) from the map above — don't try
+to hold all six in context at once unless the question is genuinely
+that broad.