diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f1f09b3..4eab6f4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -25,5 +25,15 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      # The faster/mdx-rs pipeline only accepts bracketed admonition titles
+      # (:::tip[Title]). The legacy space form (:::tip Title) silently renders
+      # as literal ":::" text, so fail the build if any slip in.
+      - name: Lint admonition syntax
+        run: |
+          if grep -rnE '^:::(note|tip|info|warning|danger|caution)[ \t]+' docs; then
+            echo "::error::Space-separated admonition titles found above. Use bracket syntax, e.g. :::tip[Title]"
+            exit 1
+          fi
+
       - name: Build site
         run: npm run build
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d2966ff
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,30 @@
+# NeatContext documentation
+
+Docusaurus 3 site (docs-only mode) for **NeatContext**, deployed to
+docs.neatcontext.com via GitHub Pages. Docs live in `docs/` as `.md` files;
+config is `docusaurus.config.ts`.
+
+## Admonitions: always use bracket titles
+
+This site runs the **faster build pipeline** (`future.v4: true` +
+`@docusaurus/faster`), which parses MDX with the Rust `mdx-rs` engine. That
+parser only recognizes the canonical directive-label syntax for admonition
+titles:
+
+```md
+:::tip[Quick hands-on demo]
+Content here.
+:::
+```
+
+The legacy space-separated form `:::tip Quick hands-on demo` is **not**
+recognized — it silently renders as a literal `:::` paragraph instead of a
+callout box. Title-less admonitions (`:::note`) are fine either way.
+
+So: **when an admonition has a title, wrap it in `[...]`.** CI enforces this
+(see the "Lint admonition syntax" step in `.github/workflows/ci.yml`).
+
+## Local commands
+
+- `npm run start` — dev server with hot reload.
+- `npm run build` — production build into `build/` (what CI and deploy run).