diff --git a/.gitignore b/.gitignore
index 694ec1f1..b75cd250 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,3 +12,9 @@ next-env.d.ts
 dist
 .DS_Store
 *.tsbuildinfo
+
+# Vercel marketplace installers (e.g. `vercel integration add neon`) drop
+# third-party agent skills and a lock file into the checkout; they are not
+# part of the OpenInstinct agent definition.
+/agent/skills/
+/skills-lock.json
diff --git a/README.md b/README.md
index dca0550f..1cee1ae1 100644
--- a/README.md
+++ b/README.md
@@ -64,6 +64,26 @@ Treat the private Blob store as production key material: deleting it loses the
 automatically generated encryption key, and rotating that key requires
 re-encrypting existing vault values.
 
+### Deploying with the Vercel CLI
+
+The deploy button sets the project's Framework Preset to Next.js for you. A
+project created with the Vercel CLI (`vercel project add` / `vercel link`)
+defaults to **Other**, which builds green but silently drops the Next.js
+output: every app route returns `404 x-vercel-error: NOT_FOUND` while
+`/eve/v1/health` still answers. Set the preset to Next.js before the first
+Git deploy, either in the project settings or with:
+
+```bash
+vercel api /v9/projects/<project-id> --method PATCH --field framework=nextjs
+```
+
+Provisioning Neon through the CLI (`vercel integration add neon ...`) also
+writes third-party agent skills under `agent/skills/` and a root
+`skills-lock.json`. Eve loads every skill in `agent/skills/`, so the assistant
+quietly gains Neon database-administration skills. Both paths are gitignored;
+delete `agent/skills/` and `skills-lock.json` after provisioning unless you
+want the agent to keep them.
+
 ### Blob storage
 
 The one-click deploy creates and connects a private Blob store automatically.
diff --git a/tests/source-layout.test.ts b/tests/source-layout.test.ts
index 5e946a97..de7f29a5 100644
--- a/tests/source-layout.test.ts
+++ b/tests/source-layout.test.ts
@@ -53,4 +53,18 @@ describe("source layout", () => {
     expect(existsSync("db/services/installation-secrets.ts")).toBe(true);
     expect(existsSync("evals/browser/worker-events.ts")).toBe(true);
   });
+
+  it("keeps third-party installer files out of the agent definition", () => {
+    expect(directories("agent")).toEqual([
+      "channels",
+      "hooks",
+      "instructions",
+      "lib",
+      "memory",
+      "schedules",
+      "subagents",
+      "tools",
+    ]);
+    expect(existsSync("skills-lock.json")).toBe(false);
+  });
 });