docs: add @ file linking and .claude/rules/ guidance to plugin docs

AGENTS.md

@@ -150,6 +150,45 @@ Choose the implementation language based on complexity:
 
 **Key principle**: Simplicity beats sophistication. Use the simplest tool that solves the problem correctly.
 
+## File Linking & Memory Organization
+
+### `@` File Imports
+
+When linking to other files in plugin documentation or any rules file,
+**always use `@path/to/file` syntax** — never markdown links `[text](path)`.
+The `@` syntax is the official Claude Code import: it actually loads the
+file's content into context. Markdown links are inert text.
+
+```md
+# ✅ Correct — imports the file's content
+See @docs/setup.md for environment setup.
+
+# ❌ Wrong — just a text reference, nothing is loaded
+See [Setup](docs/setup.md) for environment setup.
+```
+
+### `.claude/rules/` for Always-Active Rules
+
+Place rules that should always be loaded into `.claude/rules/` — Claude Code
+auto-loads all `.md` files there with the same priority as the project's primary
+documentation. No `@` import needed.
+
+Rules files support YAML frontmatter to scope them to specific file patterns:
+
+```md
+---
+paths:
+  - "hooks/**/*.py"
+---
+# Hook Script Rules
+- All hooks must exit 0 (allow) or 2 (block)
+```
+
+Rules without `paths` frontmatter apply unconditionally. Use `.claude/rules/`
+over `@` imports when rules should always be active, not just when a specific
+file is referenced. Symlinks in `.claude/rules/` are supported — use them to
+share rules across repos.
+
 ## CI/CD
 
 ### Workflows