refactor: move agent installation docs to separate file

README.adoc

@@ -25,77 +25,9 @@ Browse the full catalog of 60+ semantic anchors with interactive visualization,
 🔄 *Consistency*:: Ensure LLMs interpret concepts as intended
 🧠 *Depth*:: Activate multiple interconnected concepts with a single term
 
-== 🤖 Installation for Coding Agents
+== 🤖 Using Anchors with Local LLMs
 
-For the widest compatibility, install anchors into a project-level `AGENTS.md` first, then add agent-specific mirrors only where the official docs say they help.
-
-=== Portable Baseline (Recommended)
-
-Use the bundled installer to inject a managed anchor block into the best available project instruction file. If none exists yet, it creates `AGENTS.md`.
-
-First, copy the template and fill in your chosen anchors:
-
-[source,bash]
-----
-cp skill/semantic-anchor-onboarding/assets/templates/anchor-block.md my-anchors.md
-# Edit my-anchors.md — replace {{PRIMARY_ANCHOR_*}} / {{PRIMARY_EXPLAINER_*}} placeholders
-----
-
-Then run the installer:
-
-[source,bash]
-----
-./skill/semantic-anchor-onboarding/scripts/install.sh \
-  --source my-anchors.md \
-  --target-dir . \
-  --scope project
-----
-
-=== link:https://openai.com/codex/[Codex]
-Codex supports `AGENTS.md` for repository instructions.
-
-* Keep shared semantic anchors in `AGENTS.md`.
-* Use this as the canonical file when you want the same anchors to work across multiple agents.
-
-=== link:https://docs.anthropic.com/en/docs/claude-code/memory[Claude Code]
-Claude Code uses `CLAUDE.md` for project memory and also supports hooks.
-
-* *Static Context*: Mirror the same anchor block into `CLAUDE.md` if Claude Code is a target.
-* *Optional Hook*: If you want Claude to re-inject the managed block at session start, run:
-+
-[source,bash]
-----
-./skill/semantic-anchor-onboarding/scripts/install.sh \
-  --source my-anchors.md \
-  --target-dir . \
-  --scope project \
-  --claude-hook
-----
-
-=== link:https://github.com/google-gemini/gemini-cli[Gemini CLI]
-Current Gemini CLI docs center on `GEMINI.md` and configurable context file names.
-
-* *Native Gemini Context*: Mirror your selected anchors into `GEMINI.md`.
-* *Shared Cross-Agent Context*: Set Gemini's `context.fileName` to `AGENTS.md` if you want one portable project file.
-* Current Gemini CLI docs no longer describe `.gemini/skills/` or `gemini skills link` as the primary path for always-on instructions.
-
-=== link:https://docs.cursor.com/en/context/rules[Cursor]
-Cursor supports `AGENTS.md` and project rules in `.cursor/rules/*.mdc`.
-
-* Use `AGENTS.md` for shared, repo-wide semantic anchors.
-* Use `.cursor/rules/*.mdc` only when you need path-scoped or feature-scoped behavior inside Cursor itself.
-
-=== link:https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions[GitHub Copilot]
-Copilot supports repository instruction files, and its coding agent can also consume `AGENTS.md`.
-
-* Create or update `.github/copilot-instructions.md` when you want the same anchors to influence Copilot chat and review flows.
-* Keep `AGENTS.md` as the shared baseline if other coding agents are also in use.
-
-=== link:https://docs.windsurf.com/windsurf/cascade/memories[Windsurf]
-Windsurf supports `AGENTS.md` alongside Windsurf Rules.
-
-* Use `AGENTS.md` for portable project context shared with other agents.
-* Use Windsurf Rules only when you need editor-specific or scoped behavior.
+Most frontier LLMs already recognize semantic anchors from their training data. However, if you use local or smaller models (Llama, Mistral, Phi, etc.) that may not know all anchors, you can inject explicit definitions into your project's agent instruction files. See the link:docs/agent-installation.adoc[Agent Installation Guide] for setup instructions covering Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot, and Windsurf.
 
 == Quality Criteria
 

README.md

@@ -34,57 +34,9 @@ Semantic anchors are **well-defined terms, methodologies, or frameworks** that a
 - **Consistency** - Ensure LLMs interpret concepts as the community intends
 - **Context Compression** - Convey rich context concisely
 
-## 🤖 Installation for Coding Agents
+## 🤖 Using Anchors with Local LLMs
 
