Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

Improve docs from support feedback (#1905)

John Phamous34ac1df795b4
diff --git a/.agents/skills/human-writing/SKILL.md b/.agents/skills/human-writing/SKILL.md
deleted file mode 100644
index d5b37cc94..000000000
--- a/.agents/skills/human-writing/SKILL.md
+++ /dev/null
@@ -1,107 +0,0 @@
----
-name: human-writing
-description: Edit, review, audit, or draft standalone prose while preserving the writer's meaning and voice. Use for documentation, markdown, emails, blog posts, PRDs, and other dedicated writing when the user wants clearer, more direct, more natural, or less AI-patterned language, or asks whether a draft contains AI-slop patterns. Do not use for routine conversational replies or code unless the user asks to edit its prose.
----
-
-# Human writing
-
-Act as a sharp human editor. Preserve the writer's point and recognizable voice while making the prose clearer and more alive. Remove stock AI patterns without flattening distinctive writing into generic polished copy.
-
-## Choose the mode
-
-Use the mode implied by the request. Infer the audience, format, and goal from context. Ask one concise question only when a missing answer would materially change the result.
-
-### Edit
-
-Use by default when the user provides a draft to improve. Make the minimum effective edit. Return the full edited draft and a short **What changed** section unless the user asks for clean copy only.
-
-### Detect
-
-Use when the user asks to audit, scan, flag, or judge whether a draft reads like AI slop without rewriting it. Name each relevant pattern, quote the affected text, and explain the problem or likely fix briefly. Do not rewrite the draft, assign an AI score, or claim to know whether AI wrote it. These patterns are evidence a reader can inspect, not proof of authorship.
-
-### Draft
-
-Use when the user asks for new prose. Follow the supplied brief, audience, format, tone, and writing samples. Do not manufacture personal opinions, feelings, stories, humor, or first-person experience merely to make the prose sound human.
-
-### Technical documentation
-
-Apply these rules when writing, editing, or reviewing eve's documentation:
-
-- Identify the audience, goal, and content type before writing. Keep each page focused on one job and read nearby docs for established terminology and structure.
-- Verify behavior against the code or an authoritative source. Never invent examples, measurements, implementation details, or citations to make prose more specific.
-- Use a neutral, instructional voice. Address the reader as `you`, use imperative verbs for steps, and do not add personal reactions, humor, tangents, or first-person experience.
-- Prefer active voice, present tense, concrete verbs, and consistent terms. Do not describe a reader's task as `easy`, `simple`, or `quick`.
-- Open with a short summary of what the page helps the reader do. Use sentence case and descriptive headings, focused paragraphs, and lists when they improve scanning.
-- Define unfamiliar terms and spell out acronyms on first use. Use inline code for paths and identifiers, and reserve bold for user interface elements or critical facts.
-- Prefer TypeScript examples unless the subject is language-agnostic. Add a language tag, explain each example, and keep it minimal, runnable, and consistent with the current API.
-- Use descriptive link text and placeholders such as `your_access_token_here`. Avoid bare URLs, `here`, `<TOKEN>`, and unexplained values.
-- For review-only requests, group concise findings by file and include a clickable `file:line` location. If a file passes, report `✓ pass`.
-
-Follow repository conventions when they conflict with these rules.
-
-## Protect the writer
-
-- Preserve the meaning, facts, nuance, uncertainty, and intent.
-- Never invent claims, examples, statistics, dates, sources, quotations, product details, opinions, or reactions. Add specificity only when the source material supports it. Otherwise preserve the uncertainty, cut the unsupported claim, or flag what is missing.
-- Preserve characteristic vocabulary, cadence, bluntness, humor, fragments, digressions, profanity, and rough edges when they are clear and purposeful.
-- Leave strong sentences alone. Do not normalize every paragraph into the same shape or level of polish.
-- Treat every pattern below as a contextual warning, not a mechanical ban. Keep an intentional construction when it suits the voice, audience, or house style.
-
-## Improve the prose
-
-- Lead with the point when the setup adds nothing. Keep setup that creates necessary context, tension, or character.
-- Prefer concrete nouns, direct verbs, and supported details over abstractions and inflated claims.
-- Use active voice when it is clearer, but allow natural inanimate subjects such as "the test catches regressions" or "the report shows."
-- Make each sentence earn its place. Cut repetition, filler, and empty qualifiers without deleting real nuance or uncertainty.
-- Untangle sentences that are hard to follow. Preserve clear long sentences, fragments, and rhythm changes that belong to the writer.
-- Keep the original structure unless reorganizing materially improves the piece. Explain meaningful restructuring in **What changed**.
-- Read the result aloud in your head. Vary rhythm where it feels robotic, not simply for variety's sake.
-
-## Patterns to inspect
-
-### Empty importance and abstraction
-
-- **Importance puffery:** "stands as a testament," "marks a pivotal moment," "plays a vital role," "underscores its significance," or claims about a broader landscape that add no information. State the supported fact and let the reader judge its importance.
-- **Promotional language:** "vibrant," "groundbreaking," "renowned," "breathtaking," "rich tapestry," "commitment to excellence," or similar praise without evidence. Replace it with concrete description.
-- **Notability padding:** lists of media outlets, follower counts, or claims of an "active social media presence" that do not support the point. Use the specific relevant coverage or omit it.
-- **Superficial analysis:** trailing `-ing` clauses such as "highlighting," "showcasing," "reflecting," or "underscoring" that pretend to explain significance. State a real mechanism or consequence when the draft provides one.
-- **Weasel attribution:** "experts agree," "studies show," "industry reports suggest," or "many argue." Name a supplied source, remove the attribution, or flag that a source is needed.
-- **Formulaic challenges and outlooks:** generic "Despite these challenges" or "Future outlook" passages. Keep only concrete problems, responses, plans, or unknowns supported by the draft.
-
-### Stock rhetorical moves
-
-- **Binary contrasts:** "It's not X. It's Y," "not only X but Y," and "the question isn't X, it's Y." State the point directly unless the contrast carries real meaning or voice.
-- **Throat-clearing:** "Here's the thing," "Let me be clear," "The truth is," or "It's worth noting." Cut the setup when the following sentence works alone.
-- **Faux-insight setups:** "What nobody tells you," "the part everyone misses," or "what most people get wrong." Make the claim stand on its own.
-- **Colon reveals:** "The best part: it learns" or "The reason: distribution." Use a plain sentence unless the colon introduces a real list, label, explanation, or quotation.
-- **Rhetorical setups:** "What if I told you," "Think about it," "Plot twist," or a self-answered question used only for drama. State the point.
-- **Negative listings:** "Not a tool. Not a feature. A revolution." Say what the thing is.
-- **Dramatic fragmentation:** stacks such as "That's it. That's the whole thing" or "And speed. And control. And scale." Join them when the fragments are decorative rather than expressive.
-- **Forced groups of three:** trios chosen for cadence instead of meaning. Keep natural lists of any length; remove redundant items.
-- **False ranges:** "from X to Y" when the endpoints do not form a meaningful scale or progression. Name the actual topics.
-
-### Mechanical diction
-
-- **AI vocabulary clusters:** repeated use of words such as "delve," "foster," "leverage," "robust," "seamless," "transformative," "multifaceted," "intricate," "pivotal," "tapestry," or an abstract "landscape." Replace empty uses, but preserve legitimate technical terms, quotations, names, and deliberate diction.
-- **Fake-strong verbs:** "serves as," "stands as," "boasts," "features," or "offers" when "is," "has," or a more specific verb is clearer.
-- **Synonym cycling:** rotating among "agent," "assistant," "tool," and "system" merely to avoid repetition. Repeat the clearest term.
-- **Filler and swollen phrases:** "in order to," "due to the fact that," "at this point in time," "has the ability to," or "in terms of." Prefer the shorter equivalent when meaning stays intact.
-- **Stacked hedging:** "could potentially possibly" or layers of qualifiers. Keep the amount of uncertainty the evidence requires.
-- **Chatbot artifacts:** "Of course," "I hope this helps," "let me know," canned praise, knowledge-cutoff disclaimers, or offers to continue that escaped into the document. Remove them unless the format is genuinely conversational.
-
-### Mechanical structure and endings
-
-- **Robotic rhythm:** repeated sentence shapes, identical paragraph structures, or stacks of equally punchy fragments. Adjust only enough to restore a natural cadence.
-- **Fake-profound endings:** a final metaphor, aphorism, or mic-drop line that inflates the preceding point. End on the strongest concrete fact, takeaway, or next action already supported by the draft.
-- **Summary-recap endings:** "In conclusion," "Ultimately," or a final paragraph that only repeats what the reader just read. Cut it unless the format requires a summary.
-- **Formatting decoration:** emoji headings, scattered bold emphasis, unnecessary micro-headings, or bullet lists that would read better as short prose. Follow the content and the document's house style.
-- **Punctuation habits:** clusters of em dashes, dramatic colons, or other repeated punctuation used as a rhythm crutch. Keep punctuation that improves clarity. Follow the requested house style for quotation marks, heading capitalization, and similar typography.
-
-## Workflow
-
-1. Determine whether the request is edit, detect, or draft.
-2. Read the full source before changing or judging it.
-3. Identify the core point and the writer's voice signals. Keep this note internal.
-4. Make only changes supported by the source and the requested mode.
-5. Read `eval.md` completely and check the result against it. Revise any failure before responding.
-6. Return the output required by the selected mode. Do not print the evaluation unless the user asks for it.
diff --git a/.agents/skills/human-writing/eval.md b/.agents/skills/human-writing/eval.md
deleted file mode 100644
index 81e4c2a21..000000000
--- a/.agents/skills/human-writing/eval.md
+++ /dev/null
@@ -1,42 +0,0 @@
-# Human writing evaluation
-
-Run this checklist internally after editing, detecting, or drafting. Treat every item as pass or fail. Fix failures before responding, and do not print the checklist unless the user asks for it.
-
-## Fidelity and voice
-
-1. Does the result preserve the writer's point, intent, facts, nuance, and necessary uncertainty?
-2. Does every claim, example, statistic, date, source, quotation, product detail, opinion, and reaction come from the source or the user's brief?
-3. Does the result preserve distinctive vocabulary, cadence, bluntness, humor, fragments, digressions, profanity, and useful rough edges?
-4. Would the writer recognize the result as their own voice?
-5. Did the edit leave strong human sentences alone and make only proportional changes?
-
-## Clarity and substance
-
-1. Does the piece lead with what its audience needs while retaining setup that adds context, tension, or character?
-2. Are tangled sentences fixed without flattening clear spoken cadence?
-3. Are concrete, supported details protected rather than replaced with generic claims?
-4. Do direct verbs and natural subjects carry the prose where they improve clarity?
-5. Does each remaining sentence contribute information, reasoning, voice, or necessary transition?
-
-## Pattern check
-
-1. Are unsupported importance, promotional claims, notability padding, superficial analysis, vague attribution, and formulaic outlooks removed or flagged?
-2. Are stock contrasts, throat-clearing, faux insights, colon reveals, rhetorical setups, negative listings, decorative fragments, forced trios, and false ranges fixed when they add no value?
-3. Are empty vocabulary clusters, fake-strong verbs, synonym cycling, filler, stacked hedging, and chatbot artifacts removed without banning legitimate language?
-4. Are robotic rhythm, fake-profound endings, redundant conclusions, decorative formatting, and punctuation crutches corrected where appropriate?
-5. Were intentional constructions and required house-style choices preserved?
-
-## Technical documentation
-
-1. Does the page have a clear audience and goal, use established terminology, and stay focused on one job?
-2. Are technical claims and code examples accurate, current, and supported by the code or an authoritative source?
-3. Does the page use a neutral instructional voice, descriptive sentence-case headings, and formatting that supports scanning?
-4. Are code examples minimal, explained, language-tagged, and consistent with repository conventions?
-5. For a review, does each finding include a concise, clickable `file:line` location?
-
-## Response contract
-
-1. For an edit, is the full edited draft present, followed by a short **What changed** section unless the user requested clean copy only?
-2. For detection, does each finding name a pattern, quote the affected text, and suggest a brief fix without rewriting, scoring, or claiming AI authorship?
-3. For a draft, does the prose follow the requested audience, format, tone, and supplied voice without inventing personal experience?
-4. Is the evaluation omitted unless the user requested it?
diff --git a/.agents/skills/technical-writing/SKILL.md b/.agents/skills/technical-writing/SKILL.md
new file mode 100644
index 000000000..766026488
--- /dev/null
+++ b/.agents/skills/technical-writing/SKILL.md
@@ -0,0 +1,76 @@
+---
+name: technical-writing
+description: Write, edit, review, or audit user-facing documentation for the eve repository. Use for changes under docs/, documentation tied to eve APIs or CLI behavior, docs work based on Slack or support feedback, and requests to make eve docs clearer, more natural, or less AI-patterned while verifying claims against current source, tests, CLI help, public releases, and repository conventions.
+---
+
+# Technical writing
+
+Write accurate, task-focused documentation for eve. Treat developers and AI agents as readers: make each section easy to scan, retrieve, and act on without relying on unstated context.
+
+## Choose a workflow
+
+- For a new page or full rewrite, read [references/writing-workflow.md](references/writing-workflow.md).
+- For targeted or structural changes to existing pages, read [references/editing-workflow.md](references/editing-workflow.md).
+- Before finalizing any change, read [references/review-framework.md](references/review-framework.md).
+- For formatting and terminology, read [references/style-rules.md](references/style-rules.md).
+- For wording, voice, or AI-pattern concerns, read [references/prose-quality.md](references/prose-quality.md).
+- For page structure, read [references/content-types.md](references/content-types.md) when the content type is unclear or changing.
+
+## Verify before writing
+
+Do not rely on training data for eve behavior. Use this source hierarchy:
+
+1. Current source, public types, and tests in `packages/eve`
+2. Current CLI help and setup implementation
+3. Existing pages under `docs/`
+4. Merged pull requests, changelogs, and release notes
+5. Research plans under `research/` as proposed intent, not shipped behavior
+6. Support evidence such as Slack threads or issues
+
+Use support evidence to identify the reader's problem, not to establish product behavior. Verify commands, flags, API names, defaults, limitations, and examples against the current repository. For a docs-only change, also compare the implementation with the latest public release so the docs do not announce branch-only behavior. When docs accompany product code in the same change, state that dependency during review. If a claim cannot be verified, omit it or report the missing owner or source. Never leave `[VERIFY]` markers in a completed docs change.
+
+## Follow eve conventions
+
+- Write `eve` lowercase, including headings and sentence starts when practical.
+- Use exact public names such as `defineAgent`, `eve dev`, and `eve add channel/slack`.
+- Distinguish the root agent, the built-in `agent` tool, declared subagents, and remote agents. They have different inheritance and execution semantics.
+- Distinguish eve connections from Vercel Connect, the model-facing `Workflow` tool from authored Vercel Workflows, and durable session state from sandbox filesystem or attachment storage.
+- Name diagnostic surfaces precisely: Vercel runtime logs, **Agent Runs**, OpenTelemetry, `eve logs`, and `eve traces` are not interchangeable.
+- Treat `docs/**` as published documentation. Update `docs/meta.json` when navigation changes.
+- Keep `.md` files framework-agnostic. Use MDX components only in `.mdx` files and only when nearby pages establish the convention.
+- Preserve published routes and heading anchors when possible. When moving a page, update authored links and add permanent redirects for old HTML and Markdown URLs.
+- Prefer TypeScript examples. Include imports and language labels, and verify examples against current exports.
+- Show only supported commands and flags. Check CLI help or the command implementation before documenting them.
+- Link to related pages with descriptive text. Include the critical fact locally because retrieved sections may be read without their links.
+- Do not document proposed behavior as shipped. Describe unsupported boundaries directly when they affect a user task.
+
+## Write for the task
+
+- Lead each page and section with the answer or outcome.
+- Address the reader as `you`; use imperative verbs for steps.
+- Prefer active voice, present tense, concrete nouns, and consistent terms.
+- Preserve the author's supported meaning, nuance, and uncertainty. Make the minimum effective edit and leave strong prose alone.
+- Keep one page focused on one primary job. Add a section to an existing page when it already owns the task.
+- Put the happy path before alternatives and failure modes.
+- Add troubleshooting where observed failures cluster around a workflow. Use symptoms, verified causes, and concrete next checks.
+- Write self-contained sections. Repeat the full noun in key statements instead of relying on ambiguous pronouns.
+- Use specific limits and behavior only when the repository or an authoritative platform source supports them.
+
+## Avoid common failures
+
+- Do not invent flags, registry entries, connectors, workarounds, or platform guarantees.
+- Do not turn one product request into a new page. First decide whether the gap belongs to docs, product, or both.
+- Do not duplicate broad guides when a focused section or cross-link resolves the problem.
+- Do not rewrite clear prose merely to match a personal preference.
+- Do not manufacture examples, opinions, reactions, or specificity to make prose sound more human.
+- Do not use promotional language, rhetorical questions, filler, or claims that a task is easy, simple, or quick.
+- Do not use `we` unless describing a deliberate Vercel or eve team action.
+
+## Finish the change
+
+1. Re-read every changed page in full.
+2. Verify each new technical claim against its source.
+3. Search for contradictory statements and affected cross-links.
+4. Run the review workflow.
+5. Check changed prose against the prose-quality reference when wording changed materially.
+6. Run `pnpm docs:check` when preparing to push, unless the user requests earlier validation.
diff --git a/.agents/skills/technical-writing/agents/openai.yaml b/.agents/skills/technical-writing/agents/openai.yaml
new file mode 100644
index 000000000..1c9554a3e
--- /dev/null
+++ b/.agents/skills/technical-writing/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+ display_name: "Technical writing"
+ short_description: "Write accurate, clear, task-focused eve docs"
+ default_prompt: "Use $technical-writing to write or improve eve documentation, verify every technical claim, and keep the prose direct and natural."
diff --git a/.agents/skills/technical-writing/references/content-types.md b/.agents/skills/technical-writing/references/content-types.md
new file mode 100644
index 000000000..ad907558d
--- /dev/null
+++ b/.agents/skills/technical-writing/references/content-types.md
@@ -0,0 +1,30 @@
+# eve documentation content types
+
+Use these categories as structural heuristics, not mandatory frontmatter.
+
+## Tutorial
+
+Teach through a complete, guided build. Include prerequisites, sequential steps, observable results, and next steps. Use a tutorial when learning is the goal.
+
+## How-to
+
+Help an experienced reader complete one task. Lead with the supported path, keep explanation proportional, and add focused troubleshooting for common failures.
+
+## Reference
+
+Document APIs, CLI commands, configuration, limits, or schemas for lookup. Use exact names, consistent tables, types, defaults, constraints, and verified examples.
+
+## Conceptual
+
+Explain how or why a system works. Define the mental model, boundaries, tradeoffs, and related tasks without turning the page into a procedural guide.
+
+## Decide whether to create a page
+
+Create a page only when all are true:
+
+- The reader has a distinct goal or question.
+- The behavior is shipped and stable enough to document.
+- The content cannot fit cleanly in an existing owner page.
+- The page has enough substance to stand alone.
+
+Otherwise, add a focused section, example, limitation, or cross-link to the existing page.
diff --git a/.agents/skills/technical-writing/references/editing-workflow.md b/.agents/skills/technical-writing/references/editing-workflow.md
new file mode 100644
index 000000000..345aaed2c
--- /dev/null
+++ b/.agents/skills/technical-writing/references/editing-workflow.md
@@ -0,0 +1,51 @@
+# Editing existing eve documentation
+
+## 1. Triage the edit
+
+Choose the smallest effective change:
+
+| Level | Signal | Action |
+| --------------- | ---------------------------------------------------------- | -------------------------------------- |
+| Quick fix | Incorrect command, broken link, typo, or stale name | Correct the affected text |
+| Copy edit | Ambiguous wording, weak hierarchy, or inconsistent terms | Improve clarity without changing scope |
+| Structural edit | Missing workflow stage, failure mode, or misplaced content | Reshape the affected page |
+| Rewrite | The page no longer serves its primary task | Use the writing workflow |
+
+Feedback frequency helps rank work, but severity also matters. A single security, data-governance, or destructive-workflow issue can justify a high-priority correction.
+
+## 2. Preserve context
+
+Before editing:
+
+- Read the full page and nearby pages.
+- Search for incoming links and repeated claims.
+- Preserve route paths and heading anchors when possible.
+- Check whether the request is a docs gap, product gap, or both.
+- Identify the exact source that verifies each changed behavior.
+
+## 3. Edit around the reader's task
+
+- Keep the established page structure unless it blocks the task.
+- Make the supported happy path primary.
+- Put alternatives after the happy path.
+- Add limitations next to the workflow they constrain.
+- Add troubleshooting to the page that owns the failing workflow.
+- Prefer one focused example over a new page.
+
+When support feedback drove the edit, deduplicate incidents into user problems before writing. Do not quote internal discussion or expose implementation history unless it helps the reader act.
+
+## 4. Verify accuracy
+
+Check commands against CLI help or their implementation. Check API examples against public exports and tests. Check deployment behavior against eve source and authoritative Vercel platform documentation.
+
+If product semantics remain unsettled, document only the stable boundary. Route recovery flows, guarantees, or matrices to the responsible product owner instead of guessing.
+
+## 5. Check adjacent content
+
+Search for:
+
+- Contradictory statements
+- Old command names or flags
+- Pages that describe the same workflow
+- Links to changed headings
+- Reference pages that need the same limitation or behavior
diff --git a/.agents/skills/technical-writing/references/prose-quality.md b/.agents/skills/technical-writing/references/prose-quality.md
new file mode 100644
index 000000000..a18329fc1
--- /dev/null
+++ b/.agents/skills/technical-writing/references/prose-quality.md
@@ -0,0 +1,47 @@
+# Prose quality
+
+Apply this pass after the technical claims and page structure are correct. The goal is clear, natural eve documentation, not a generic rewrite.
+
+## Preserve intent
+
+- Preserve supported meaning, facts, nuance, and necessary uncertainty.
+- Keep established eve terminology even when a synonym would add variety.
+- Leave strong sentences alone. Make the minimum effective edit.
+- Preserve useful detail instead of replacing it with broad summaries.
+- Do not invent examples, measurements, sources, opinions, reactions, or implementation details.
+- Match eve's neutral instructional voice rather than an individual author's casual voice.
+
+## Improve clarity
+
+- Lead with the point when setup adds no necessary context.
+- Prefer concrete nouns and direct verbs over abstractions and inflated claims.
+- Cut repetition, filler, and empty qualifiers without deleting real constraints.
+- Untangle sentences that require rereading, but keep clear long sentences when they carry necessary detail.
+- Vary rhythm only when repeated sentence shapes sound mechanical.
+
+## Inspect contextual warning signs
+
+Treat these as warnings, not mechanical bans. Keep an intentional construction when it is the clearest choice or matches repository style.
+
+- **Unsupported importance:** Remove claims that something is pivotal, transformative, or broadly significant unless evidence supports the consequence.
+- **Promotional language:** Replace praise such as seamless, robust, groundbreaking, or powerful with concrete behavior.
+- **Superficial analysis:** Remove trailing clauses such as “highlighting” or “underscoring” when they do not explain a mechanism or consequence.
+- **Vague attribution:** Name an authoritative supplied source or remove phrases such as “experts agree” and “studies show.”
+- **Stock rhetoric:** Remove throat-clearing, faux-insight setups, self-answered questions, decorative contrasts, negative lists, and colon reveals when the following statement works alone.
+- **Decorative rhythm:** Avoid stacked fragments, forced groups of three, false ranges, repeated sentence templates, and punctuation used only for emphasis.
+- **Mechanical diction:** Replace fake-strong verbs, synonym cycling, swollen phrases, stacked hedging, and generic AI vocabulary with the precise term.
+- **Chatbot artifacts:** Remove canned praise, offers to continue, knowledge-cutoff disclaimers, and “I hope this helps” language.
+- **Weak endings:** End on the last useful fact or next action instead of a redundant summary, slogan, metaphor, or “In conclusion” paragraph.
+- **Decorative formatting:** Remove scattered emphasis, unnecessary micro-headings, and lists that are clearer as short prose.
+
+## Final read
+
+Read the changed section in full, then check:
+
+1. Every claim still matches its source.
+2. The revision preserves the original intent and necessary uncertainty.
+3. Each sentence contributes information, reasoning, or a necessary transition.
+4. The prose sounds direct and natural when read aloud.
+5. The edit did not normalize unrelated or already-clear writing.
+
+For a review-only request, report concise findings with a clickable file and line. Do not assign an AI score or claim to know whether AI wrote the text.
diff --git a/.agents/skills/technical-writing/references/review-framework.md b/.agents/skills/technical-writing/references/review-framework.md
new file mode 100644
index 000000000..ffbf42f11
--- /dev/null
+++ b/.agents/skills/technical-writing/references/review-framework.md
@@ -0,0 +1,49 @@
+# Reviewing eve documentation
+
+Run separate passes. Fix blockers and major issues before style nits.
+
+## Pass 1: Purpose and structure
+
+- Does the page have one primary job?
+- Does the introduction lead with the outcome or definition?
+- Does the heading order match the reader's workflow?
+- Does the content belong on this page rather than a new page?
+
+## Pass 2: Technical accuracy
+
+- Do commands and flags match current CLI help or implementation?
+- Do API names, imports, defaults, and examples match current public source and tests?
+- Are limitations explicit and current?
+- Does any statement describe unmerged or proposed behavior as shipped?
+- For docs-only work, is each new behavior present in the latest public release rather than only on the current branch?
+- Do platform claims have an authoritative owner or source?
+
+Treat a wrong command, nonexistent API, unsafe instruction, or false guarantee as a blocker.
+
+## Pass 3: Completeness
+
+- Can the reader complete the supported happy path?
+- Are prerequisites and environment assumptions clear?
+- Are repeated real-world failure modes covered?
+- Does troubleshooting tell the reader what to inspect next?
+- Are product gaps separated from docs guidance?
+
+## Pass 4: Style and retrieval
+
+- Is `eve` lowercase?
+- Are terms consistent with code and CLI output?
+- Does each section lead with its key fact?
+- Are headings descriptive enough to work as search results?
+- Is critical information present locally rather than only behind links?
+- Are sentences direct, active, and free of promotional or robotic phrasing?
+- Did the edit preserve supported meaning, nuance, uncertainty, and strong existing prose?
+- Are stock rhetorical patterns, filler, inflated claims, and mechanical rhythm removed where they add no value?
+
+## Pass 5: Diff discipline
+
+- Does every changed sentence fix an accuracy, usability, structure, or style problem?
+- Did the edit preserve unrelated working content and anchors?
+- Did it create contradictions elsewhere?
+- Are all new files necessary?
+
+Leave clear, correct prose unchanged.
diff --git a/.agents/skills/technical-writing/references/style-rules.md b/.agents/skills/technical-writing/references/style-rules.md
new file mode 100644
index 000000000..086676a24
--- /dev/null
+++ b/.agents/skills/technical-writing/references/style-rules.md
@@ -0,0 +1,51 @@
+# eve documentation style
+
+## Names and capitalization
+
+- Write `eve` lowercase.
+- Match public API, CLI, provider, and product names exactly.
+- Use sentence case for headings.
+- Use American English and the Oxford comma.
+
+## Voice
+
+- Address the reader as `you` when the reader acts.
+- Use imperative verbs for steps.
+- Prefer active voice and present tense.
+- Use neutral, instructional language.
+- Avoid `easy`, `simple`, `quick`, `just`, `obviously`, `utilize`, `facilitate`, `leverage`, `robust`, and `seamless`.
+- Avoid rhetorical questions, filler introductions, stacked fragments, and promotional claims.
+
+## Formatting
+
+- Use inline code for commands, flags, APIs, paths, filenames, and literal values.
+- Use bold for interface labels or a critical fact, not routine emphasis.
+- Add language identifiers to fenced code blocks.
+- Use descriptive link text instead of `here` or bare URLs.
+- Use Markdown in `.md`; use MDX-only syntax only in `.mdx`.
+- Follow nearby docs for frontmatter and component conventions.
+
+## Code and commands
+
+- Prefer TypeScript unless the subject is language-agnostic.
+- Include imports and enough context for examples to compile or run.
+- Use placeholders such as `your_access_token_here` when readers must substitute values.
+- Verify CLI syntax against current help or implementation.
+- Do not invent expected output. Show it only when stable and useful.
+
+## Lists and tables
+
+- Use numbered lists for ordered procedures and bullets for related unordered information.
+- Start procedure steps with one imperative action.
+- Use tables when readers compare repeated fields or symptoms; keep column schemas consistent.
+- Write complete sentences with periods when list items contain explanations.
+
+## Troubleshooting
+
+Use a symptom-first table when several failures share a workflow:
+
+| Symptom | Check | Next action |
+| ------------------ | --------------------------- | ----------------------- |
+| Observable failure | Verified diagnostic surface | Supported recovery step |
+
+Do not state a cause unless evidence supports it. When several causes produce the same symptom, tell the reader how to distinguish them.
diff --git a/.agents/skills/technical-writing/references/writing-workflow.md b/.agents/skills/technical-writing/references/writing-workflow.md
new file mode 100644
index 000000000..e1d4347b8
--- /dev/null
+++ b/.agents/skills/technical-writing/references/writing-workflow.md
@@ -0,0 +1,45 @@
+# Writing new eve documentation
+
+## 1. Research the task
+
+Identify:
+
+- What the reader needs to accomplish or understand
+- Where the task begins and ends
+- Current source, tests, CLI help, or platform documentation that verifies it
+- Existing eve pages that overlap
+- Common failures from support evidence
+- Product work that is not yet shipped
+
+Do not draft until the supported workflow and its boundaries are clear.
+
+## 2. Choose one content type and job
+
+Use [content-types.md](content-types.md) as a structural heuristic. Do not add `contentType` frontmatter solely because this skill categorizes the page.
+
+Prefer extending an existing owner page. Create a page only when the topic has a distinct user goal, enough stable content, and no clear existing home.
+
+## 3. Outline before drafting
+
+Write the headings first. Order them around the reader's workflow:
+
+1. Outcome or definition
+2. Prerequisites or boundaries
+3. Supported happy path
+4. Alternatives
+5. Failure modes or limitations
+6. Related tasks
+
+For a small page, omit sections that add no value.
+
+## 4. Draft and verify together
+
+- Verify every command, flag, identifier, and example before adding it.
+- Prefer complete TypeScript examples with current imports.
+- Explain what a command changes and what success looks like when that is stable and observable.
+- Use exact terms that match code and CLI output.
+- Separate current behavior from proposed product work.
+
+## 5. Self-edit
+
+Remove repetition, filler, unsupported qualifiers, and implementation detail the reader cannot act on. Confirm that each section makes sense when retrieved independently.
diff --git a/docs/channels/chat-sdk.mdx b/docs/channels/chat-sdk.mdx
index f63b25327..18466a52d 100644
--- a/docs/channels/chat-sdk.mdx
+++ b/docs/channels/chat-sdk.mdx
@@ -5,7 +5,7 @@ description: "Bridge any Vercel Chat SDK adapter — Slack, Discord, Telegram, W
The Chat SDK channel connects your agent to any [Vercel Chat SDK](https://chat-sdk.dev) adapter. You pick an adapter (`@chat-adapter/slack`, `@resend/chat-sdk-adapter`, and so on), register handlers for the messages you care about, and call `send` to hand each turn to eve. Use it to reach a surface eve does not ship a first-class channel for, or when you want to manage credentials and state with the Chat SDK's own primitives rather than [Vercel Connect](../guides/auth-and-route-protection). See [Channels](./overview) for the contract this builds on.
-You supply an adapter and a state store: the adapter owns provider auth, webhook verification, and delivery, while eve owns session dispatch, streaming, typing, and human-in-the-loop. First-class channels such as [Slack](./slack) manage credentials through Vercel Connect instead — reach for whichever fits the surface you are targeting.
+You supply an adapter and a state store: the adapter owns provider auth, webhook verification, and delivery, while eve owns session dispatch, streaming, typing, and human-in-the-loop. First-class channels such as [Slack](./slack) use their own channel APIs and can manage credentials through Vercel Connect or environment variables you configure directly.
## Install
diff --git a/docs/channels/github.mdx b/docs/channels/github.mdx
index 7ab3c0441..756090e8b 100644
--- a/docs/channels/github.mdx
+++ b/docs/channels/github.mdx
@@ -14,7 +14,7 @@ Run the registry setup from the agent directory:
eve add channel/github
```
-The flow checks that the Vercel CLI is authenticated, creates or links a Vercel project when needed, provisions an app-scoped GitHub Connect client, and replaces its default trigger with `/eve/v1/github`. It then installs `@vercel/connect` and writes `agent/channels/github.ts` with the connector UID.
+The flow checks that the Vercel CLI is authenticated, creates or links a Vercel project when needed, provisions an app-scoped GitHub Connect client, and registers `/eve/v1/github` as a trigger destination. It then installs `@vercel/connect` and writes `agent/channels/github.ts` with the connector UID.
Vercel Connect creates the GitHub App, receives and verifies its webhooks, and forwards them to the deployed agent. After deploying, open the GitHub App in the Connect dashboard and install it in the organization or account where you want to use it. Add the generated invocation token (for example, `@my-agent`) to a new issue, pull request, or review comment to start a conversation. GitHub may not autocomplete the token or render it as a linked mention.
diff --git a/docs/channels/linear.mdx b/docs/channels/linear.mdx
index 0129aa29d..6314003d9 100644
--- a/docs/channels/linear.mdx
+++ b/docs/channels/linear.mdx
@@ -16,7 +16,7 @@ eve add linear
Select **Linear Channel** in the component checklist. **Linear MCP** is also selected by default if you want the agent to search and update Linear through MCP. Run `eve add channel/linear-agent` instead to install only the channel directly.
-The flow checks that the Vercel CLI is authenticated, creates or links a Vercel project when needed, reuses a compatible existing connector when available or provisions an app-scoped Linear Connect client, and replaces its default trigger with `/eve/v1/linear`. It then installs `@vercel/connect` and writes `agent/channels/linear.ts` with the connector UID.
+The flow checks that the Vercel CLI is authenticated, creates or links a Vercel project when needed, reuses a compatible existing connector when available or provisions an app-scoped Linear Connect client, and registers `/eve/v1/linear` as a trigger destination. It then installs `@vercel/connect` and writes `agent/channels/linear.ts` with the connector UID.
Vercel Connect creates the Linear app with the `app:assignable` and `app:mentionable` scopes required for Agent Sessions, receives and verifies `AgentSessionEvent` webhooks, and forwards them to the deployed agent. After deploying, open the Linear app in the Connect dashboard and install it in the workspace where you want to delegate work. Then delegate an issue or mention the agent in a Linear Agent Session.
diff --git a/docs/channels/overview.mdx b/docs/channels/overview.mdx
index 33603f572..9c51735c5 100644
--- a/docs/channels/overview.mdx
+++ b/docs/channels/overview.mdx
@@ -40,9 +40,9 @@ When eve doesn't ship a channel for your surface, build one with `defineChannel`
## Relationship to the Chat SDK
-eve uses the Chat SDK's **card-builder components** (Cards, Buttons, Actions, etc.) for composing rich Slack messages. When you build a card with the [Slack channel](./slack), the underlying primitives come from the Chat SDK and get converted to Slack Block Kit at post time.
+eve uses the [Chat SDK's card-builder components](https://chat-sdk.dev/docs/api/cards) (Cards, Buttons, Actions, etc.) for composing rich Slack messages. When you build a card with the [Slack channel](./slack), the underlying primitives come from the Chat SDK and get converted to Slack Block Kit at post time.
-eve does **not** use the Chat SDK's runtime. The `Chat`, `Adapter`, and `Thread` primitives are never imported or reachable through eve's public API. eve implements its own channel layer (webhook handling, signature verification, event parsing, and thread management). Building Slack messages works like Chat SDK cards, but wiring a channel means authoring against eve's `defineChannel(...)` API, not a Chat SDK adapter.
+eve's first-class channels use eve-owned runtimes for webhook handling, verification, event parsing, and thread management. The optional [Chat SDK channel](./chat-sdk) is the exception: it accepts a Chat SDK adapter and exposes its `Chat` and `Thread` primitives. Use `slackChannel` for eve's first-class Slack integration, `defineChannel(...)` for an eve-native custom channel, or `chatSdkChannel` when you intentionally want a Chat SDK adapter and runtime.
## Which channel?
diff --git a/docs/channels/slack.mdx b/docs/channels/slack.mdx
index 7d65f7add..89268bdbe 100644
--- a/docs/channels/slack.mdx
+++ b/docs/channels/slack.mdx
@@ -1,31 +1,26 @@
---
title: "Slack"
-description: "Reach your agent from Slack app mentions and DMs, with thread anchoring, buttons, and Vercel Connect credentials."
+description: "Reach your agent from Slack app mentions and DMs with Vercel Connect-managed credentials, threaded replies, and interactive buttons."
type: integration
---
-The Slack channel puts your agent inside a workspace. It answers `@mentions` and DMs, replies in threads, shows typing indicators, and turns human-in-the-loop (HITL) prompts into buttons. Use it when the conversation should happen where your team already works. Credentials run through [Vercel Connect](../guides/auth-and-route-protection), which handles both the outbound bot token and inbound webhook verification, so there's no `SLACK_BOT_TOKEN` or `SLACK_SIGNING_SECRET` for you to manage. See [Channels](./overview) for the contract this builds on.
+The Slack channel puts your agent inside a workspace. It answers `@mentions` and DMs, replies in threads, shows typing indicators, and turns human-in-the-loop (HITL) prompts into buttons. [Vercel Connect](https://vercel.com/kb/guide/vercel-connect) is the recommended setup: it manages the Slack bot token, verifies inbound requests, supports token rotation and multiple workspace installations, and forwards events to your agent without copying Slack secrets into your project environment. If you cannot use Vercel Connect, you can provide the bot token and signing secret through environment variables. See [Channels](./overview) for the contract this builds on.
-## Set up Connect
+## Add the channel
-Create a Slack Connect client and copy its UID (e.g. `slack/my-agent`), then attach this project as the trigger destination at eve's Slack route:
+Run the guided setup from your agent project:
```bash
-npm install -g vercel@latest
-vercel connect create slack --triggers
-vercel connect detach <uid> --yes
-vercel connect attach <uid> --triggers --trigger-path /eve/v1/slack --yes
+eve add channel/slack
```
-The `create` step provisions a destination at the default Connect path. `detach` then `attach --trigger-path /eve/v1/slack` re-points the trigger at the eve Slack route, since eve does not serve the default Connect path. `--triggers` turns on Slack Event Subscriptions; without it, Slack never delivers `app_mention` or `message.im`. You can also create the client from the [Connect dashboard](https://vercel.com/d?to=/%5Bteam%5D/~/connect&title=Go+to+Connect).
+The command recommends Vercel Connect, then scaffolds `agent/channels/slack.ts` and installs any required dependency. Choose the environment-variable option only when you need to manage the Slack bot token and signing secret yourself.
-## Add the channel
+### Recommended: use Vercel Connect
-Scaffold the channel and its dependency with `eve add channel/slack`, or set it up by hand:
+Vercel Connect setup requires an authenticated Vercel CLI and a linked Vercel project. The guided flow creates or reuses a Slack connector, waits for you to install it in a workspace, and registers `/eve/v1/slack` as a trigger destination before writing the channel file.
-```bash
-npm install @vercel/connect
-```
+The generated channel resolves credentials at runtime:
```ts title="agent/channels/slack.ts"
import { connectSlackCredentials } from "@vercel/connect/eve";
@@ -38,17 +33,93 @@ export default slackChannel({
`connectSlackCredentials` returns `{ botToken, webhookVerifier }`, keeping token rotation, multi-workspace tenancy, and request verification inside Connect rather than your code.
-If eve cannot find an authenticated Vercel session, `eve add channel/slack` asks whether to set up Vercel Connect or use portable environment credentials. The portable option adds the required names to `.env.example`. Before deploying, appropriate values must be supplied to your runtime environment.
+### Manage Slack credentials yourself
+
+Use this fallback when the agent does not run on Vercel or Vercel Connect is unavailable. In the setup command, **Use portable credentials** is the environment-variable option; eve adds `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` to `.env.example`.
+
+This option does not create or install the Slack app. Configure it in [Slack app settings](https://api.slack.com/apps):
-### Deploy
+1. Add the `app_mentions:read` and `chat:write` bot scopes. Add `im:history` for DMs, `files:read` for inbound attachments, and `files:write` when the agent uploads files.
+2. Install or reinstall the app, copy its Bot User OAuth Token to `SLACK_BOT_TOKEN`, and copy the signing secret from **Basic Information** to `SLACK_SIGNING_SECRET`.
+3. Set both values in `.env.local` for local development or in the target runtime's environment, then start or deploy the agent at a public URL.
+4. Under **Event Subscriptions**, set the Request URL to `https://your-agent.example/eve/v1/slack`. Subscribe to `app_mention`, plus `message.im` for DMs.
+5. Under **Interactivity & Shortcuts**, use the same Request URL when the agent uses buttons or HITL prompts.
-Deploy once the trigger destination and channel file are ready:
+Add the matching message events and history scopes if you also want unmentioned thread replies, as described in [Continue conversations without repeated mentions](#continue-conversations-without-repeated-mentions).
+
+## Deploy
+
+Deploy the production agent after the trigger destination and channel file are ready:
```bash
-VERCEL_USE_EXPERIMENTAL_FRAMEWORKS=1 vercel deploy --prod
+eve deploy
```
-`VERCEL_USE_EXPERIMENTAL_FRAMEWORKS=1` lets the Vercel CLI recognize eve as a framework during the build. eve's own setup commands set the same flag.
+`eve deploy` deploys the linked Vercel project to production. The guided flow registers the trigger destination against the production branch, which is the Vercel CLI default. Manage trigger destinations separately in the Connect dashboard when you need a different branch or environment.
+
+## Test a preview branch with Vercel Connect
+
+Use a separate connector when you want preview Slack traffic isolated from production, then register the preview branch as a trigger destination:
+
+```bash
+npm install -g vercel@latest
+vercel connect create slack --name your-agent-preview --triggers
+vercel connect attach slack/your-agent-preview \
+ --environment preview \
+ --triggers \
+ --trigger-branch your-preview-branch \
+ --trigger-path /eve/v1/slack \
+ --yes
+```
+
+Run these commands from the linked project directory. `--environment preview` makes the connector credentials available to Preview deployments. `--trigger-branch` selects the branch that receives forwarded Slack webhooks.
+
+Select the matching connector at runtime instead of leaving the generated production UID hard-coded:
+
+```ts title="agent/channels/slack.ts"
+import { connectSlackCredentials } from "@vercel/connect/eve";
+import { slackChannel } from "eve/channels/slack";
+
+const connectorUid =
+ process.env.VERCEL_ENV === "preview" ? "slack/your-agent-preview" : "slack/my-agent";
+
+export default slackChannel({
+ credentials: connectSlackCredentials(connectorUid),
+});
+```
+
+Creating a connector with triggers also registers a default production destination. Remove that destination from the Connect dashboard before treating the preview connector as isolated. The guided production setup does not restrict credential environments, so also set the production connector's project access to **Production** and the preview connector's access to **Preview** in the dashboard. `vercel connect detach` removes project token access, not trigger destinations. Vercel Connect supports up to three trigger destinations per connector; see the [Vercel Connect guide](https://vercel.com/kb/guide/vercel-connect) for current limits and environment guidance.
+
+Slack must be able to reach the preview route without an interactive authentication challenge. For a Connect trigger, exempt the branch domain with a [Deployment Protection Exception](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/deployment-protection-exceptions) when that feature is available, or use an unprotected preview domain. For a Slack app that uses environment-variable credentials, append `?x-vercel-protection-bypass=your-generated-secret` to its event and interaction request URLs. Enabling [Protection Bypass for Automation](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation) does not bypass a request unless the sender presents that secret.
+
+## Set up Vercel Connect manually
+
+To set up the connector outside the guided flow, create it, then register eve's Slack route with the linked project:
+
+```bash
+npm install -g vercel@latest
+vercel connect create slack --name your-agent --triggers
+vercel connect attach slack/your-agent \
+ --environment production \
+ --triggers \
+ --trigger-path /eve/v1/slack \
+ --yes
+```
+
+`--triggers` enables Slack Event Subscriptions. The attach command registers eve's route in addition to the default destination created with the connector. Remove the default destination separately in the [Connect dashboard](https://vercel.com/d?to=/%5Bteam%5D/~/connect&title=Go+to+Connect). For an existing connector, skip `create` and attach the intended route directly.
+
+## Troubleshoot Slack delivery
+
+Check the delivery path in order so you can identify where a Slack event stops:
+
+| Symptom | Check | Next action |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eve add channel/slack` stops before scaffolding the channel | Read the setup error for the failed Vercel login, project link, workspace install, connector lookup, or trigger registration step. | Resolve that step, then rerun `eve add channel/slack`. |
+| Setup says it could not remove an existing trigger destination | Check the connector's destinations in the Connect dashboard. `vercel connect detach` removes project token access, not trigger destinations. | Edit or remove the stale destination in the dashboard, then register `/eve/v1/slack` with `vercel connect attach`. |
+| Mentions never reach the deployment | Confirm that the connector trigger destination uses the intended project and branch, enables triggers, and points to `/eve/v1/slack`. | Edit or remove stale destinations in the Connect dashboard, then register the intended destination with `vercel connect attach`. |
+| Mentions work but DMs or thread replies do not | Check the Slack app's Event Subscriptions and OAuth scopes. DMs require `message.im` and `im:history`; channel replies require the matching message event and history scope. | Add the missing events or scopes, then reinstall the Slack app if Slack requires it. |
+| A preview request receives an authentication page or protection error | Check whether the branch domain is exempt or the direct Slack request URL includes `x-vercel-protection-bypass`. Slack cannot complete an interactive Vercel Authentication challenge. | Add a Deployment Protection Exception for the branch domain, or add the automation bypass query parameter to a Slack app that uses environment-variable credentials. |
+| The webhook reaches the deployment but the agent does not reply | Open the project's Vercel runtime logs, then inspect the session in **Agent Runs** when your team has access. | Use the first missing or failed stage to narrow the issue to channel dispatch, the agent run, or outbound Slack delivery. |
## How the channel handles inbound events
@@ -71,6 +142,43 @@ Only the first available handler runs. A message hook returning `null` drops the
`onInteraction(action, ctx)` separately handles `block_actions` callbacks not consumed by HITL. eve attaches the triggering Slack user id to the same model message as its text, preserving speaker attribution without profile lookups.
+#### Restrict who can invoke the agent
+
+A valid Slack signature proves that Slack sent the event. It does not decide which channel or person your agent should trust. Fail closed in the inbound handler before returning auth, especially when the app is installed in a shared Slack Connect channel:
+
+```ts title="agent/channels/slack.ts"
+import { connectSlackCredentials } from "@vercel/connect/eve";
+import { defaultSlackAuth, slackChannel, type SlackMessage } from "eve/channels/slack";
+
+const allowedChannels = new Set(["C01234567"]);
+const allowedUsers = new Set(["U01234567"]);
+
+function isAllowedUser(message: SlackMessage) {
+ const userId = message.author?.userId;
+ return Boolean(userId && allowedUsers.has(userId));
+}
+
+export default slackChannel({
+ credentials: connectSlackCredentials("slack/my-agent"),
+ onAppMention(ctx, message) {
+ if (!isAllowedUser(message) || !allowedChannels.has(message.channelId)) {
+ return null;
+ }
+ return { auth: defaultSlackAuth(message, ctx) };
+ },
+ onDirectMessage(ctx, message) {
+ if (!isAllowedUser(message)) return null;
+ return { auth: defaultSlackAuth(message, ctx) };
+ },
+});
+```
+
+Override every enabled inbound handler; leaving `onDirectMessage` out would retain eve's default DM behavior. Slack Connect can deliver events from external users, so authorize the explicit user and current channel IDs your policy expects. If access depends on organization membership, resolve it from Slack's shared-channel and user data instead of inferring it from the request signature.
+
+Keep authorization checks inside sensitive tools too. The inbound allowlist controls who can start a turn; tool-level checks control what that authenticated Slack principal may read or change.
+
+The allowlist above gates message-started turns. Built-in HITL buttons are handled before `onInteraction`, and the person who clicks supplies the Slack auth for the resumed session. Anyone who can interact with the Slack message can answer it. Put sensitive prompts in channels limited to the intended approvers, and re-check `ctx.session.auth.current` inside a sensitive tool before performing its side effect.
+
#### Continue conversations without repeated mentions
Use `onMessage` to handle explicit mentions and continue replies in threads with an active eve session:
@@ -106,6 +214,28 @@ async onMessage(ctx, message) {
Like `threadContext`, this helper calls `conversations.replies` and requires the matching Slack history scope. It observes at most the first 50 messages of the thread, and a failed fetch is logged and swallowed, so the returned list may be empty or stale — treat an unexpected empty list as "don't route" rather than "no participants".
+#### Load prior thread messages
+
+You get the triggering mention by default, but not the earlier replies in the thread. Enable `threadContext` to fetch and inject them with every message attributed by stable Slack user id. Use `since: "last-agent-reply"` so repeated mentions inject only what is new:
+
+```ts
+import { slackChannel } from "eve/channels/slack";
+import { connectSlackCredentials } from "@vercel/connect/eve";
+
+export default slackChannel({
+ credentials: connectSlackCredentials("slack/my-agent"),
+ threadContext: { since: "last-agent-reply" },
+});
+```
+
+`since` sets the boundary for what each mention injects and accepts three values:
+
+- `"thread-root"` (the default): every prior message in the thread, on every mention. `threadContext: {}` behaves the same.
+- `"last-agent-reply"`: only messages after this installed agent's last reply, keeping repeated mentions incremental. Replies from other Slack bots do not move the boundary.
+- A predicate `(message: SlackThreadMessage) => boolean`: only messages after the last one it matches, such as "since the last message that mentioned a particular user".
+
+`threadContext` requires the matching Slack history scope. Thread helpers reuse messages already loaded within the same inbound handler, and overlapping refreshes share one `conversations.replies` request. Omit it when the agent should see only direct mentions. `loadThreadContextMessages` remains available when you need custom filtering or non-model processing of the raw thread messages.
+
#### Cancel an active turn
Message hooks (`onMessage`, `onAppMention`, and `onDirectMessage`) receive thread-bound session operations directly on `ctx`. Call `ctx.cancel({ turnId? })` before returning `{ auth }` to stop the current turn and queue the new Slack message as replacement input, producing a debounce-like experience:
@@ -211,26 +341,6 @@ const session = await ctx.resolveSession({ target });
`onEvent` covers JSON `event_callback` deliveries only. URL verification, slash commands, and interactive payloads do not reach it. Add every desired event and required OAuth scope to the Slack app's Event Subscriptions configuration; eve can only handle events Slack sends.
-You get the triggering mention by default, but not the earlier replies in the thread. Enable `threadContext` to fetch and inject them with every message attributed by stable Slack user id. Use `since: "last-agent-reply"` so repeated mentions inject only what is new:
-
-```ts
-import { slackChannel } from "eve/channels/slack";
-import { connectSlackCredentials } from "@vercel/connect/eve";
-
-export default slackChannel({
- credentials: connectSlackCredentials("slack/my-agent"),
- threadContext: { since: "last-agent-reply" },
-});
-```
-
-`since` sets the boundary for what each mention injects and accepts three values:
-
-- `"thread-root"` (the default): every prior message in the thread, on every mention. `threadContext: {}` behaves the same.
-- `"last-agent-reply"`: only messages after this installed agent's last reply, keeping repeated mentions incremental. Replies from other Slack bots do not move the boundary.
-- A predicate `(message: SlackThreadMessage) => boolean`: only messages after the last one it matches, such as "since the last message that mentioned a particular user".
-
-`threadContext` requires the matching Slack history scope. Thread helpers reuse messages already loaded within the same inbound handler, and overlapping refreshes share one `conversations.replies` request. Omit it when the agent should see only direct mentions. `loadThreadContextMessages` remains available when you need custom filtering or non-model processing of the raw thread messages.
-
### Slack API calls outside a handler
Inside webhook-side handlers (`onAppMention`, `onEvent`, `onInteraction`, `events`),
@@ -240,7 +350,7 @@ messages, for example, has no inbound Slack request. For that, call the
same primitive the handle uses directly:
```ts
-import { callSlackApi, resolveSlackBotToken } from "eve/channels/slack";
+import { callSlackApi } from "eve/channels/slack";
import { connectSlackCredentials } from "@vercel/connect/eve";
const { botToken } = connectSlackCredentials("slack/my-agent");
@@ -309,7 +419,9 @@ Start a session without an inbound message through `ctx.to(slack, target).send(m
Inbound files behind authenticated Slack URLs are staged with `fetchFile`. See [File uploads](./custom#file-uploads) for the `fetchFile` contract.
-Private file downloads require the Slack bot token's `files:read` scope. Add the scope and reinstall the Slack app before sending attachments. If Slack returns an HTML sign-in page instead of file bytes, eve rejects the response with this remediation instead of staging the page as an attachment.
+Private file downloads require the Slack bot token's `files:read` scope. Add the scope and reinstall the Slack app before sending attachments.
+
+Staged files live in the session sandbox under `/workspace/attachments`. Session history keeps a reference to that path, not a second copy of the Slack file. If the backend can no longer reattach the original sandbox, eve cannot restore the attachment bytes from history; later turns receive a missing-file result. Store files outside the sandbox when the agent must retain them independently of sandbox availability.
## What to read next
diff --git a/docs/connections/mcp.mdx b/docs/connections/mcp.mdx
index 9338cbc66..d76b83bfb 100644
--- a/docs/connections/mcp.mdx
+++ b/docs/connections/mcp.mdx
@@ -214,6 +214,12 @@ Return `"user-approval"` (or `true`) to pause for a person and `"not-applicable"
[Human-in-the-loop](/docs/human-in-the-loop#approvals) covers the full set of statuses, how `approvedTools` and `session.auth` factor in, and how a gated call pauses and resumes durably.
+## Control result size
+
+eve sends an MCP tool's returned content to the model as the tool result. MCP connections do not expose a per-result transform equivalent to an authored tool's [`toModelOutput`](/docs/tools#shape-what-the-model-sees-with-tomodeloutput).
+
+When a remote tool returns more data than the model needs, narrow the result at the MCP server. Prefer a purpose-built search or summary tool, or return a stable handle that another call can use to fetch a smaller slice. If you do not control the server and an equivalent upstream API is available, replace only that operation with an authored tool that stores the full payload outside model context and projects the needed fields through `toModelOutput`. Block the original MCP operation through [`tools.block`](#tool-filters) so the model does not see duplicate tools.
+
## Troubleshooting
| Symptom | Check |
diff --git a/docs/guides/dynamic-workflows.md b/docs/guides/dynamic-workflows.md
index 5207c9134..d0b974366 100644
--- a/docs/guides/dynamic-workflows.md
+++ b/docs/guides/dynamic-workflows.md
@@ -7,6 +7,8 @@ The experimental `Workflow` tool lets the model write JavaScript that coordinate
A single turn can already call several subagents, and parallel tool calls dispatch concurrently. What a workflow adds is _programmatic_ coordination. The program decides how many subagents to run based on an earlier result, which output feeds which call, and how to combine everything. That is logic the model cannot express as a few one-off calls.
+`Workflow` is a model-facing tool, not an API for authored tools, hooks, or application code. Authored code cannot submit a Workflow program or use `Workflow` to start an arbitrary user-authored Vercel Workflow. Use the [client SDK](./client/overview) when application code needs to start or continue an eve session; use ordinary application APIs for other deterministic orchestration.
+
## Enable the Workflow tool
Export the experimental Workflow definition from `agent/tools/workflow.ts`. The helper name carries the "experimental" warning, but the tool the model actually sees is named `Workflow`.
diff --git a/docs/guides/frontend/overview.mdx b/docs/guides/frontend/overview.mdx
index ac43aba34..be0188b53 100644
--- a/docs/guides/frontend/overview.mdx
+++ b/docs/guides/frontend/overview.mdx
@@ -75,7 +75,9 @@ export function Chat() {
Most chat UIs only need `data.messages` and `status`. Drop down to `events` when you need the authoritative wire events directly, for example to persist an audit log or build a custom projection.
-`data.messages` are `EveMessage[]` following the AI SDK `UIMessage` convention, so they drop straight into any AI SDK UI primitive that accepts a `UIMessage[]`. Parts include user text, user file attachments, assistant text, reasoning, tool calls, tool results, input requests, and connection authorization prompts.
+`data.messages` are eve-owned `EveMessage[]`. Common text, reasoning, file, and dynamic-tool parts follow the [AI SDK `UIMessage`](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message) rendering convention, but the types are not interchangeable. eve also exposes authorization and HITL metadata, and a file part's URL can be absent. Adapt those parts before passing messages to an API typed as `UIMessage[]`.
+
+When the root agent delegates, its stream emits `subagent.called` with the child's `childSessionId`, then `subagent.completed` when the child returns. Detailed child progress lives on the child session's stream instead of being flattened into the root `data.messages`. Use the lower-level [TypeScript client](../client/overview#sessions) to attach to that ID when your UI needs live subagent activity. See [What the parent sees](../../subagents#what-the-parent-sees) for the complete contract.
## Sending and streaming
diff --git a/docs/sandbox.mdx b/docs/sandbox.mdx
index d17ffa755..ba55c808a 100644
--- a/docs/sandbox.mdx
+++ b/docs/sandbox.mdx
@@ -183,7 +183,7 @@ export default defineSandbox({
});
```
-Sessions are persistent, and how the underlying runtime idles out depends on the backend. On the Vercel backend, the VM times out after a period of inactivity (default 30 minutes); eve preserves the filesystem and resumes the sandbox on the next message as if nothing happened, even days later. The Docker backend keeps a long-lived container per durable session and persists `/workspace` across turns without that timeout, and the just-bash backend stores its virtual filesystem under `.eve/sandbox-cache/`. In every case, `/workspace` survives between turns for the same session.
+Sessions are persistent, and how the underlying runtime idles out depends on the backend. On the Vercel backend, the VM times out after a period of inactivity (default 30 minutes); eve preserves the filesystem and resumes the sandbox on the next message while the persisted sandbox remains available. The Docker backend keeps a long-lived container per durable session and persists `/workspace` across turns without that timeout, and the just-bash backend stores its virtual filesystem under `.eve/sandbox-cache/`.
Authored runtime callbacks can stop compute sooner through the handle returned
by `ctx.getSandbox()`:
@@ -203,7 +203,9 @@ stop-specific state is needed. Lifecycle `use()` calls return the I/O-only
`SandboxSession` because bootstrap and session initialization do not own runtime
teardown.
-Session sandboxes are keyed per durable session, not per deployment, so redeploying your app does not discard them. A session gets a replacement sandbox only when the sandbox definition itself changes — the authored sandbox source, workspace seed content, or `revalidationKey` — in which case the next turn starts from the rebuilt template and `onSession` runs again.
+Session sandboxes are keyed per durable session, not per deployment, so redeploying your app does not by itself discard them. A definition change to the authored sandbox source, workspace seed content, or `revalidationKey` replaces the sandbox on the next turn and runs `onSession` again.
+
+Reattachment still depends on the backend retaining its physical sandbox state. If a persisted Vercel sandbox is no longer available, eve creates a replacement, using the current template when one is configured. Files and other changes made after the original sandbox was created are not restored automatically. Because the durable session still has the same sandbox key, `onSession` does not run again for this replacement. Persist important artifacts outside the sandbox, and do not rely on `onSession` as the only place that applies security-critical configuration.
When the eve server stops, no sandbox compute outlives it. `eve dev` stops the sandboxes it started when the dev server closes, and a self-hosted production server stops every open sandbox on shutdown (`SIGTERM`/`SIGINT`). Session state persists across the stop — the next server start reattaches each durable session from its stopped container, VM, or snapshot. Custom `SandboxBackend` adapters implement `stop()` for authored runtime calls and `shutdown()` for server teardown. Both stop the underlying compute while keeping the session reattachable from persisted state where the backend supports it; authored `stop()` failures reject, while process-wide shutdown collects and logs failures without blocking teardown.
@@ -223,7 +225,7 @@ networkPolicy: {
Default egress is `allow-all`. For non-public, sensitive, regulated, or production workloads, configure `deny-all` or an explicit allow-list before running untrusted tools or handling sensitive data.
-Set it on the factory (`vercel({ networkPolicy: "deny-all" })`) and it applies before authored `bootstrap` code runs; framework-owned base setup may briefly keep egress open to install required packages. Set it in `onSession`'s `use()` to override per-session. The common pattern combines both: leave the factory open so `bootstrap` can `git clone`, then lock down in `onSession`. To change the policy mid-turn, call `sandbox.setNetworkPolicy(...)` on the live handle.
+Set it on the factory (`vercel({ networkPolicy: "deny-all" })`) and it applies before authored `bootstrap` code runs; framework-owned base setup may briefly keep egress open to install required packages. Set it in `onSession`'s `use()` to override per-session. A provider-loss replacement with the same sandbox key does not rerun `onSession`, so enforce the security-critical baseline on the factory. If `bootstrap` needs network access, give the factory only the destinations it needs, then narrow the policy further in `onSession`. To change the policy mid-turn, call `sandbox.setNetworkPolicy(...)` on the live handle.
Domain-level allow-lists and credential brokering are supported by `vercel()` and `microsandbox()`. The Docker backend honors only `"allow-all"` and `"deny-all"` (at creation and via `setNetworkPolicy`); the just-bash backend rejects `setNetworkPolicy` entirely.
diff --git a/docs/skills.mdx b/docs/skills.mdx
index cf468b44d..e10857c15 100644
--- a/docs/skills.mdx
+++ b/docs/skills.mdx
@@ -59,9 +59,20 @@ export default defineSkill({
eve generates `SKILL.md` from `markdown`, and each `files` entry becomes a package-relative sibling. Start with plain markdown and move to `defineSkill` only when you hit its limits.
+## Find and install community skills
+
+`eve registry search` includes [skills.sh](https://skills.sh) as the built-in `@skills` source. Search by task, review the source, then install the returned skill into your project:
+
+```bash
+eve registry search react --registry @skills
+eve add @skills/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+skills.sh skills are community-authored project files. Review their source and the resulting diff before running the agent. See [Install integrations](./install-integrations#add-a-skill) for registry configuration and install behavior.
+
## Skills are scoped per agent
-Skills are scoped to the agent that declares them. A [subagent](./subagents)'s `skills/` are invisible to the root agent, and the reverse holds too. There's no shared-skill mechanism, so put shared executable helpers in `lib/`.
+Skills are scoped to the agent that declares them. A [subagent](./subagents)'s `skills/` are invisible to the root agent, and the reverse holds too. To share one skill definition across agents, package it in a [workspace extension](./extensions#use-an-extension-in-a-workspace) and mount that extension in each agent. Put shared executable helpers in `lib/`.
## Read skill files at runtime
diff --git a/docs/subagents.mdx b/docs/subagents.mdx
index 9f597b432..c50656a9c 100644
--- a/docs/subagents.mdx
+++ b/docs/subagents.mdx
@@ -139,7 +139,7 @@ A declared subagent inherits nothing from the root's authored slots. Discovery t
| Channels | Root-only | Root-only |
| Schedules | Root-only | Root-only |
-For a declared subagent this means duplicating anything the child needs. When two subagents need the same procedure, copy the markdown under each `skills/` directory, or share typed helpers via `lib/`. The sandbox does not inherit from the parent; it falls back to the framework default unless the subagent authors `subagents/<id>/sandbox.ts` or seeds files via `subagents/<id>/sandbox/workspace/`.
+For a declared subagent this means authoring or mounting anything the child needs. When two subagents need the same procedure, package the skill in a [workspace extension](./extensions#use-an-extension-in-a-workspace) and mount that extension in each subagent. Share typed helpers through `lib/`. The sandbox does not inherit from the parent; it falls back to the framework default unless the subagent authors `subagents/<id>/sandbox.ts` or seeds files via `subagents/<id>/sandbox/workspace/`.
The root built-in `agent` tool is the exception. Its children share the root's sandbox and tools because they are copies of the same agent working on the same files.