docs: add INSTRUCTION.md — canonical LLM onboarding guide

Primary onboarding doc for any connected agent: what AgentDrive is,
why/how to use it, session workflow, user-facing explanations, and
golden rules. Mintlify mirror + README/docs cross-links.

Author: PabloTheThinker

CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to this project are documented here. The product is
 
 ## Unreleased
 
+### Added — INSTRUCTION.md for LLM onboarding (2026-06-18)
+
+- **`INSTRUCTION.md`** (repo root) — canonical onboarding for any AI agent: what AgentDrive is, why to use it, how it works (capability funnel + 6-step loop), session workflow, anti-patterns, how to explain AgentDrive to the user (elevator pitch, analogies, FAQ), golden rules, and a full session example.
+- **`docs/INSTRUCTION.md`** — Mintlify mirror with frontmatter for docs site nav.
+- **`README.md`** — points models to INSTRUCTION.md before FOR_AI_MODELS.md.
+- **`docs/FOR_AI_MODELS.md`** · **`docs/ai-models/quickstart.md`** — cross-links to INSTRUCTION as entry point.
+- **`docs/docs.json`** — INSTRUCTION added to "Using with AI Models" nav; fixed trailing comma in redirects.
+
 ### Fixed — Repo-wide consistency audit (2026-06-18)
 
 - **Drive path unification (P0)** — removed duplicate `SwarmDriveManager` from `drive.py`; `get_default_drive()` and `create_scoped_pool()` now use `swarm_manager.get_or_create_pool()` → shared `swarms/<id>/drive/` (aligns MCP, memory bank, Experience Graph).

INSTRUCTION.md

@@ -8,7 +8,7 @@
 
 AgentDrive gives any capable model — Grok, Claude, Cursor, Continue, Ollama, custom harnesses — a **structural memory system** that grows from its own decisions. Not a vector store. Not a chat-memory SaaS. A living substrate where reasoning traces, patterns, skills, and knowledge compound across sessions instead of resetting every time you open a new chat.
 
-> **For AI models:** Your first MCP action is always `agentdrive_mcp_catalog()`. Then read **[docs/FOR_AI_MODELS.md](docs/FOR_AI_MODELS.md)** — the canonical rules for working inside AgentDrive.
+> **For AI models:** Your first MCP action is always `agentdrive_mcp_catalog()`. Then read **[INSTRUCTION.md](INSTRUCTION.md)** — what AgentDrive is, how to use it, and how to explain it to your user. Deep reference: **[docs/FOR_AI_MODELS.md](docs/FOR_AI_MODELS.md)**.
 
 ---
 
@@ -199,7 +199,8 @@ Guides: [docs/AD_GRID_JOIN.md](docs/AD_GRID_JOIN.md) · [docs/AD_GRID_VISION.md]
 
 | Doc | Purpose |
 |-----|---------|
-| [FOR_AI_MODELS.md](docs/FOR_AI_MODELS.md) | Canonical rules for any connected model |
+| [INSTRUCTION.md](INSTRUCTION.md) | **Start here (LLMs)** — what, why, how, explain to user |
+| [FOR_AI_MODELS.md](docs/FOR_AI_MODELS.md) | Deep reference rules for any connected model |
 | [CAPABILITY_FUNNEL.md](docs/CAPABILITY_FUNNEL.md) | How intelligence compounds (single mental model) |
 | [MEMORY_BANK.md](docs/MEMORY_BANK.md) | Deep memory layer — vault/topic, search, anchor |
 | [MULTIVERSE_COGNITION.md](docs/MULTIVERSE_COGNITION.md) | Parallel timeline decisions |

README.md

@@ -1,9 +1,10 @@
 # AgentDrive for AI Models (LLM Onboarding Guide)
 
-**This is the canonical "rules for the AI" document.**\
-Give this file (or keep it in context) to any model — frontier (Grok, Claude, Cursor) or local (via Continue, Ollama, LM Studio, direct MCP, etc.) — that will use AgentDrive.
+**Start with [INSTRUCTION.md](../INSTRUCTION.md)** — what AgentDrive is, why to use it, how it works, session workflow, and how to explain it to your user.
 
-Read this once at the start of any serious session. It will make you far more effective.
+**This document is the deep reference** — extended rules, Experience Graph tool tables, AD-Grid inhabitant guide, and anti-patterns. Give both files (or keep them in context) to any model — frontier (Grok, Claude, Cursor) or local (via Continue, Ollama, LM Studio, direct MCP, etc.) — that will use AgentDrive.
+
+Read INSTRUCTION.md once at session start; consult this file when you need detail on a specific surface.
 
 ---