docs: Add Meta-Boundary guide to clarify Application vs Tooling domains

conductor/product.md

@@ -6,6 +6,7 @@ To serve as an expert-level utility for personal developer use on small projects
 ## Architecture Reference
 For deep implementation details when planning or implementing tracks, consult `docs/` (last updated: 08e003a):
 - **[docs/guide_architecture.md](../docs/guide_architecture.md):** Threading model, event system, AI client, HITL mechanism
+- **[docs/guide_meta_boundary.md](../docs/guide_meta_boundary.md):** The critical distinction between the Application's Strict-HITL environment and the Meta-Tooling environment used to build it.
 - **[docs/guide_tools.md](../docs/guide_tools.md):** MCP Bridge, Hook API, ApiHookClient, shell runner
 - **[docs/guide_mma.md](../docs/guide_mma.md):** 4-tier orchestration, DAG engine, worker lifecycle
 - **[docs/guide_simulations.md](../docs/guide_simulations.md):** Test framework, mock provider, verification patterns

docs/Readme.md

@@ -9,6 +9,7 @@
 | Guide | Contents |
 |---|---|
 | [Architecture](guide_architecture.md) | Thread domains, cross-thread data structures, event system, application lifetime, task pipeline (producer-consumer), Execution Clutch (HITL), AI client multi-provider architecture, Anthropic/Gemini caching strategies, context refresh, comms logging, state machines |
+| [Meta-Boundary](guide_meta_boundary.md) | Explicit distinction between the Application's domain (Strict HITL) and the Meta-Tooling domain (autonomous agents), preventing feature bleed and safety bypasses via shared bridges like `mcp_client.py`. |
 | [Tools & IPC](guide_tools.md) | MCP Bridge 3-layer security model, all 26 native tool signatures, Hook API GET/POST endpoints with request/response formats, ApiHookClient method reference, `/api/ask` synchronous HITL protocol, session logging, shell runner |
 | [MMA Orchestration](guide_mma.md) | Ticket/Track/WorkerContext data structures, DAG engine (cycle detection, topological sort), ConductorEngine execution loop, Tier 2 ticket generation, Tier 3 worker lifecycle with context amnesia, Tier 4 QA integration, token firewalling, track state persistence |
 | [Simulations](guide_simulations.md) | `live_gui` pytest fixture lifecycle, `VerificationLogger`, process cleanup, Puppeteer pattern (8-stage MMA simulation), approval automation, mock provider (`mock_gemini_cli.py`) with JSON-L protocol, visual verification patterns, ASTParser (tree-sitter) vs summarizer (stdlib `ast`) |

docs/guide_meta_boundary.md

@@ -0,0 +1,34 @@
+# Meta-Boundary & Tooling Architecture
+
+## The Core Confusion
+This repository contains two distinct architectural domains that share similar concepts. It is very easy for an AI agent (or human) to confuse the two and cause "feature bleed" or safety bypasses.
+
+1. **The Application (`manual_slop`)**: The Dear PyGui application being developed. This is the product.
+2. **The Meta-Tooling**: The scripts, CLI wrappers, and MCP servers used by the human developer (and their external AI assistants like Gemini CLI or Claude Code) to *build* the Application.
+
+## Domain 1: The Application (`manual_slop`)
+- **Primary Files**: `gui_2.py`, `ai_client.py`, `multi_agent_conductor.py`, `dag_engine.py`.
+- **Purpose**: A local GUI for orchestrating AI. It manages its own internal AI sessions, tracks, and tickets.
+- **Safety Model**: **Strict Human-In-The-Loop (HITL)**. Any script or mutating action generated by the Application's internal AI *must* be approved by the human via a GUI modal (`pre_tool_callback`).
+- **Internal Tooling Control**: The tools available to the Application's internal AI are defined strictly by `manual_slop.toml` (`[agent.tools]`).
+
+## Domain 2: The Meta-Tooling
+- **Primary Files**: `scripts/mma_exec.py`, `scripts/tool_call.py`, `scripts/mcp_server.py`, `.gemini/`, `.claude/`.
+- **Purpose**: The external AI agents (you, reading this) used to write the code for the Application.
+- **Safety Model**: Driven by the external agent's own framework (e.g., Gemini CLI's auto-approval policies or Claude Code's permissions). These agents have their own sandboxing and do *not* use the Application's GUI for approval.
+- **Tooling Control**: These external agents use `mcp_client.py` natively to investigate and modify the `manual_slop` codebase (e.g., using `set_file_slice` to fix a bug).
+
+## The Overlap & Entropy Vector: `mcp_client.py`
+`mcp_client.py` is the shared bridge. 
+- It was originally written to give the Application's internal AI some read-only file context tools.
+- It was later expanded heavily with AST mutation tools (`py_update_definition`, `set_file_slice`) specifically so the **Meta-Tooling** (Gemini CLI) could perform surgical edits on the codebase.
+
+**The Danger**: Because `mcp_client.py` is shared, an AI working on the Application might accidentally expose these new Meta-Tooling mutation tools to the Application's internal AI *without* wiring them into the Application's strict GUI approval modal. This causes a critical safety bypass where the Application's AI can silently mutate files.
+
+## Guidelines for Future Tiers
+When you are implementing a Track, you must ask yourself:
+> *"Am I modifying the Application's behavior, or am I modifying the Meta-Tooling used to build it?"*
+
+1. **If adding a tool to `mcp_client.py`**: You must clarify if it is for the Meta-Tooling (us) or the Application (them). If it is for the Application, it MUST be gated behind `manual_slop.toml` toggles and wired to the GUI's `pre_tool_callback` for approval.
+2. **If editing `mma_exec.py`**: You are modifying the Meta-Tooling. The changes here affect how *you* (or your Tier 3 workers) operate. Ensure you respect token limits (Context Amnesia) and do not leak massive Application files into your own context window.
+3. **If editing `gui_2.py` or `ai_client.py`**: You are modifying the Application. Do not assume your external tool capabilities (like automatic file modification) apply here. Follow the Application's strict UX rules.