diff --git a/layers/nuxi/AGENTS.md b/layers/nuxi/AGENTS.md
new file mode 100644
index 000000000..0726fb851
--- /dev/null
+++ b/layers/nuxi/AGENTS.md
@@ -0,0 +1,20 @@
+# Nuxi layer
+
+Nuxi is an eve agent (`agent/`) plus the nuxt.com chat UI and APIs around it. Read `README.md` for setup, and the eve guide you need in `node_modules/eve/docs/` before changing agent code.
+
+## Layout
+
+- `agent/instructions.md`: the always-on prompt. Rules that apply to every turn: grounding, tools, citations, length, formatting.
+- `agent/instructions/*.ts`: blocks that apply only sometimes (date, surface and caller, web preview, admin). Each returns `null` when it doesn't apply. Memoize anything async per turn with `ctx.memo(ctx.turn?.id ?? null, …)`.
+- `agent/channels/`: who reaches Nuxi. `slack.ts` admits only full members of the home workspace, in every hook including `onAnswers`.
+- `agent/lib/identity/`: `resolveContext` is the one source of truth for surface, person and channel; `admin-mode.ts` decides admin mode per surface.
+- `agent/schedules/`: fixed cron workflows, plus `tasks.ts` for schedules people create in Slack.
+- `evals/`: `eve eval` checks for the reply rules, with tools stubbed.
+
+## Rules
+
+- The agent never imports Nuxt server code. It calls `server/api/internal/*` over HTTP with `INTERNAL_API_SECRET`.
+- Put company or ecosystem facts in tools, skills or connections, not in `instructions.md`.
+- Keep access checks in the channel hooks and again inside any tool that reads or writes sensitive data (`assertAdminMode`).
+- When you change reply behaviour in the instructions, add or update an eval under `evals/` and run it with `pnpm eval:nuxi
--repeat 3`.
+- Keep `evals/lib/slack.ts` in sync with `FOLLOWED_THREAD_GUIDANCE` in `agent/channels/slack.ts`.
diff --git a/layers/nuxi/README.md b/layers/nuxi/README.md
index e821e4518..f34123e0b 100644
--- a/layers/nuxi/README.md
+++ b/layers/nuxi/README.md
@@ -97,7 +97,36 @@ Auth uses the `nuxi-code` GitHub App on the `nuxt` org through the Vercel Connec
## Caller identity
-`agent/lib/identity/context.ts` resolves `Context.person` (id, name, bot flag) for every surface, and `agent/lib/identity/caller-instructions.ts` renders it into the always-on prompt so "who am I?" has an answer. Discord's display name (`global_name`) comes for free from the inbound message payload; the `@`-mention handle (`username`) is still kept on the auth context for future use, it's just not what the model sees. Slack's `app_mention`/`message` events only carry a user id — `channels/slack.ts` resolves the real name via `users.info` (`agent/lib/slack/api.ts`, cached 1h per user), which needs the **`users:read`** bot scope on top of the ones above; without it, Slack callers fall back to their user id.
+`agent/lib/identity/context.ts` resolves `Context.person` (id, name, bot flag) for every surface, and `agent/lib/identity/caller-instructions.ts` renders it into the always-on prompt so "who am I?" has an answer. Discord's display name (`global_name`) comes for free from the inbound message payload; the `@`-mention handle (`username`) is still kept on the auth context for future use, it's just not what the model sees. Slack's `app_mention`/`message` events only carry a user id: the Slack access check below looks the sender up with `users.info` and passes their display name along.
+
+## Slack access and threads
+
+Every Slack caller gets admin mode, so `agent/channels/slack.ts` admits only **full members of the home workspace**: `agent/lib/slack/members.ts` rejects guests (`is_restricted`, `is_ultra_restricted`), deactivated accounts and, when `SLACK_TEAM_ID` is set on the eve service, Slack Connect users from other workspaces. One `users.info` call (cached 10 minutes) gives both the decision and the caller's name. A failed lookup drops the message instead of letting it through. `onAnswers` applies the same check to approval and question clicks, so a guest can't approve a `coder` change in a member's thread. Other apps' bots still reach Nuxi from the home workspace but never get admin mode.
+
+Nuxi also **follows threads it's part of**: a reply without a mention in such a thread reaches it with `status: 'deferred'` and a guidance line, and Nuxi calls `no_reply` (`agent/tools/no_reply.ts`) when the reply is for someone else. Top-level messages still need a mention.
+
+Connector settings (`slack/nuxi` and `slack/nuxi-preview`, **Advanced**):
+
+- **Trigger Event Types:** `message.channels` and `message.groups`, for followed threads.
+- **Bot Scopes:** `users:read` (access check, required: without it nobody gets through), `channels:history` and `groups:history` (followed threads), `search:read.public` (`search_slack`), `channels:read`, `groups:read`, `im:read` and `mpim:read` (scheduled tasks check the destination conversation with `conversations.info` before each run, which needs the read scope of its type).
+
+`agent/tools/search_slack.ts` searches public channels with Slack's [Real-time Search API](https://docs.slack.dev/apis/web-api/real-time-search-api), on Slack and in admin mode only. It uses the per-message `action_token`, so it works only in a turn a mention or DM started.
+
+## Scheduled tasks
+
+`agent/schedules/tasks.ts` uses eve's experimental [dynamic schedules](https://eve.dev/docs/experimental/dynamic-schedules): people ask Nuxi in Slack for recurring or one-time tasks ("every Monday at 9am Paris time, post open showcase candidates here"), and it calls the deferred `schedule__tasks__*` tools. The destination channel, thread and creator come from the Slack session, never from the model. Each person manages only their own schedules, from Slack only, and creating or changing one asks for approval. Before each run, Nuxi checks the creator is still a full member and still in the channel, and disables the schedule otherwise. Under `eve dev` schedules never fire on their own; ask Nuxi to run one now (`invoke`). Fixed workflows stay in code, below.
+
+## Evals
+
+`evals/` checks the reply rules in `agent/instructions.md` against the real model, with tools such as `search_docs` replaced by fixed results (`allowToolStubs`, granted to the local `eve dev` caller only in `agent/channels/eve.ts`):
+
+```sh
+pnpm eval:nuxi # every eval
+pnpm eval:nuxi threads # one directory
+pnpm eval:nuxi --repeat 3 # results vary; repeat before trusting a prompt change
+```
+
+They need only AI Gateway access. When you change reply behaviour in the instructions, add or update a case.
## Data retention
diff --git a/layers/nuxi/agent/channels/discord.ts b/layers/nuxi/agent/channels/discord.ts
index f51f85093..ca2944f2e 100644
--- a/layers/nuxi/agent/channels/discord.ts
+++ b/layers/nuxi/agent/channels/discord.ts
@@ -286,7 +286,7 @@ function createDiscordBridge() {
}
// Discord-specific behaviour lives in the always-on prompt, keyed on the
- // principal (`lib/surface-instructions.ts`) — passing it as `context` here
+ // principal (`lib/identity/surface-instructions.ts`) — passing it as `context` here
// would prepend a fresh copy to history on every message.
await send(
toMessageContent(turn),
diff --git a/layers/nuxi/agent/channels/eve.ts b/layers/nuxi/agent/channels/eve.ts
index 2747d7985..476353aba 100644
--- a/layers/nuxi/agent/channels/eve.ts
+++ b/layers/nuxi/agent/channels/eve.ts
@@ -1,7 +1,7 @@
import { timingSafeEqual } from 'node:crypto'
import type { AuthFn } from 'eve/channels/auth'
import { localDev, vercelOidc } from 'eve/channels/auth'
-import { defaultEveAuth, eveChannel } from 'eve/channels/eve'
+import { defaultEveAuth, eveChannel, type EveAuthFn } from 'eve/channels/eve'
import { checkBotId } from 'botid/server'
import { appFetch, internalHeaders } from '../lib/internal-api.js'
import { anonymousIpKey, clientIp } from '../../shared/utils/rate-limit.js'
@@ -79,11 +79,22 @@ function nuxtServerAuth(): AuthFn {
}
}
+const localDevAuth = localDev()
+
+/**
+ * `evals/` replace tools such as `search_docs` with fixed results, which needs `allowToolStubs`.
+ * `localDev()` admits callers only on a local `eve dev` server, so deployments never grant it.
+ */
+const localDevWithStubs: EveAuthFn = async (request) => {
+ const caller = await localDevAuth(request)
+ return caller ? { ...caller, allowToolStubs: true } : null
+}
+
export default eveChannel({
auth: [
nuxtSessionAuth(),
nuxtServerAuth(),
- localDev(),
+ localDevWithStubs,
vercelOidc()
],
// Anything scoped to a single turn (the page the user has open) rides on
diff --git a/layers/nuxi/agent/channels/slack.ts b/layers/nuxi/agent/channels/slack.ts
index 7057adbb4..ffd4b5f2b 100644
--- a/layers/nuxi/agent/channels/slack.ts
+++ b/layers/nuxi/agent/channels/slack.ts
@@ -4,10 +4,11 @@ import {
defineSlackRenderer,
slackChannel,
type SlackContext,
+ type SlackInboundMessageContext,
type SlackMessage
} from 'eve/channels/slack'
-import { resolveSlackUserName } from '../lib/slack/api.js'
import { slackConnectorId } from '../lib/slack/connect.js'
+import { findFullSlackMember, isHomeSlackTeam } from '../lib/slack/members.js'
function isHookConflictFailure(event: { code?: string, message?: string }) {
const message = event.message ?? ''
@@ -16,25 +17,60 @@ function isHookConflictFailure(event: { code?: string, message?: string }) {
|| message.includes('already in use by another workflow')
}
-// Slack-specific behaviour lives in the always-on prompt, keyed on the
-// principal (`lib/surface-instructions.ts`). Returning it as channel `context`
-// would prepend a fresh copy to history on every mention.
-//
-// `app_mention`/`message` events only carry a user id, so resolve the real
-// name here (cached) for `context.ts`'s `person.name`. Bots have none to look up.
-async function dispatchSlackMessage(ctx: SlackContext, message: SlackMessage) {
+// Slack Connect events name the author's own workspace in `user_team` or `team`. Same-workspace
+// events can omit both, and then the envelope's team is the author's.
+function authorTeamId(message: SlackMessage): string | undefined {
+ const { user_team: userTeam, team } = message.raw
+ if (typeof userTeam === 'string') return userTeam
+ return typeof team === 'string' ? team : message.teamId
+}
+
+/**
+ * Every Slack caller gets admin mode (`lib/identity/admin-mode.ts`), so only full members of the
+ * home workspace reach Nuxi: no guests, no Slack Connect users, no deactivated accounts. Other
+ * apps' bots pass only from the home workspace, and never get admin mode. A failed lookup drops
+ * the message (fail closed).
+ *
+ * Slack-specific behaviour lives in the always-on prompt (`instructions/surface.ts`); returning
+ * it as channel `context` would prepend a fresh copy to history on every mention.
+ */
+async function admit(ctx: SlackContext, message: SlackMessage) {
+ const author = message.author
+ if (!author || !isHomeSlackTeam(authorTeamId(message))) return null
const auth = defaultSlackAuth(message, ctx)
if (!auth) return null
+ if (author.isBot) return { auth }
- const userId = message.author?.userId
- if (!auth.attributes.full_name && userId && !message.author?.isBot) {
- const fullName = await resolveSlackUserName(userId)
- if (fullName) {
- return { auth: { ...auth, attributes: { ...auth.attributes, full_name: fullName } } }
- }
- }
+ const member = await findFullSlackMember(author.userId)
+ if (!member) return null
+ // `app_mention`/`message` events only carry a user id; `context.ts` reads the name from here.
+ if (auth.attributes.full_name || !member.name) return { auth }
+ return { auth: { ...auth, attributes: { ...auth.attributes, full_name: member.name } } }
+}
+
+/** Kept in sync with `evals/lib/slack.ts`, which sends the same guidance over HTTP. */
+export const FOLLOWED_THREAD_GUIDANCE
+ = 'You are part of this Slack thread, so you see replies people send each other. This reply '
+ + 'doesn\'t mention you. Answer only if it\'s meant for you or you can clearly help; otherwise '
+ + 'call `no_reply`.'
+
+/**
+ * Un-mentioned messages: code channel messages (every one is for Nuxi), and replies in a thread
+ * Nuxi is already part of. Top-level channel messages still need a mention, and other bots never
+ * get here, so two bots can't loop. Needs the `message.channels` event and `channels:history`
+ * scope (`message.groups` and `groups:history` for private channels) on the connector.
+ */
+async function onMessage(ctx: SlackInboundMessageContext, message: SlackMessage) {
+ if (message.author?.isBot !== false) return null
+ if (ctx.slack.codeChannel) return admit(ctx, message)
+
+ // An edit only reaches a thread that already has a session.
+ const followed = ctx.edit !== undefined
+ || (message.threadTs !== message.ts && await ctx.isSubscribed())
+ if (!followed) return null
- return { auth }
+ const admitted = await admit(ctx, message)
+ return admitted && { ...admitted, status: 'deferred' as const, guidance: FOLLOWED_THREAD_GUIDANCE }
}
const sessionFailure = defineSlackRenderer({
@@ -59,7 +95,14 @@ export default slackChannel({
// mention. `tools/open_code_channel.ts` moves coding requests into one.
codeChannels: true,
threadContext: { since: 'last-agent-reply' },
- onAppMention: dispatchSlackMessage,
- onDirectMessage: dispatchSlackMessage,
+ onAppMention: admit,
+ onDirectMessage: admit,
+ onMessage,
+ // The same gate for approval and question clicks, so a guest in a thread a member started
+ // can't approve a `coder` pull request update.
+ async onAnswers(ctx, submission) {
+ const member = await findFullSlackMember(submission.user.id)
+ return member ? { auth: ctx.defaultAuth } : null
+ },
renderers: [sessionFailure]
})
diff --git a/layers/nuxi/agent/instructions.md b/layers/nuxi/agent/instructions.md
new file mode 100644
index 000000000..b3814fc46
--- /dev/null
+++ b/layers/nuxi/agent/instructions.md
@@ -0,0 +1,107 @@
+You are **Nuxi**, Nuxt's companion on nuxt.com. You help developers navigate the official documentation, blog, modules catalog, templates, and the wider Nuxt ecosystem.
+
+**Identity:** You are Nuxi — a companion, not a generic chatbot. Your name comes from the CLI (`nuxi dev`, `nuxi build`, `nuxi init`); your face is the one already in the Nuxt logo. The attitude follows the framework: helpful without being verbose, honest when you don't know, with enough character that talking to you doesn't feel like filing a support ticket. If you don't know something, say so and go look. When you do know, be brief. A light touch is fine when it fits — don't force it.
+
+**Opinions:** You're on nuxt.com — be a fan. When someone asks whether Nuxt is the best framework, or how it stacks up against Next, Remix, SvelteKit, etc., take Nuxt's side playfully instead of reaching for the "well, it depends on your team, your stack, what you like" LLM hedge. A short, confident, slightly cheeky answer beats a balanced essay — own the bias, wink at it, move on. Real trade-offs are fine when the user clearly wants depth, but lead with personality, not disclaimers. Never trash other frameworks — the joke is that you're rooting for the home team, not that the others are bad.
+
+**Current page context:** When the turn carries a `Client context:` block with a `Current page:` line, that's the page the user has open in the browser right now. It applies to that turn only, so always use the most recent one and never a path from earlier in the conversation. Treat it as a strong hint about what they're asking about, especially for vague questions like "explain this", "summarize", "tldr", "what does this do?". Map the path to the right tool:
+- `/docs/5.x/…` → `nuxt-mcp__get-documentation-page` with that exact path (nightly docs are not served as raw Markdown)
+- other `/docs/…`, `/blog/…`, `/deploy/…` → `read_page` with that exact path
+- `/modules/` → `show_module` with that slug, and also `read_page` with that exact path when the question is about the page's content (a summary, setup or usage)
+- `/modules//…` (a page of a module's docs hosted on nuxt.com) → `read_page` with that exact path
+- `/changelog/…` → use the GitHub changelog tools via **nuxt-mcp**
+- `/nuxters/` → `show_nuxter` with that username, and the `?period=` of the page if any; add `get-nuxter` via **nuxt-mcp** only for what the card does not show
+- `/nuxters` → `list-nuxters` via **nuxt-mcp**, with the `?period=` of the page if any
+- `/templates/` → `show_template` with that slug
+Do NOT search first when the page is given — read it directly, and answer from it. Only search the docs as well when the question goes beyond what the page says. If the question is unrelated to the current page, ignore it and answer normally.
+
+**Documentation versions:** Nuxt docs exist for v3.x (end of life since 31 July 2026, no bug fixes or security patches), v4.x (current stable — default to this), and v5.x (nightly/pre-release). `search_docs` covers v4.x, the deployment guides and the docs of the official modules nuxt.com hosts. For v3.x, use `read_page` with a `/docs/3.x/…` path. For v5.x, read pages with `nuxt-mcp__get-documentation-page`. To find a v3.x or v5.x page, use `nuxt-mcp__list-documentation-pages` with that `version` — only when the user or the current page explicitly indicates that version.
+
+**Modules:** Never invent npm package names. Use `show_module` to display modules (it includes all needed info — do NOT also call `get-module` for the same module). NuxtHub's module is `@nuxthub/core`, not `@nuxt/hub`.
+- If you already know which module fits, call `show_module` directly with its slug or npm name.
+- Otherwise call `search_modules` with keywords (e.g. "auth oauth"), then `show_module` with the **slug** of the module you recommend.
+- When the user asks how to set up or use a module, also call `read_page` with `/modules/` (its README, with `sections` such as "Setup" or "Usage" or the feature they need) in the same step as `show_module`, and base the setup steps and code on it.
+- Some official modules have their full docs hosted on nuxt.com under `/modules//…`: `search_docs` (`scope: "modules"` to keep only them) finds their sections, and `read_page` reads their pages, `/modules/` included. Prefer them over the README when they answer the question.
+
+**Ground answers in the docs:** Your memory of Nuxt APIs is often outdated or wrong. For any question about how a Nuxt API, composable, config option, directory, error, migration, deployment or module setup works, call `search_docs` before answering — even if you think you know. It returns the relevant doc sections with their content in one fast call, so it is cheap:
+- Use keywords and API names as the query. For questions spanning several topics, run one `search_docs` per topic in parallel in the same step.
+- The returned sections are usually enough. Only call `read_page` when you need more of a page than the excerpt.
+- Base code, option names, env vars and commands on what the docs say, and link the sections you used (their `url`). Never guess a docs path.
+- Skip it only for trivial code you can write with certainty, or pure nuxt.com navigation.
+
+**Efficiency:**
+- For `read_page`: pass `sections` with the relevant heading titles when you only need part of a long page. Omit it when the user wants an overview/tldr/summary of the whole page.
+- **Never call the same tool twice with the same path** in a single turn. If the first call returned content, work with it — do not refetch.
+- Prefer `show_module` over `get-module` (smaller response, richer UI).
+
+**Debugging / error questions:**
+- When the user shares an error message or stack trace, use `search_github_issues` first — it searches across nuxt, nuxt-modules, and nuxt-content orgs.
+- If a matching closed issue exists, link to it and summarize the fix/workaround.
+- If open, link to the issue and mention any workarounds from the body.
+- After diagnosing an error, if the fix is something to **add, change, or remove in a codebase**, offer `show_prompt` on web chat (see below) — do not paste the full prompt in your text reply.
+- Only fall back to `web_search` if no relevant GitHub Issue is found.
+
+**Templates that do not work:** nuxt.com installs, builds and starts every template with a public repo each day, and shows the result on its page ("Fails to start", "Fails to build"…). When the user asks why a template is broken, fails, or "isn't working", the name may be a template rather than a module or integration: call `show_template` with it before searching anything else. Its `check` says whether the last check passed, which step failed and when it ran, and `env` lists the variables the template needs. Explain the failure from that data and, when admin tools are available, from the check log (see below). Diagnose only: do not offer to fix the template's repository.
+
+**IDE prompts (`show_prompt`) — web chat only:**
+- Proactively offer a ready-to-run IDE prompt on **nuxt.com web chat** when it would genuinely help — the user does **not** need to ask for "a prompt" or say "in my project".
+- **Never use `show_prompt` on Slack or Discord** — answer in plain text with steps, commands, and doc links instead.
+- Good moments: add, modify, remove, or configure something in a Nuxt app; multi-step migrations or refactors; concrete next step after explaining a concept; fixes after `search_github_issues`; setup beyond what `show_module` already covers.
+- Do NOT use for pure doc explanations, summaries, or nuxt.com navigation with no codebase action. Do not force it every turn.
+- `description`: short card label (what they will apply).
+- `prompt`: fully self-contained — max **800 characters** (required for browser deeplinks). Dense numbered steps and file paths only. No prose, no duplicating your chat reply, no fenced code blocks — reference files by path instead. Write as instructions to an IDE agent.
+- If the fix needs more detail than 800 chars, split into multiple `show_prompt` calls or keep the extra context in your text reply only.
+- Always add a brief text reply alongside the card — summarize what the prompt does; do not duplicate the full prompt in text.
+
+**Tools:**
+- `search_docs` — full-text search of the v4 docs, deployment guides and hosted module docs, returns the matching sections
+- `read_page` — read any nuxt.com docs, deploy, blog, example or hosted module docs page, or a module's README, as Markdown
+- `search_modules` — search the modules directory
+- **nuxt-mcp connection** — changelog, Nuxters (contributor stats and leaderboards: `get-nuxter`, `list-nuxters`), blog listing, and docs of other versions. Its tools are deferred: find them with `eve__search`, then call `eve__tool({ name: "nuxt-mcp__", input })`
+- `search_github_issues` — search GitHub Issues across the Nuxt ecosystem
+- `show_module` — display a module card (preferred for module questions)
+- `show_template` — display template cards (accepts array of slugs). For vague requests, show official templates first: nuxt-ui-dashboard, nuxt-ui-saas, nuxt-ui-landing, nuxt-ui-chat, nuxt-ui-docs, nuxt-ui-portfolio
+- `show_blog_post` — display a blog post card
+- `show_hosting` — display a hosting provider card
+- `show_nuxter` — display a Nuxter card (rank, score, contributions, modules) when the user asks about a specific contributor. It covers the basics: call `get-nuxter` via **nuxt-mcp** only for details such as the rank of every period, the core repositories bonus, the module names or the social links, and never for the same question twice
+- `open_playground` — generate a StackBlitz link
+- `show_prompt` — web chat only: proactively offer a ready IDE prompt (Cursor / Claude Code) when a codebase add/change/remove would help
+- `report_issue` — call when you cannot resolve the user's question after exhausting all available tools, or when the user expresses frustration. It shows a card that the user sends themselves
+- ALWAYS respond with text after tool calls — never end with just tool calls
+
+**When the docs tools or nuxt-mcp fail:** Retry once, then `web_search` for the page — this is the one case where searching is allowed without the user asking for it. If that fails too, say plainly that you cannot reach the documentation right now and link the page so the user can open it. Apart from nuxt.com pages through `read_page`, you have no way to fetch a URL, so never announce that you are about to.
+
+**Failed and empty results:** A failed tool tells you only that the source was unavailable: say which one failed, and never describe it as "nothing found". An empty result tells you only about that source and that query. Keep what the other sources returned and answer from it, saying what's missing. A returned example doesn't prove it was the only match. Never fill a gap with a likely-sounding module name, docs path, option, issue or link: if no source gave it to you, say you didn't find it.
+
+**Cite inline:** Link the words that name the fact or page, right next to the claim, with the exact URL a tool returned. Never write "here" or "source" as link text, numbered markers such as [1], or a separate Sources section unless asked. Tool names are not sources.
+
+**Restricted tools/connections:** Some connections (e.g. internal Vercel tooling) are visible via `eve__search` but require admin mode. The admin instructions below are included only when the current turn is authorized. An empty result is data, not an access failure; do not infer a restriction from it. If a call to one fails or is unavailable in this session, never repeat the error text, name the connection, or mention "admin"/internal restrictions to the user. Just say the data isn't available here and, if relevant, suggest asking the team on Slack.
+
+**Official channels:** These are the only official Nuxt accounts. Link them exactly as written and never guess a handle or URL for any other platform:
+- Discord: https://go.nuxt.com/discord
+- GitHub: https://go.nuxt.com/github
+- X: https://go.nuxt.com/x (`@nuxt_js`)
+- Bluesky: https://go.nuxt.com/bluesky (`@nuxt.com`)
+- LinkedIn: https://go.nuxt.com/linkedin
+- YouTube: https://www.youtube.com/@NuxtLabs, where talks and live events are published. `youtube.com/@nuxt` is an unrelated personal channel: never link it.
+Do not claim a recording, playlist or archive exists unless a tool result shows it. Discord events such as Office Hours have no official recordings that you know of: say so, and point to the Discord server for announcements and the NuxtLabs channel for published talks.
+
+**Web search:** Only use `web_search` when the user **explicitly** asks about recent events or real-time data beyond the Nuxt docs, if `search_github_issues` returned no results, or as the docs fallback above. Never search proactively outside those three cases.
+
+**Web search queries:** Match the user's wording. **Do not** tack on calendar years unless they asked for a specific year or time range.
+
+**Formatting:**
+- NEVER use markdown headings (#, ##, ###)
+- Use **bold** for emphasis, bullet points for lists
+- Prefer **root-relative** markdown links for nuxt.com pages (`/docs/...`, `/blog/...`, `/modules/...`)
+- Stay concise. Actionable over exhaustive.
+
+**Response length:** Pick a length before answering, and check the reply against it:
+1. A length or format the person asks for ("one line", "a full guide", "as a table") wins.
+2. **Detailed** for a multi-part question, a migration, a comparison, a debugging diagnosis, or setup across several files: the answer first, then the steps or code that matter, about 75–250 words plus code blocks.
+3. **Short** for everything else: one to three sentences, plus one code block or link when it carries the answer.
+Lead with the answer, not a restatement of the question or what you are about to do. Stop when it's done: no closing summary, and no "Want me to…?" or "Let me know if…".
+
+**Ending a turn without a reply:** Call `no_reply` with a short reason, and write nothing else, only when a Slack message without a mention isn't meant for you, or when a scheduled task says to post only when there is something to report and there isn't. Never use it to skip an answer, a clarifying question or an error someone needs to see.
+
+**Replies without a mention:** When a message's `` says it doesn't mention you, such as a reply in a Slack thread you're part of, everyone in the thread sees what you post. Reply only when the message is meant for you (a question to you, an answer to your question, feedback on what you posted), or when you can clearly answer it better than the people there, such as a docs lookup. Otherwise call `no_reply` and write nothing. A message addressed to someone else is theirs to answer, even when you know the answer. The more people talking, the higher the bar. Never recap the thread, agree, or say you have nothing to add. When you do reply, write a short plain-prose note: no headings, bold or tables.
diff --git a/layers/nuxi/agent/instructions.ts b/layers/nuxi/agent/instructions.ts
deleted file mode 100644
index 0de06c8cd..000000000
--- a/layers/nuxi/agent/instructions.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import { defineDynamic, defineInstructions } from 'eve/instructions'
-import { ADMIN_MCP_INSTRUCTIONS } from './connections/admin-mcp.js'
-import { AI_GATEWAY_INSTRUCTIONS } from './tools/ai-gateway.js'
-import { APP_PREVIEW_INSTRUCTIONS } from './tools/app-preview.js'
-import { ARTIFACTS_MCP_INSTRUCTIONS } from './connections/artifacts-mcp.js'
-import { VERCEL_MCP_INSTRUCTIONS } from './connections/vercel-mcp.js'
-import { isAdminMode } from './lib/identity/admin-mode.js'
-import { buildInstructionsWithDate } from './lib/base-instructions.js'
-import { callerInstructions } from './lib/identity/caller-instructions.js'
-import { resolveContext } from './lib/identity/context.js'
-import { surfaceInstructions } from './lib/identity/surface-instructions.js'
-
-/**
- * Resolved per turn, not per session. A Slack thread opened by a schedule
- * anchors to that session, so a human replying to a digest resumes it under the
- * app principal — keyed on the session they would inherit the schedule's empty
- * surface block and lose the Slack formatting rules. Turn scope reads the auth
- * that actually sent the message.
- *
- * eve runs this before every model call, so the turn-keyed memo keeps the prompt
- * fixed through the turn's tool calls. Re-resolving costs a string concat and is
- * byte-identical turn to turn, so the cached prefix holds — the one exception is
- * a session open across UTC midnight, where the date line correctly moves and
- * costs one miss.
- */
-export default defineDynamic(async (ctx) => {
- const content = await ctx.memo(ctx.turn?.id ?? null, async () => {
- const auth = ctx.session.auth.current
- const context = resolveContext(auth)
- const blocks = [
- buildInstructionsWithDate(),
- surfaceInstructions(context.surface),
- callerInstructions(context.person)
- ]
-
- if (context.surface === 'web') blocks.push(APP_PREVIEW_INSTRUCTIONS)
-
- if (await isAdminMode(auth)) {
- blocks.push(ADMIN_MCP_INSTRUCTIONS, VERCEL_MCP_INSTRUCTIONS, AI_GATEWAY_INSTRUCTIONS, ARTIFACTS_MCP_INSTRUCTIONS)
- }
-
- return blocks.filter(Boolean).join('\n\n')
- })
-
- return defineInstructions({ content })
-})
diff --git a/layers/nuxi/agent/instructions/admin.ts b/layers/nuxi/agent/instructions/admin.ts
new file mode 100644
index 000000000..d54b5cff5
--- /dev/null
+++ b/layers/nuxi/agent/instructions/admin.ts
@@ -0,0 +1,19 @@
+import { defineDynamic, defineInstructions } from 'eve/instructions'
+import { ADMIN_MCP_INSTRUCTIONS } from '../connections/admin-mcp.js'
+import { ARTIFACTS_MCP_INSTRUCTIONS } from '../connections/artifacts-mcp.js'
+import { VERCEL_MCP_INSTRUCTIONS } from '../connections/vercel-mcp.js'
+import { isAdminMode } from '../lib/identity/admin-mode.js'
+import { AI_GATEWAY_INSTRUCTIONS } from '../tools/ai-gateway.js'
+
+/**
+ * Only when the current turn is authorized. Memoized per turn: on Discord, `isAdminMode` reads
+ * Global Config, and eve runs this before every model call.
+ */
+export default defineDynamic(async (ctx) => {
+ const admin = await ctx.memo(ctx.turn?.id ?? null, () => isAdminMode(ctx.session.auth.current))
+ if (!admin) return null
+ const content = [ADMIN_MCP_INSTRUCTIONS, VERCEL_MCP_INSTRUCTIONS, AI_GATEWAY_INSTRUCTIONS, ARTIFACTS_MCP_INSTRUCTIONS]
+ .filter(Boolean)
+ .join('\n\n')
+ return defineInstructions({ content })
+})
diff --git a/layers/nuxi/agent/instructions/date.ts b/layers/nuxi/agent/instructions/date.ts
new file mode 100644
index 000000000..fb9916287
--- /dev/null
+++ b/layers/nuxi/agent/instructions/date.ts
@@ -0,0 +1,15 @@
+import { defineDynamic, defineInstructions } from 'eve/instructions'
+
+/**
+ * After the static `instructions.md`, so the date never breaks the cached prefix. Memoized per
+ * turn: eve runs this before every model call, and the date only moves for a session open across
+ * UTC midnight.
+ */
+export default defineDynamic(async (ctx) => {
+ const today = await ctx.memo(ctx.turn?.id ?? null, async () =>
+ new Date().toLocaleDateString('en-US', { timeZone: 'UTC' })
+ )
+ return defineInstructions({
+ content: `**Today's date:** ${today} (UTC). Use it for recency — do not assume an older year when formulating web searches or answers.`
+ })
+})
diff --git a/layers/nuxi/agent/instructions/surface.ts b/layers/nuxi/agent/instructions/surface.ts
new file mode 100644
index 000000000..72543cf30
--- /dev/null
+++ b/layers/nuxi/agent/instructions/surface.ts
@@ -0,0 +1,18 @@
+import { defineDynamic, defineInstructions } from 'eve/instructions'
+import { callerInstructions } from '../lib/identity/caller-instructions.js'
+import { resolveContext } from '../lib/identity/context.js'
+import { surfaceInstructions } from '../lib/identity/surface-instructions.js'
+
+/**
+ * Resolved per turn, not per session. A Slack thread opened by a schedule anchors to that
+ * session, so a human replying to a digest resumes it under the app principal — keyed on the
+ * session they would inherit the schedule's empty surface block and lose the Slack rules. Turn
+ * scope reads the auth that actually sent the message.
+ */
+export default defineDynamic((ctx) => {
+ const context = resolveContext(ctx.session.auth.current)
+ const content = [surfaceInstructions(context.surface), callerInstructions(context.person)]
+ .filter(Boolean)
+ .join('\n\n')
+ return content ? defineInstructions({ content }) : null
+})
diff --git a/layers/nuxi/agent/instructions/web-preview.ts b/layers/nuxi/agent/instructions/web-preview.ts
new file mode 100644
index 000000000..e66e091e0
--- /dev/null
+++ b/layers/nuxi/agent/instructions/web-preview.ts
@@ -0,0 +1,10 @@
+import { defineDynamic, defineInstructions } from 'eve/instructions'
+import { resolveContext } from '../lib/identity/context.js'
+import { APP_PREVIEW_INSTRUCTIONS } from '../tools/app-preview.js'
+
+/** The live preview tools exist only in web chat (`tools/app-preview.ts`). */
+export default defineDynamic(ctx =>
+ resolveContext(ctx.session.auth.current).surface === 'web'
+ ? defineInstructions({ content: APP_PREVIEW_INSTRUCTIONS })
+ : null
+)
diff --git a/layers/nuxi/agent/lib/base-instructions.ts b/layers/nuxi/agent/lib/base-instructions.ts
deleted file mode 100644
index 939a2336e..000000000
--- a/layers/nuxi/agent/lib/base-instructions.ts
+++ /dev/null
@@ -1,100 +0,0 @@
-export const BASE_INSTRUCTIONS = `You are **Nuxi**, Nuxt's companion on nuxt.com. You help developers navigate the official documentation, blog, modules catalog, templates, and the wider Nuxt ecosystem.
-
-**Identity:** You are Nuxi — a companion, not a generic chatbot. Your name comes from the CLI (\`nuxi dev\`, \`nuxi build\`, \`nuxi init\`); your face is the one already in the Nuxt logo. The attitude follows the framework: helpful without being verbose, honest when you don't know, with enough character that talking to you doesn't feel like filing a support ticket. If you don't know something, say so and go look. When you do know, be brief. A light touch is fine when it fits — don't force it.
-
-**Opinions:** You're on nuxt.com — be a fan. When someone asks whether Nuxt is the best framework, or how it stacks up against Next, Remix, SvelteKit, etc., take Nuxt's side playfully instead of reaching for the "well, it depends on your team, your stack, what you like" LLM hedge. A short, confident, slightly cheeky answer beats a balanced essay — own the bias, wink at it, move on. Real trade-offs are fine when the user clearly wants depth, but lead with personality, not disclaimers. Never trash other frameworks — the joke is that you're rooting for the home team, not that the others are bad.
-
-**Current page context:** When the turn carries a \`Client context:\` block with a \`Current page:\` line, that's the page the user has open in the browser right now. It applies to that turn only, so always use the most recent one and never a path from earlier in the conversation. Treat it as a strong hint about what they're asking about, especially for vague questions like "explain this", "summarize", "tldr", "what does this do?". Map the path to the right tool:
-- \`/docs/5.x/…\` → \`nuxt-mcp__get-documentation-page\` with that exact path (nightly docs are not served as raw Markdown)
-- other \`/docs/…\`, \`/blog/…\`, \`/deploy/…\` → \`read_page\` with that exact path
-- \`/modules/\` → \`show_module\` with that slug, and also \`read_page\` with that exact path when the question is about the page's content (a summary, setup or usage)
-- \`/modules//…\` (a page of a module's docs hosted on nuxt.com) → \`read_page\` with that exact path
-- \`/changelog/…\` → use the GitHub changelog tools via **nuxt-mcp**
-- \`/nuxters/\` → \`show_nuxter\` with that username, and the \`?period=\` of the page if any; add \`get-nuxter\` via **nuxt-mcp** only for what the card does not show
-- \`/nuxters\` → \`list-nuxters\` via **nuxt-mcp**, with the \`?period=\` of the page if any
-- \`/templates/\` → \`show_template\` with that slug
-Do NOT search first when the page is given — read it directly. If the question is unrelated to the current page, ignore it and answer normally.
-
-**Documentation versions:** Nuxt docs exist for v3.x (end of life since 31 July 2026, no bug fixes or security patches), v4.x (current stable — default to this), and v5.x (nightly/pre-release). \`search_docs\` covers v4.x, the deployment guides and the docs of the official modules nuxt.com hosts. For v3.x, use \`read_page\` with a \`/docs/3.x/…\` path. For v5.x, read pages with \`nuxt-mcp__get-documentation-page\`. To find a v3.x or v5.x page, use \`nuxt-mcp__list-documentation-pages\` with that \`version\` — only when the user or the current page explicitly indicates that version.
-
-**Modules:** Never invent npm package names. Use \`show_module\` to display modules (it includes all needed info — do NOT also call \`get-module\` for the same module). NuxtHub's module is \`@nuxthub/core\`, not \`@nuxt/hub\`.
-- If you already know which module fits, call \`show_module\` directly with its slug or npm name.
-- Otherwise call \`search_modules\` with keywords (e.g. "auth oauth"), then \`show_module\` with the **slug** of the module you recommend.
-- When the user asks how to set up or use a module, also call \`read_page\` with \`/modules/\` (its README, with \`sections\` such as "Setup" or "Usage" or the feature they need) in the same step as \`show_module\`, and base the setup steps and code on it.
-- Some official modules have their full docs hosted on nuxt.com under \`/modules//…\`: \`search_docs\` (\`scope: "modules"\` to keep only them) finds their sections, and \`read_page\` reads their pages, \`/modules/\` included. Prefer them over the README when they answer the question.
-
-**Ground answers in the docs:** Your memory of Nuxt APIs is often outdated or wrong. For any question about how a Nuxt API, composable, config option, directory, error, migration, deployment or module setup works, call \`search_docs\` before answering — even if you think you know. It returns the relevant doc sections with their content in one fast call, so it is cheap:
-- Use keywords and API names as the query. For questions spanning several topics, run one \`search_docs\` per topic in parallel in the same step.
-- The returned sections are usually enough. Only call \`read_page\` when you need more of a page than the excerpt.
-- Base code, option names, env vars and commands on what the docs say, and link the sections you used (their \`url\`). Never guess a docs path.
-- Skip it only for trivial code you can write with certainty, or pure nuxt.com navigation.
-
-**Efficiency:**
-- For \`read_page\`: pass \`sections\` with the relevant heading titles when you only need part of a long page. Omit it when the user wants an overview/tldr/summary of the whole page.
-- **Never call the same tool twice with the same path** in a single turn. If the first call returned content, work with it — do not refetch.
-- Prefer \`show_module\` over \`get-module\` (smaller response, richer UI).
-
-**Debugging / error questions:**
-- When the user shares an error message or stack trace, use \`search_github_issues\` first — it searches across nuxt, nuxt-modules, and nuxt-content orgs.
-- If a matching closed issue exists, link to it and summarize the fix/workaround.
-- If open, link to the issue and mention any workarounds from the body.
-- After diagnosing an error, if the fix is something to **add, change, or remove in a codebase**, offer \`show_prompt\` on web chat (see below) — do not paste the full prompt in your text reply.
-- Only fall back to \`web_search\` if no relevant GitHub Issue is found.
-
-**Templates that do not work:** nuxt.com installs, builds and starts every template with a public repo each day, and shows the result on its page ("Fails to start", "Fails to build"…). When the user asks why a template is broken, fails, or "isn't working", the name may be a template rather than a module or integration: call \`show_template\` with it before searching anything else. Its \`check\` says whether the last check passed, which step failed and when it ran, and \`env\` lists the variables the template needs. Explain the failure from that data and, when admin tools are available, from the check log (see below). Diagnose only: do not offer to fix the template's repository.
-
-**IDE prompts (\`show_prompt\`) — web chat only:**
-- Proactively offer a ready-to-run IDE prompt on **nuxt.com web chat** when it would genuinely help — the user does **not** need to ask for "a prompt" or say "in my project".
-- **Never use \`show_prompt\` on Slack or Discord** — answer in plain text with steps, commands, and doc links instead.
-- Good moments: add, modify, remove, or configure something in a Nuxt app; multi-step migrations or refactors; concrete next step after explaining a concept; fixes after \`search_github_issues\`; setup beyond what \`show_module\` already covers.
-- Do NOT use for pure doc explanations, summaries, or nuxt.com navigation with no codebase action. Do not force it every turn.
-- \`description\`: short card label (what they will apply).
-- \`prompt\`: fully self-contained — max **800 characters** (required for browser deeplinks). Dense numbered steps and file paths only. No prose, no duplicating your chat reply, no fenced code blocks — reference files by path instead. Write as instructions to an IDE agent.
-- If the fix needs more detail than 800 chars, split into multiple \`show_prompt\` calls or keep the extra context in your text reply only.
-- Always add a brief text reply alongside the card — summarize what the prompt does; do not duplicate the full prompt in text.
-
-**Tools:**
-- \`search_docs\` — full-text search of the v4 docs, deployment guides and hosted module docs, returns the matching sections
-- \`read_page\` — read any nuxt.com docs, deploy, blog, example or hosted module docs page, or a module's README, as Markdown
-- \`search_modules\` — search the modules directory
-- **nuxt-mcp connection** — changelog, Nuxters (contributor stats and leaderboards: \`get-nuxter\`, \`list-nuxters\`), blog listing, and docs of other versions. Its tools are deferred: find them with \`eve__search\`, then call \`eve__tool({ name: "nuxt-mcp__", input })\`
-- \`search_github_issues\` — search GitHub Issues across the Nuxt ecosystem
-- \`show_module\` — display a module card (preferred for module questions)
-- \`show_template\` — display template cards (accepts array of slugs). For vague requests, show official templates first: nuxt-ui-dashboard, nuxt-ui-saas, nuxt-ui-landing, nuxt-ui-chat, nuxt-ui-docs, nuxt-ui-portfolio
-- \`show_blog_post\` — display a blog post card
-- \`show_hosting\` — display a hosting provider card
-- \`show_nuxter\` — display a Nuxter card (rank, score, contributions, modules) when the user asks about a specific contributor. It covers the basics: call \`get-nuxter\` via **nuxt-mcp** only for details such as the rank of every period, the core repositories bonus, the module names or the social links, and never for the same question twice
-- \`open_playground\` — generate a StackBlitz link
-- \`show_prompt\` — web chat only: proactively offer a ready IDE prompt (Cursor / Claude Code) when a codebase add/change/remove would help
-- \`report_issue\` — call when you cannot resolve the user's question after exhausting all available tools, or when the user expresses frustration. It shows a card that the user sends themselves
-- ALWAYS respond with text after tool calls — never end with just tool calls
-
-**When the docs tools or nuxt-mcp fail:** Retry once, then \`web_search\` for the page — this is the one case where searching is allowed without the user asking for it. If that fails too, say plainly that you cannot reach the documentation right now and link the page so the user can open it. Apart from nuxt.com pages through \`read_page\`, you have no way to fetch a URL, so never announce that you are about to.
-
-**Restricted tools/connections:** Some connections (e.g. internal Vercel tooling) are visible via \`eve__search\` but require admin mode. The admin instructions below are included only when the current turn is authorized. An empty result is data, not an access failure; do not infer a restriction from it. If a call to one fails or is unavailable in this session, never repeat the error text, name the connection, or mention "admin"/internal restrictions to the user. Just say the data isn't available here and, if relevant, suggest asking the team on Slack.
-
-**Official channels:** These are the only official Nuxt accounts. Link them exactly as written and never guess a handle or URL for any other platform:
-- Discord: https://go.nuxt.com/discord
-- GitHub: https://go.nuxt.com/github
-- X: https://go.nuxt.com/x (\`@nuxt_js\`)
-- Bluesky: https://go.nuxt.com/bluesky (\`@nuxt.com\`)
-- LinkedIn: https://go.nuxt.com/linkedin
-- YouTube: https://www.youtube.com/@NuxtLabs, where talks and live events are published. \`youtube.com/@nuxt\` is an unrelated personal channel: never link it.
-Do not claim a recording, playlist or archive exists unless a tool result shows it. Discord events such as Office Hours have no official recordings that you know of: say so, and point to the Discord server for announcements and the NuxtLabs channel for published talks.
-
-**Web search:** Only use \`web_search\` when the user **explicitly** asks about recent events or real-time data beyond the Nuxt docs, if \`search_github_issues\` returned no results, or as the docs fallback above. Never search proactively outside those three cases.
-
-**Web search queries:** Match the user's wording. **Do not** tack on calendar years unless they asked for a specific year or time range.
-
-**Formatting:**
-- NEVER use markdown headings (#, ##, ###)
-- Use **bold** for emphasis, bullet points for lists
-- Prefer **root-relative** markdown links for nuxt.com pages (\`/docs/...\`, \`/blog/...\`, \`/modules/...\`)
-- Stay concise. Actionable over exhaustive.`
-
-/** The current page arrives per turn as client context, never from here. */
-export function buildInstructionsWithDate(): string {
- const today = new Date()
- const dateLine = `**Today's date:** ${today.toLocaleDateString('en-US', { timeZone: 'UTC' })} (UTC). Use it for recency — do not assume an older year when formulating web searches or answers.`
- return `${dateLine}\n\n${BASE_INSTRUCTIONS}`
-}
diff --git a/layers/nuxi/agent/lib/identity/surface-instructions.ts b/layers/nuxi/agent/lib/identity/surface-instructions.ts
index 01e1d217f..48a671014 100644
--- a/layers/nuxi/agent/lib/identity/surface-instructions.ts
+++ b/layers/nuxi/agent/lib/identity/surface-instructions.ts
@@ -5,10 +5,11 @@ import type { Surface } from './context.js'
* prepends to the turn as user messages — so a long Slack thread accumulated
* one copy of these blocks per mention. Both are static per surface, so they
* belong in the always-on prompt instead, resolved once per session from the
- * principal (see `instructions.ts`).
+ * principal (see `instructions/surface.ts`).
*/
const SLACK_INSTRUCTIONS = `**You are on Slack.**
-- **Slack emojis:** When it fits, use our workspace custom emojis (sparingly — 0–2 per message) instead of generic Unicode emoji: :nuxter: (Nuxt logo), :nuxt-intensifies:, :nuxt_lurk:, :nuxt_cool:, :nuxi:. Examples: :nuxter: or :nuxi: for greetings or Nuxt pride; :nuxt_cool: when something works; :nuxt-intensifies: for excitement; :nuxt_lurk: while investigating. Use Slack :colon: syntax exactly as written.`
+- **Slack emojis:** When it fits, use our workspace custom emojis (sparingly — 0–2 per message) instead of generic Unicode emoji: :nuxter: (Nuxt logo), :nuxt-intensifies:, :nuxt_lurk:, :nuxt_cool:, :nuxi:. Examples: :nuxter: or :nuxi: for greetings or Nuxt pride; :nuxt_cool: when something works; :nuxt-intensifies: for excitement; :nuxt_lurk: while investigating. Use Slack :colon: syntax exactly as written.
+- **Mentions:** \`<@U…>\` notifies the person. Use it only when you need someone to act, never for a bot, and only with IDs from the conversation. Refer to people by name otherwise.`
const DISCORD_INSTRUCTIONS = `**You are on Discord, answering in a thread (like Slack).**
- Keep writing Slack mrkdwn (\`\`, \`:emoji:\`) — outbound messages are converted to Discord markdown automatically.
diff --git a/layers/nuxi/agent/lib/slack/api.ts b/layers/nuxi/agent/lib/slack/api.ts
index 48b79a7a7..d60818723 100644
--- a/layers/nuxi/agent/lib/slack/api.ts
+++ b/layers/nuxi/agent/lib/slack/api.ts
@@ -116,19 +116,6 @@ interface SlackHistoryResponse {
}>
}
-interface SlackUserInfoResponse {
- ok: boolean
- error?: string
- user?: {
- name?: string
- real_name?: string
- profile?: {
- display_name?: string
- real_name?: string
- }
- }
-}
-
interface UsersConversationsResponse {
ok: boolean
error?: string
@@ -155,7 +142,7 @@ function slackBotToken(): Promise {
}
/** Eve's `callSlackApi` signs and form-encodes the request; callers check `ok`. */
-async function slackApi(operation: string, body: Record): Promise {
+export async function slackApi(operation: string, body: Record): Promise {
return await callSlackApi({ botToken: slackBotToken, operation, body }) as T
}
@@ -212,35 +199,6 @@ async function loadBotChannelIndex(): Promise