diff --git a/.ai/README.md b/.ai/README.md
deleted file mode 100644
index 49fa6dfbba2..00000000000
--- a/.ai/README.md
+++ /dev/null
@@ -1 +0,0 @@
-This folder contains reference documentation that is primarily intended for AI agents working in this codebase.
\ No newline at end of file
diff --git a/.ai/embeds/IMPLEMENTATION.md b/docs/specs/4-architecture/features/012-embeds/IMPLEMENTATION.md
similarity index 100%
rename from .ai/embeds/IMPLEMENTATION.md
rename to docs/specs/4-architecture/features/012-embeds/IMPLEMENTATION.md
diff --git a/.ai/embeds/LAYOUT_ALGORITHMS.md b/docs/specs/4-architecture/features/012-embeds/LAYOUT_ALGORITHMS.md
similarity index 100%
rename from .ai/embeds/LAYOUT_ALGORITHMS.md
rename to docs/specs/4-architecture/features/012-embeds/LAYOUT_ALGORITHMS.md
diff --git a/.ai/embeds/README.md b/docs/specs/4-architecture/features/012-embeds/README.md
similarity index 100%
rename from .ai/embeds/README.md
rename to docs/specs/4-architecture/features/012-embeds/README.md
diff --git a/.ai/embeds/SPECIFICATION.md b/docs/specs/4-architecture/features/012-embeds/SPECIFICATION.md
similarity index 100%
rename from .ai/embeds/SPECIFICATION.md
rename to docs/specs/4-architecture/features/012-embeds/SPECIFICATION.md
diff --git a/.ai/embeds/demo.html b/docs/specs/4-architecture/features/012-embeds/demo.html
similarity index 100%
rename from .ai/embeds/demo.html
rename to docs/specs/4-architecture/features/012-embeds/demo.html