Add Directus Docs AI assistant

[bryantgillespie]

Changes

• Adds the Directus Docs AI assistant UI, chat history, search-palette handoff, page-context prompts, feedback capture, and OpenRouter streaming endpoint.
• Adds assistant admission hardening: abuse gate, burst and daily limits, request/message bounding, tool binding limits, secret redaction, PostHog AI telemetry, and dev-only limit reset/status endpoints.
• Consolidates burst-style rate limiting into a shared Store-backed module, wraps docs API limits in one module, and documents the rate-limit language/ADR.
• Adds focused coverage for assistant admission, request context, tool binding, rate limits, docs API limits, and assistant client message transitions.
• Splits contributor setup into CONTRIBUTING.md and adds AI Assistant setup/env documentation while keeping README public-facing.

Potential Risks

• Requires OPENROUTER_API_KEY to enable the assistant and Upstash/Redis env vars for cross-instance burst and daily limits in production.
• pnpm build is still blocked by existing prerender 404/content/icon issues unrelated to the assistant changes.

Review Notes

• Focused test run passed: pnpm exec vitest run modules/assistant/index.test.ts modules/assistant/runtime/composables/useAssistant.test.ts modules/assistant/runtime/server/utils/admit.test.ts modules/assistant/runtime/server/utils/abuse-gate.test.ts modules/assistant/runtime/server/utils/bind-tools.test.ts modules/assistant/runtime/server/utils/rate-limit.test.ts modules/assistant/runtime/server/utils/request-context.test.ts server/utils/rate-limit.test.ts server/utils/docs-api-limit.test.ts.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 3, 2026 1:36am

[Copilot]

Pull request overview

This PR introduces an in-site “Directus Docs AI assistant” (UI + server endpoint) and hardens assistant admission/rate-limiting, while also consolidating burst-style rate limiting into a shared store-backed module and updating contributor documentation accordingly.

Changes:

• Adds an AI assistant chat UI (split panel, floating input, chat history, tool-call display, feedback capture) and a Nitro streaming endpoint backed by OpenRouter.
• Adds assistant admission hardening (abuse gate, burst + daily limits, request/message bounding, tool binding limits, redaction, PostHog AI telemetry, dev-only status/reset helpers).
• Replaces ad-hoc per-endpoint in-memory limiters with a shared server/utils/rate-limit.ts module plus a docs API wrapper (enforceDocsApiLimit), and documents the decisions via ADR/CONTEXT updates.

Reviewed changes