-For the widest compatibility, install anchors into a project-level `AGENTS.md` first, then add agent-specific mirrors only where the official docs say they help.
-
-### Portable Baseline (Recommended)
-
-Use the bundled installer to inject a managed anchor block into the best available project instruction file. If none exists yet, it creates `AGENTS.md`.
-
-First, copy the template and fill in your chosen anchors:
-
-```bash
-cp skill/semantic-anchor-onboarding/assets/templates/anchor-block.md my-anchors.md
-# Edit my-anchors.md — replace {{PRIMARY_ANCHOR_*}} / {{PRIMARY_EXPLAINER_*}} placeholders
-```
-
-Then run the installer:
-
-```bash
-./skill/semantic-anchor-onboarding/scripts/install.sh \
-  --source my-anchors.md \
-  --target-dir . \
-  --scope project
-```
-
-### [Codex](https://openai.com/codex/)
-Codex supports `AGENTS.md` for repository instructions.
-- Keep shared semantic anchors in `AGENTS.md`.
-- Use this as the canonical file when you want the same anchors to work across multiple agents.
-
-### [Claude Code](https://docs.anthropic.com/en/docs/claude-code/memory)
-Claude Code uses `CLAUDE.md` for project memory and also supports hooks.
-- **Static Context:** Mirror the same anchor block into `CLAUDE.md` if Claude Code is a target.
-- **Optional Hook:** If you want Claude to re-inject the managed block at session start, run:
-  ```bash
-  ./skill/semantic-anchor-onboarding/scripts/install.sh \
-    --source my-anchors.md \
-    --target-dir . \
-    --scope project \
-    --claude-hook
-  ```
-
-### [Gemini CLI](https://github.com/google-gemini/gemini-cli)
-Current Gemini CLI docs center on `GEMINI.md` and configurable context file names.
-- **Native Gemini Context:** Mirror your selected anchors into `GEMINI.md`.
-- **Shared Cross-Agent Context:** Set Gemini's `context.fileName` to `AGENTS.md` if you want one portable project file.
-- Current Gemini CLI docs no longer describe `.gemini/skills/` or `gemini skills link` as the primary path for always-on instructions.
-
-### [Cursor](https://docs.cursor.com/en/context/rules)
-Cursor supports `AGENTS.md` and project rules in `.cursor/rules/*.mdc`.
-- Use `AGENTS.md` for shared, repo-wide semantic anchors.
-- Use `.cursor/rules/*.mdc` only when you need path-scoped or feature-scoped behavior inside Cursor itself.
+Most frontier LLMs already recognize semantic anchors from their training data. However, if you use local or smaller models (Llama, Mistral, Phi, etc.) that may not know all anchors, you can inject explicit definitions into your project's agent instruction files. See the [Agent Installation Guide](docs/agent-installation.adoc) for setup instructions covering Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot, and Windsurf.
 
 ## 📚 Content Structure
 

docs/agent-installation.adoc

@@ -0,0 +1,80 @@
+= Installing Semantic Anchors for Coding Agents
+:toc:
+
+== When Do You Need This?
+
+Most frontier LLMs (GPT-4, Claude, Gemini) already have semantic anchors in their training data -- saying "TDD, London School" or "Clean Architecture" is enough to activate the right concepts.
+
+However, *local or smaller LLMs* (Llama, Mistral, Phi, etc.) may not recognize all anchors reliably. For these models, you can inject explicit anchor definitions into your project's agent instruction files. This ensures consistent behavior regardless of the model's training data.
+
+== Portable Baseline (Recommended)
+
+For the widest compatibility, install anchors into a project-level `AGENTS.md` first, then add agent-specific mirrors only where the official docs say they help.
+
+Use the bundled installer to inject a managed anchor block into the best available project instruction file. If none exists yet, it creates `AGENTS.md`.
+
+First, copy the template and fill in your chosen anchors:
+
+[source,bash]
+----
+cp skill/semantic-anchor-onboarding/assets/templates/anchor-block.md my-anchors.md
+# Edit my-anchors.md — replace {{PRIMARY_ANCHOR_*}} / {{PRIMARY_EXPLAINER_*}} placeholders
+----
+
+Then run the installer:
+
+[source,bash]
+----
+./skill/semantic-anchor-onboarding/scripts/install.sh \
+  --source my-anchors.md \
+  --target-dir . \
+  --scope project
+----
+
+== Agent-Specific Setup
+
+=== link:https://openai.com/codex/[Codex]
+Codex supports `AGENTS.md` for repository instructions.
+
+* Keep shared semantic anchors in `AGENTS.md`.
+* Use this as the canonical file when you want the same anchors to work across multiple agents.
+
+=== link:https://docs.anthropic.com/en/docs/claude-code/memory[Claude Code]
+Claude Code uses `CLAUDE.md` for project memory and also supports hooks.
+
+* *Static Context*: Mirror the same anchor block into `CLAUDE.md` if Claude Code is a target.
+* *Optional Hook*: If you want Claude to re-inject the managed block at session start, run:
++
+[source,bash]
+----
+./skill/semantic-anchor-onboarding/scripts/install.sh \
+  --source my-anchors.md \
+  --target-dir . \
+  --scope project \
+  --claude-hook
+----
+
+=== link:https://github.com/google-gemini/gemini-cli[Gemini CLI]
+Current Gemini CLI docs center on `GEMINI.md` and configurable context file names.
+
+* *Native Gemini Context*: Mirror your selected anchors into `GEMINI.md`.
+* *Shared Cross-Agent Context*: Set Gemini's `context.fileName` to `AGENTS.md` if you want one portable project file.
+* Current Gemini CLI docs no longer describe `.gemini/skills/` or `gemini skills link` as the primary path for always-on instructions.
+
+=== link:https://docs.cursor.com/en/context/rules[Cursor]
+Cursor supports `AGENTS.md` and project rules in `.cursor/rules/*.mdc`.
+
+* Use `AGENTS.md` for shared, repo-wide semantic anchors.
+* Use `.cursor/rules/*.mdc` only when you need path-scoped or feature-scoped behavior inside Cursor itself.
+
+=== link:https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions[GitHub Copilot]
+Copilot supports repository instruction files, and its coding agent can also consume `AGENTS.md`.
+
+* Create or update `.github/copilot-instructions.md` when you want the same anchors to influence Copilot chat and review flows.
+* Keep `AGENTS.md` as the shared baseline if other coding agents are also in use.
+
+=== link:https://docs.windsurf.com/windsurf/cascade/memories[Windsurf]
+Windsurf supports `AGENTS.md` alongside Windsurf Rules.
+
+* Use `AGENTS.md` for portable project context shared with other agents.
+* Use Windsurf Rules only when you need editor-specific or scoped behavior.