Copilot reviewed 63 out of 65 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/server/get-directus-file.test.ts	Adds a test file (currently duplicates existing sliceUtf8 coverage).
server/utils/rate-limit.ts	Introduces a shared fixed-window limiter with pluggable Memory/Upstash stores.
server/utils/rate-limit.test.ts	Adds unit tests for shared limiter verdicts and store-failure policies.
server/utils/mcp-rate-limit.ts	Removes the legacy MCP in-memory limiter implementation.
server/utils/docs-api-rate-limit.ts	Removes the legacy docs API in-memory limiter implementation.
server/utils/docs-api-limit.ts	Adds a single docs API limiter wrapper that throws 429s with Retry-After.
server/utils/docs-api-limit.test.ts	Adds tests for docs API limiter behavior and fail-open policy.
server/mcp/tools/search-directus-code.ts	Switches MCP tool rate limiting to the shared limiter module.
server/mcp/tools/get-directus-page.ts	Adds an MCP tool to fetch directus.com marketing pages as markdown (chunked).
server/api/docs/search.get.ts	Replaces inline docs API rate limiting with enforceDocsApiLimit.
server/api/docs/index.get.ts	Replaces inline docs API rate limiting with enforceDocsApiLimit.
server/api/docs/get.get.ts	Replaces inline docs API rate limiting with enforceDocsApiLimit.
scripts/test-abuse-gate.sh	Adds a curl script to exercise the abuse-gate/admission path locally.
README.md	Moves detailed contributor/setup docs into CONTRIBUTING and adds assistant pointers.
package.json	Adds assistant/telemetry/UI dependencies (AI SDK, OpenRouter, Upstash, split panel, etc.).
nuxt.config.ts	Registers the assistant Nuxt module, adds split-panel CSS, adds ph icon collection.
modules/posthog/runtime/server/capture.ts	Adds server-side PostHog capture helper for assistant telemetry.
modules/posthog/runtime/plugins/posthog.server.ts	Updates server PostHog plugin cookie handling and feature-flag loading behavior.
modules/assistant/runtime/utils/messages.ts	Adds message compaction + tool-call extraction helpers for UI + requests.
modules/assistant/runtime/utils/easter-egg.ts	Adds a small easter-egg prompt handler and response builder.
modules/assistant/runtime/types.ts	Adds assistant runtime types for FAQ configuration.
modules/assistant/runtime/strings.ts	Adds assistant UI strings/constants.
modules/assistant/runtime/server/utils/stream.ts	Adds OpenRouter streaming + tool-call step handling + idle abort + telemetry flush.
modules/assistant/runtime/server/utils/sanitize.ts	Adds input bounds + redaction utilities for assistant requests/tool results.
modules/assistant/runtime/server/utils/request-context.ts	Builds system prompt + page/prefs/session context and compacts model messages.
modules/assistant/runtime/server/utils/request-context.test.ts	Adds tests for request-context derivation/sanitization/compaction.
modules/assistant/runtime/server/utils/rate-limit.ts	Implements assistant daily-limits (KV/memory) + overrides + status/reset helpers.
modules/assistant/runtime/server/utils/rate-limit.test.ts	Adds tests for daily limiter (IPv6 prefixing, degrade/deny paths, KV errors).
modules/assistant/runtime/server/utils/profiles.ts	Adds assistant “normal/degraded” limit profiles (tokens/steps/message limits).
modules/assistant/runtime/server/utils/is-dev-context.ts	Adds environment detection helpers for dev-only endpoints.
modules/assistant/runtime/server/utils/fingerprint.ts	Adds request fingerprinting + PostHog distinct-id derivation.
modules/assistant/runtime/server/utils/bind-tools.ts	Binds MCP tools into AI SDK tools with schema validation, budgets, truncation, redaction.
modules/assistant/runtime/server/utils/bind-tools.test.ts	Adds tests for tool binding, budgets, truncation, and redaction.
modules/assistant/runtime/server/utils/admit.ts	Implements assistant admission pipeline (gate → burst → parse → daily) and JSON rejects.
modules/assistant/runtime/server/utils/admit.test.ts	Adds tests ensuring admission ordering and correct early-reject behavior.
modules/assistant/runtime/server/utils/abuse-gate.ts	Adds abuse gate logic (origin/referer/fetch headers/UA) for trusted/suspicious/blocked.
modules/assistant/runtime/server/utils/abuse-gate.test.ts	Adds tests for abuse-gate verdicts across dev/prod/preview scenarios.
modules/assistant/runtime/server/plugins/posthog-otel.ts	Adds OTel + PostHog AI span processor with attribute/event redaction.
modules/assistant/runtime/server/api/chat.post.ts	Adds streaming chat endpoint that admits requests, builds context, binds tools, streams model output.
modules/assistant/runtime/server/api/test/reset-limits.post.ts	Adds dev-only endpoint to reset assistant daily limits (optional token).
modules/assistant/runtime/server/api/test/assistant-status.get.ts	Adds dev-only endpoint to inspect assistant limiter status for current fingerprint/IP.
modules/assistant/runtime/composables/useHighlighter.ts	Adds Shiki core highlighter loader for assistant markdown/code rendering.
modules/assistant/runtime/composables/useAssistantHistory.ts	Adds localStorage-backed conversation history persistence + compaction.
modules/assistant/runtime/composables/useAssistant.ts	Adds main client assistant state machine (open/close, history transitions, headers, easter egg).
modules/assistant/runtime/composables/useAssistant.test.ts	Adds tests for message transitions, pending initial messages, easter-egg cancellation, etc.
modules/assistant/runtime/components/AssistantSlashes.vue	Adds a small animated loading glyph with reduced-motion support.
modules/assistant/runtime/components/AssistantPreStream.vue	Adds Shiki-stream rendering for code blocks inside assistant markdown.
modules/assistant/runtime/components/AssistantMessageFeedback.vue	Adds thumbs up/down feedback + optional follow-up survey render + copy response action.
modules/assistant/runtime/components/AssistantLoading.vue	Adds assistant loading UI with rotating phrases + tool-call display.
modules/assistant/runtime/components/AssistantFloatingInput.vue	Adds a floating “Ask AI” input for docs routes with shortcut focus handling.
modules/assistant/runtime/components/AssistantChatBody.vue	Adds the assistant panel UI (messages, history view, tool-call display, prompt, controls).
modules/assistant/runtime/components/AssistantChat.vue	Adds header button to toggle assistant.
modules/assistant/prompts/system-prompt.ts	Adds a system prompt defining assistant scope/tool usage/safety/refusal rules.
modules/assistant/index.ts	Adds Nuxt module wiring (runtime config, server routes/plugins, components/imports).
modules/assistant/index.test.ts	Adds tests for assistant enablement gating (API key + kill switch).
docs/adr/0001-shared-rate-limit-module.md	Documents the shared rate limit module decision and rationale.
CONTRIBUTING.md	Adds contributor setup and detailed assistant configuration/environment docs.
CONTEXT.md	Adds shared “domain language” terminology (rate limiting + assistant state/transition terms).
content/licensing/1.overview.md	Trims trailing whitespace in licensing docs content.
content/index.md	Updates docs index description copy.
app/components/DocsSearchPalette.vue	Adds “Ask AI” handoff from search palette and a meta+enter shortcut.
app/components/DocsHeader.vue	Adds assistant toggle button in docs header when enabled.
app/app.vue	Adds split-panel layout to host assistant alongside docs, plus persisted panel sizing.
app/app.config.ts	Adds assistant FAQ seed content and container-query overrides for narrow-pane layouts.
.env.example	Documents assistant-related environment variables and recommended KV settings.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[LZylstra]

Few minor things, otherwise looks great. Had some fun with it.. tried to talk it into giving me a Directus discount but it wouldn't