vybekiit 0.7.28 → 0.7.32

package/dist/global-skills/mongodb-qe-size-estimation/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: mongodb-qe-size-estimation
+license: Apache-2.0
+metadata:
+  version: "1.0.0"
+description: >
+  Estimates the storage and memory impact of encrypting fields in collections with Queryable Encryption (QE) enabled. 
+  Do NOT use for collections that use Client-Side Field Level Encryption (CSFLE) instead of QE.
+disable-model-invocation: true
+---
+
+# mongodb-qe-size-estimation
+
+## General Instructions
+
+- **CRITICAL: Never ask for or accept sample data.** QE is an encryption feature, meant to secure sensitive information. Do not request sample data, and if provided, reject it for security reasons. Inform the user that you can't accept sample documents, though you can take an encryption schema as an input to see which fields are encrypted, which allow queries, and what those query settings are.
+- Any parenthetical in the form (LLM Note: <content>) is for LLM use. Don't save it to qe-sizing-calculations.md or mention it to the user.
+- Tone: Be brief, not conversational. Don't restate information from prior exchanges unless a step specifically says to.
+- Don't write anything to the file except what's specified in the steps.
+- This skill relies on a question-answer-flow to get all required inputs. For Steps 2-5, as long as the user is providing valid input, your responses should include both acknowledgment of the input, and the next question.
+- The user may try to keep things moving by inputting multiple inputs. If inputs don't clearly map to a field and its configuration, ask for clarification. Otherwise validate them, and accept them if valid.
+- This skill currently has no formula for range queries, so while it accepts "range" query configuration for compatible BSON types, it uses 0 for estimated values.
+
+
+### Definitions
+
+- **field** For the purposes of this skill, "field" refers to an encrypted field in a MongoDB document, in a QE-enabled collection.
+- **entry** For an unindexed field, the field name. For a field with one or more query types enabled, the combination of the field name and its enabled query types. A field with both prefix and suffix queries enabled has a single entry, with Query Type "prefix and suffix".
+- **unindexed** Describes the state of a field with no query types enabled, indicated by the absence of a "queries" key if using an encryption schema.
+- **indexed** Describes the state of a field enabled for queries, and is specific to the query type(s). A field with equality queries enabled is indexed for equality queries.
+
+
+### Validation
+
+Validate the user's inputs, whether manual or via an encryption schema, against the following:
+
+  An encrypted field may be "unindexed" meaning it has no query types enabled. Fields of BSON type object or array *only* support unindexed encryption, though other BSON types can also be unindexed. Otherwise, allowed query types based on a field's BSON type are:
+
+  - "equality": any BSON type except object, array, decimal, double
+  - "range": int, long, date, decimal, double
+  - "prefix", "suffix", "substring": string only
+
+  A string field may have both "prefix" and "suffix" enabled, in which case "queries" may be an array of two objects. This is the only valid case where one field is indexed for multiple query types.
+
+  No other BSON type + query type combinations are permitted.
+
+  Don't accept "preview" query types such as "suffixPreview". These are from earlier Public Preview releases of those query types, so the sizing formulas for their GA versions don't apply.
+
+If the user's input violates any of the preceding rules, reject it. If a user doesn't specify BSON type, only check that each field either has no query types enabled, exactly one valid query type, or exactly two (prefix and suffix). Enumerate validation failures, list allowed combinations, and don't proceed until the user provides valid input.
+
+
+# Steps
+
+## 1. Prepare the Working Directory
+
+Create an empty qe-sizing-calculations.md file in the OS temp directory ($TMPDIR, or /tmp if unset). If a qe-sizing-calculations.md file already exists at that location, inform the user and ask for confirmation to delete it and create a new one for the new set of calculations.
+
+## 2. State Purpose and Request Input Preference
+
+State: "This skill calculates the maximum storage impact of enabling Queryable Encryption on a collection. Values are saved to the <path to qe-sizing-calculations.md> file if you want to verify the calculations or see per-field numbers. Note that prefix, suffix, and substring queries on encrypted fields require MongoDB 9.0, and aren't supported in earlier versions. 
+
+All values are worst-case. You may see a smaller impact on storage or memory in practice.
+
+Do you want to provide field information manually, or use an encryption schema file?"
+
+If the user opts for an encryption schema, request it as either pasted content or a file path, and expect JSON format. Validate the schema against this skill's "Validation" section. If the schema is valid but includes fields with "range" queries enabled, inform the user that no calculations are available for those fields, so their impact is estimated as 0.
+
+## 3. Get the Number of Documents
+
+Ask the user how many documents in the collection have encrypted fields. If they don't know, a safe default is the total number of documents in the collection. Save this value to qe-sizing-calculations.md as:
+
+**N:** <value>
+
+## 4. Get the Number of Entries
+
+- If the user chose manual input, ask: How many fields are you encrypting without enabling queries?
+- If the user chose encryption schema, count the number of encrypted fields without queries enabled.
+
+Save this value to qe-sizing-calculations.md as:
+
+**numUnindexed:** <number of unindexed encrypted fields>
+
+- If the user chose manual input, ask: How many encrypted fields have queries enabled?
+- If the user chose encryption schema, count the number of fields with queries enabled.
+
+Save this value to qe-sizing-calculations.md as:
+
+**numIndexed:** <number of encrypted fields indexed for queries>
+
+Save the sum of numUnindexed and numIndexed to qe-sizing-calculations.md as:
+
+**numEntries:** <sum of numUnindexed and numIndexed>
+
+## 5. Get Inputs Per Field
+
+Write a section heading to qe-sizing-calculations.md:
+
+== FIELD VALUES ===============================================================
+
+As you get information, write it to qe-sizing-calculations.md in the following format, omitting any lines that don't apply. For unindexed fields, this means omitting the Query Type.
+
+**<Field Name>** <the name provided by the user, or the dot notation "path" value if taken from the encryption schema>
+**Query Type:** <equality, range, prefix, suffix, substring, or "prefix and suffix">
+**mlen:** <include if Query Type is substring. Integer from 2-50, inclusive>
+**lb:** <include if Query Type is "prefix", "suffix", or "substring". Integer 1+ for prefix and suffix queries, or 2+ for substring queries>
+**ub:** <include if Query Type is "prefix", "suffix", or "substring". Integer 1+ for prefix and suffix queries, or 2-6 for substring queries>
+**lb_prefix:** <include if Query Type is "prefix and suffix". Integer 1+>
+**ub_prefix:** <include if Query Type is "prefix and suffix". Integer 1+>
+**lb_suffix:** <include if Query Type is "prefix and suffix". Integer 1+>
+**ub_suffix:** <include if Query Type is "prefix and suffix". Integer 1+>
+**v:** <omit if Query Type is range, otherwise include. Integer representing the average byte length of the unencrypted values for the field>
+
+- If the user provided an encryption schema, do this once:
+  - Add one entry to qe-sizing-calculations.md for each unindexed field, omitting the "Query Type" line.
+  - If a field has both prefix and suffix queries enabled, regardless of ordering, write its "Query Type" as "prefix and suffix".
+  - Add one entry per field with queries enabled. Map the keys in each "queries" object to field values as follows, omitting all keys that aren't listed:
+    - strMaxLength (substring only) -> mlen
+    - strMinQueryLength -> lb if the field only has a single query type. If the field has both prefix and suffix queries enabled, then the strMinQueryLength for prefix queries is lb_prefix, and the strMinQueryLength for suffix queries is lb_suffix.
+    - strMaxQueryLength -> ub if the field only has a single query type. If the field has both prefix and suffix queries enabled, then the strMaxQueryLength for prefix queries is ub_prefix, and the strMaxQueryLength for suffix queries is ub_suffix.
+
+- If the user didn't provide an encryption schema, do this per field:
+  - Only validate BSON types against allowed query types if the user provides a field's BSON type. Otherwise, don't ask for or validate field BSON types.
+  - Ask for the field name and whether it's unindexed or has queries enabled (LLM Note: If it has a query type, valid options are: "equality", "range", "prefix", "suffix", "substring", or "prefix and suffix". Reject other values or combinations. If the user specifies "range", warn them that no formula is available for calculating it)
+  - If a user only provides a single lower bound and upper bound value for a field with both prefix and suffix queries enabled, use the lower bound for both lb_prefix and lb_suffix, and the upper bound for both ub_prefix and ub_suffix.
+  - Validate the inputs.
+
+Do this per field:
+
+  Check the list below, and ask the user for the values that aren't already populated. Write all values to the qe-sizing-calculations.md file.
+
+  **mlen:** (LLM Note: only include if no schema provided, and Query Type is substring) Max Length, the maximum allowable length of the string.
+  **lb:** (LLM Note: only include if no schema provided, and Query Type is "prefix", "suffix", or "substring") Lower Bound, the minimum searchable characters.
+  **ub:** (LLM Note: only include if no schema provided, and Query Type is "prefix", "suffix", or "substring") Upper Bound, the maximum searchable characters.
+  **lb_prefix:** (LLM Note: only include if no schema provided, and Query Type is "prefix and suffix") Lower Bound for prefix queries, the minimum searchable characters.
+  **ub_prefix:** (LLM Note: only include if no schema provided, and Query Type is "prefix and suffix") Upper Bound for prefix queries, the maximum searchable characters.
+  **lb_suffix:** (LLM Note: only include if no schema provided, and Query Type is "prefix and suffix") Lower Bound for suffix queries, the minimum searchable characters.
+  **ub_suffix:** (LLM Note: only include if no schema provided, and Query Type is "prefix and suffix") Upper Bound for suffix queries, the maximum searchable characters.
+  **v:** (LLM Note: skip if Query Type is range since we have no calculation for those, otherwise needed once per field). Average byte length of the unencrypted values for the field. If the user provides character length, accept it as equivalent.
+
+  Validate values against the formatting snippet at the start of this step. Validate that lb ≤ ub ≤ mlen (if present). Validate that lb_prefix ≤ ub_prefix and lb_suffix ≤ ub_suffix (if present). If a value falls outside allowable bounds, reject it and inform the user. Do not proceed without a valid value.
+  
+  If mlen < v, warn the user that the full field value isn't queryable, but accept it as valid. 
+
+Repeat until you have populated the full number of entries, numEntries, in qe-sizing-calculations.md.
+
+## 6. Add Formulas and Results to qe-sizing-calculations.md
+
+This step populates calculation information to file, including intermediate steps.
+
+For every entry in qe-sizing-calculations.md:
+
+1. Append the following lines to each existing entry in the FIELD VALUES section of qe-sizing-calculations.md. It is critical that you copy formula templates exactly to avoid cascading issues. When running calculations, defer to available mathematical parsing tools and ensure correct order of operations.
+
+  - For fields with no Query Type:
+
+    **T:** 0
+    **Document Storage (bytes):** <run the calculation: 71 + ceil((v+6)/16) * 16>
+
+  - For fields with a Query Type of "equality":
+
+    **T:** 1
+    **Document Storage (bytes):** <run the calculation: 1.2 * (255 * T + 122 + ceil((v + 6) / 16) * 16)>
+
+  - For fields with a Query Type of "range", there is currently no formula, so record an entry with values of 0:
+
+    **T:** 0
+    **Document Storage (bytes):** 0
+
+  - For fields with a Query Type of "prefix" or "suffix":
+
+    **T formula:** T = 1 + (ub - lb + 1)
+    **T calculation:** <The T formula template with all placeholders populated by the field's values, but not calculated>
+    **T:** <run the calculation in "T calculation" and write the result here>
+    **Document Storage (bytes):** <run the calculation: 1.2 * (255 * T + 122 + ceil((v + 6) / 16) * 16)>
+
+
+  - For fields with a Query Type of "prefix and suffix":
+  
+    **T formula:** T = 1 + (ub_prefix - lb_prefix + 1) + (ub_suffix - lb_suffix + 1)
+    **T calculation:** <The T formula template with all placeholders populated by the field's values, but not calculated>
+    **T:** <run the calculation in "T calculation" and write the result here>
+    **Document Storage (bytes):** <run the calculation: 1.2 * (255 * T + 122 + ceil((v + 6) / 16) * 16)>
+
+  - For fields with a Query Type of "substring":
+
+    **T formula:** T = 1 + (ub - lb + 1) * (2 * mlen + 2 - ub - lb) / 2
+    **T calculation:** <The T formula template with all placeholders populated by the field's values, but not calculated>
+    **T:** <run the calculation in "T calculation" and write the result here>
+    **Document Storage (bytes):** <run the calculation: 1.2 * (255 * T + 122 + ceil((v + 6) / 16) * 16)>
+
+2. Do a silent audit pass to verify the information you just added uses the correct T formula or static value, and the correct values for the T calculation, then proceed.
+
+## 7. Calculate Index Storage, Total Disk Storage, and Memory
+
+These values are collection-level and calculated as totals across all entries.
+
+At the end of the qe-sizing-calculations.md file, silently write the following lines:
+
+== COLLECTION-LEVEL TOTALS ====================================================
+**N:** <copy the N value from the top of the file down to this section, for easier reading>
+**T_Total:** <the sum of all T values.>
+**Index Storage (bytes):** <run the calculation: 1.2 * (67 * T_Total + 640)>
+**Total Disk Storage (bytes):** <run the calculation: N * (Index Storage + (the sum of all Document Storage values))>
+**Memory (bytes):** <run the calculation: N * (52 * T_Total + 17)>
+
+## 8. Sum Total Results and Report Conclusions
+
+Output the following, and include the units:
+
+**Total Disk Storage Impact:** <the Total Disk Storage value from qe-sizing-calculations.md, converted to decimal GB (1000³ bytes) >
+**Required Memory:** <the Memory value from qe-sizing-calculations.md, converted to binary GiB (1024³ bytes)>
+**Fields by Impact (descending):** <sort all fields in qe-sizing-calculations.md by T, descending, then list them as: Name (<either the Query Type, or unindexed>): T>
+
+If the encryption schema or manual inputs included fields with range queries enabled, list those fields and remind the user that their impact wasn't calculated.
+
+## 9. Interpret Results
+
+Present advice. Don't provide any advice the user has explicitly rejected, such as suggesting different query types if they insist a field needs to allow substring queries. Only raise problems, don't mention something if it passes all checks. If you suggest changing values to a specific number, populate the Step 6 T formula template for that query type with the suggested values, calculate it with available mathematical tools, and quote only that result.
+
+- (LLM Note: Only run this check if the number of fields with substring queries enabled is greater than floor(50 million/N). Defer to available mathematical parsing tools to ensure correct calculation) Tell the user to limit the number of substring queryable fields to no more than: floor(50 million/<documents in collection>). Tell them not to use substring queries on collections of more than 50 million documents.
+- (LLM Note: Only run this check if one or more substring queryable fields are present) Check if substring-indexed fields might be suitable for prefix or suffix queries instead, and suggest that to the user. For example, queries against encrypted "name" fields can often use prefix instead of substring, though this admittedly presents drawbacks for cases like hyphenated surnames.
+- (LLM Note: Only make these suggestions if they apply to the user's inputs, and if the changes don't make the modified value go outside its allowed limits) Tell the user to consider raising lb, lowering ub, or lowering mlen values.
+
+Also inform the user of the path to the qe-sizing-calculations.md file, and ask if they want to review the data, or delete the temporary file. Remind them that the temporary file contains the names of encrypted fields and their average plaintext lengths, and should be deleted once finished.

package/dist/global-skills/mongodb-query-optimizer/SKILL.md

@@ -7,6 +7,7 @@ compatibility: >-
 license: Apache-2.0
 metadata:
   version: "1.0.0"
+disable-model-invocation: true
 ---
 
 # MongoDB Query Optimizer

package/dist/global-skills/mongodb-schema-design/SKILL.md

@@ -4,6 +4,7 @@ description: MongoDB schema design patterns and anti-patterns. Use when designin
 license: Apache-2.0
 metadata:
   version: "1.0.0"
+disable-model-invocation: true
 ---
 
 # MongoDB Schema Design

package/dist/global-skills/mongodb-search-and-ai/SKILL.md

@@ -5,6 +5,7 @@ description: |
 license: Apache-2.0
 metadata:
   version: "1.0.0"
+disable-model-invocation: true
 ---
 
 # MongoDB Search and AI Recommendations Skill

package/dist/global-skills/native-data-fetching/SKILL.md

@@ -3,6 +3,7 @@ name: native-data-fetching
 description: Use when implementing or debugging ANY network request, API call, or data fetching. Covers fetch API, React Query, SWR, error handling, caching, offline support, and Expo Router data loaders (`useLoaderData`).
 version: 1.0.0
 license: MIT
+disable-model-invocation: true
 ---
 
 # Expo Networking

package/dist/global-skills/neon/SKILL.md

@@ -14,6 +14,7 @@ description: >-
   no-signup database.
 metadata:
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon
+disable-model-invocation: true
 ---
 
 # Neon
@@ -194,25 +195,27 @@ Then inspect credentials without printing secrets. `NEON_API_KEY` or a `neon pro
 
 ### Combined setup: `neon init`
 
-When both agent tooling and project setup are needed, use authenticated `neon init`. `--agent` takes the coding-agent name. `-y` skips prompts but does not supply project selection or credentials. `--skip-template` skips scaffolding a starter app.
+When both agent tooling and project setup are needed, use authenticated `neon init`. It sets up the current directory in place. `--agent` takes the coding-agent name. `-y` skips prompts but does not supply project selection or credentials.
 
 Link an existing project:
 
 ```bash
-neon init --skip-template --agent cursor \
+neon init --agent cursor \
   --org-id <org-id> --project-id <project-id> -y
 ```
 
 Create and link a project:
 
 ```bash
-neon init --skip-template --agent cursor \
+neon init --agent cursor \
   --org-id <org-id> --project-name my-app \
   --region-id aws-us-east-2 -y
 ```
 
 `--services` may declare `auth`, `data-api`, `functions`, `object-storage`, and `ai-gateway` (repeat the flag or comma-separate). Pass `none` for the bare starter policy. It writes `neon.ts`; it does not deploy or wire the app. Selecting `data-api` also declares Auth (the default Data API provider requires it). Use `data-api` only for PostgREST / Supabase database-client compatibility.
 
+With `-y`, `init` installs the Neon plugin globally where the agent supports it (its MCP server signs in with OAuth). Other agents get skills and the MCP server globally, with an API key when the CLI is signed in. `--mcp-auth` and `--mcp-config-location` change the MCP setup; see `neon init --help`.
+
 If `init` already installed the Neon plugin, do not also run `neon mcp` and `neon skills` for the same agent.
 
 When tooling already exists, only one component is missing, or env writes need `--no-env-pull`, use the manual steps below. `init` has no `--no-env-pull`. Before a command that pulls env, inspect existing configuration. If a supplied `DATABASE_URL` or `AWS_*` value must stay, pass `--no-env-pull` on `link` / `checkout` and write env to a separate `--file`.
@@ -223,11 +226,21 @@ Use the install check above. Do not run `neon login` unattended. MCP remains the
 
 ### 2. Install the Neon MCP Server
 
+Install globally, the CLI default. One install serves every project:
+
+```bash
+neon mcp --agent <agent> -y
+```
+
+This writes an API key into the agent's user config, reusing an existing Neon MCP key or minting one (needs `neon auth` or a personal API key). Always pass `--agent`; without it, `-y` writes to every installed agent.
+
+Add `--oauth` to store only the server URL instead; the user signs in from the agent and picks scopes on the consent page. For a project-level install, always use OAuth so no key lands in a file git can commit:
+
 ```bash
-neon mcp --oauth --project --agent cursor -y
+neon mcp --oauth --project --agent <agent> -y
 ```
 
-`--oauth` writes the server URL and leaves sign-in to the MCP client. That is not an authenticated MCP session. `--project` means project-level agent config, not a Neon project ID; the agent must support project-level installs (`cursor` does). Bare `neon mcp -y` installs globally and can reuse or mint an account-wide API key — do not treat it as the unattended default.
+`neon mcp --help` lists the other flags (`--read-only`, `--project-id`, `--category`) and supported agents.
 
 For all available plugins and IDE integrations, see: https://neon.com/docs/ai/ai-agents-tools.md
 

package/dist/global-skills/neon-ai-gateway/SKILL.md

@@ -15,6 +15,7 @@ description: >-
 metadata:
   parent: neon
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-ai-gateway
+disable-model-invocation: true
 ---
 
 **FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.

package/dist/global-skills/neon-auth/SKILL.md

@@ -13,6 +13,7 @@ description: >-
 metadata:
   parent: neon
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-auth
+disable-model-invocation: true
 ---
 
 **FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.

package/dist/global-skills/neon-functions/SKILL.md

@@ -19,6 +19,7 @@ description: >-
 metadata:
   parent: neon
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-functions
+disable-model-invocation: true
 ---
 
 **FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.
@@ -154,6 +155,16 @@ To deploy a single function without applying `neon.ts`: `neon functions deploy <
 
 When `neon checkout` _creates_ a new branch and a `neon.ts` is present, it applies the policy automatically. Pass `--env <file>` on that create so Function env that reads `process.env` resolves (`neon checkout feat --create --env .env.local`). Existing process env wins over the file. Checking out an existing branch never reconciles it — apply config changes with `neon deploy --env <file>` (add `--update-existing` only after reviewing those changes).
 
+### Native binaries and custom builds
+
+The default deploy bundles `source` into one `index.mjs`, which cannot hold a compiled binary. Ship one as a separate archive file:
+
+- npm package with a Node addon (`sharp`): `externalPackages: ["sharp"]`. The deploy installs its linux-arm64 glibc build and copies the files in.
+- Your own build output (`.node`, `.so`, `.wasm`, data files): `bundler: "none"` with a prebuilt directory, or an inline `bundler: async (fn) => ({ "index.mjs": …, "bin/tool": … })`.
+- A standalone executable you spawn: ship it as above, then copy it to `/run` and `chmod 755` it at startup. Files in `/opt/function` arrive as mode `644` on a read-only filesystem, and `/tmp` is `noexec`.
+
+Runtime target, pros and cons, working snippets, and size limits: [references/native-binaries.md](references/native-binaries.md).
+
 ## Neon Infrastructure as Code (`neon.ts`)
 
 The `functions` block from [Setup](#setup) is part of `neon.ts`, Neon's infrastructure-as-code file — one TypeScript file declares every function (its `source`, display `name`, and `env`) alongside any other branch services, in version control (see the `neon` skill for the full reference). Treat it like Terraform for your branch:
@@ -652,4 +663,5 @@ The Neon documentation is the source of truth and Functions is evolving rapidly,
 - https://neon.com/docs/compute/functions/custom-domains.md
 - https://neon.com/docs/cli/triggers.md
 - [references/function-triggers.md](references/function-triggers.md)
+- [references/native-binaries.md](references/native-binaries.md)
 - [references/production-hardening.md](references/production-hardening.md)

package/dist/global-skills/neon-functions/references/native-binaries.md

@@ -0,0 +1,188 @@
+# Shipping native binaries with a Function
+
+The default deploy bundles `source` into a single `index.mjs` with esbuild. A compiled binary cannot be inlined into that file, so it has to ship as a separate file in the deploy archive. There are three ways to put it there. Pick by what the binary is:
+
+| The binary is                                                                              | Use                                                            |
+| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| An npm package backed by a Node-API addon (`sharp`, most `@napi-rs/*` packages)             | [`externalPackages`](#externalpackages-npm-packages-with-a-node-addon) |
+| A file your own build step produces: a `.node` addon, a `.so`, a `.wasm`, model weights    | [`bundler: "none"`](#bundler-none-ship-a-prebuilt-directory) or a [custom `bundler`](#custom-bundler-return-the-file-map) |
+| A standalone executable you spawn (`ffmpeg`, a Go or Rust CLI)                              | A custom `bundler` or `"none"`, plus [a copy to `/run` at startup](#standalone-executables) |
+
+The examples use top-level `functions`, which needs `neon` CLI 4.20 or newer and `@neon/config` 1.6 or newer.
+
+## The runtime a binary lands on
+
+- **linux, arm64, glibc**, Node.js 24. A binary built for macOS or x64 cannot load there.
+- The archive is extracted to `/opt/function`, a read-only filesystem. `import.meta.url` in the root `index.mjs` points there, so `new URL("./bin/tool", import.meta.url)` resolves to `/opt/function/bin/tool`.
+- **Every file arrives with mode `644`.** Unix permission bits in the zip are dropped on extraction, and `chmod` in place fails with `EROFS`. A `.node` or `.so` loads fine (it is `dlopen`ed, not executed). Spawning a file from `/opt/function` fails with `EACCES`.
+- `/tmp` is writable and mounted `noexec`: a copied binary still fails with `EACCES` after `chmod 755`.
+- `/run` is a writable tmpfs that allows exec (about 990 MiB, backed by the function's 2048 MiB of memory).
+
+The filesystem layout is observed behavior, not documented by Neon. Re-check it if spawning starts failing.
+
+## `externalPackages`: npm packages with a Node addon
+
+```typescript
+// neon.ts
+import { defineConfig } from "@neon/config/v1";
+
+export default defineConfig({
+  functions: {
+    resize: {
+      name: "Resize",
+      source: "./src/resize.ts",
+      externalPackages: ["sharp"],
+    },
+  },
+});
+```
+
+esbuild leaves `import sharp from "sharp"` unresolved. At deploy, the CLI installs the version of `sharp` from your project with `npm install --cpu=arm64 --os=linux --libc=glibc --ignore-scripts` into a temp directory, traces the files it reaches with `@vercel/nft`, and copies them into the archive under `node_modules/` with the tree layout intact. Only the installed version is read from your `node_modules`; the shipped files come from the temp install, and your `node_modules` is not modified.
+
+The deploy fails with a named error when:
+
+- the package is not installed in your project (no version to pin)
+- the declared package itself does not install for linux-arm64 glibc (`EBADPLATFORM`)
+- a staged `.node` or `.so` is not an AArch64 ELF binary
+- `npm` is not on `PATH`
+- the archive exceeds the [size limits](#size-limits)
+
+It does not fail when a platform-specific optional dependency is silently skipped, or when a package that compiles from source at install time ships no binary (the staging install runs with `--ignore-scripts`). Those deploy and then fail at invoke. Use packages that publish a linux-arm64 glibc prebuild (`sharp` does), and invoke the deployed function once to confirm the addon loads.
+
+A deploy and `neon dev` print an advisory warning for any bundled package that carries native code and is not declared. A package with a working JavaScript fallback (`ws` with `bufferutil`) triggers it too and needs no change. Do not silence it with `{ name, includeFiles: false }`: that externalizes the package and ships nothing, so a reached import throws `Cannot find module` on every invoke. `includeFiles: false` is only for an import the function never evaluates.
+
+Under `neon dev`, the package is only kept out of the bundle and resolves from your own `node_modules` for your host.
+
+Pros: one line in `neon.ts`; the target-platform install, file tracing, arch check, and size check are automatic; local dev uses your host build.
+
+Cons: only for npm packages that publish a linux-arm64 glibc prebuild; transitive pins, overrides, and patches from your lockfile are not carried into the staged install; esbuild bundler only (`externalPackages` with `bundler: "none"` or a function fails validation).
+
+## `bundler: "none"`: ship a prebuilt directory
+
+Run your own build, then point `source` at its output. The directory root must contain `index.mjs` or `index.js`. Everything else in the directory ships as-is:
+
+```text
+dist/fn/
+  index.mjs        # built by your step, reads ./native/addon.node
+  native/addon.node
+```
+
+```typescript
+// neon.ts
+import { defineConfig } from "@neon/config/v1";
+
+export default defineConfig({
+  functions: {
+    api: { name: "API", source: "./dist/fn", bundler: "none" },
+  },
+});
+```
+
+```bash
+npm run build:fn && neon deploy --env .env.local
+neon functions deploy api --src dist/fn --no-bundle   # same thing, without neon.ts
+```
+
+`neon deploy` does not run your build step. Run it first, or use a [custom `bundler`](#custom-bundler-return-the-file-map) to keep the build inside `neon deploy`.
+
+Pros: works with any build tool or framework output (`.mastra/output` is the common one); full control over the archive layout.
+
+Cons: no architecture check, so a binary built for your laptop deploys and then fails at invoke; the build step is yours to keep in sync with `neon deploy`; TypeScript cannot ship unbundled.
+
+## Custom `bundler`: return the file map
+
+An inline function in `neon.ts` returns archive paths mapped to bytes. `neon deploy` zips the map, and `neon dev` serves the same map locally:
+
+```typescript
+// neon.ts
+import { readFile } from "node:fs/promises";
+import { build } from "esbuild";
+import { defineConfig } from "@neon/config/v1";
+
+export default defineConfig({
+  functions: {
+    transcode: {
+      name: "Transcode",
+      source: "./src/transcode.ts",
+      bundler: async (fn) => {
+        const out = await build({
+          entryPoints: [fn.source],
+          bundle: true,
+          platform: "node",
+          format: "esm",
+          write: false,
+          outfile: "index.mjs",
+          // CommonJS dependencies call require(); ESM output has none in scope.
+          banner: {
+            js: "import{createRequire}from'module';const require=createRequire(import.meta.url);",
+          },
+        });
+        return {
+          "index.mjs": out.outputFiles[0].contents,
+          "bin/ffmpeg": new Uint8Array(
+            await readFile(new URL("./vendor/linux-arm64/ffmpeg", import.meta.url)),
+          ),
+        };
+      },
+    },
+  },
+});
+```
+
+`esbuild` must be a dependency of your project. The map needs `index.mjs` or `index.js` at the root.
+
+Pros: the build lives in `neon.ts`, so `neon deploy` and `neon dev` always build the same thing; any file from anywhere can go in the archive.
+
+Cons: no architecture check; `externalPackages` cannot be combined with it, so an npm addon has to be copied into the map by hand, with its `node_modules/` layout.
+
+## Standalone executables
+
+Ship the executable with a custom `bundler` or `bundler: "none"`, then copy it to `/run` and mark it executable once per isolate:
+
+```typescript
+// src/transcode.ts
+import { execFile } from "node:child_process";
+import { chmod, copyFile, mkdir } from "node:fs/promises";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+let ffmpeg: Promise<string> | undefined;
+function ffmpegPath(): Promise<string> {
+  if (process.env.FFMPEG_PATH) return Promise.resolve(process.env.FFMPEG_PATH);
+  ffmpeg ??= (async () => {
+    await mkdir("/run/bin", { recursive: true });
+    await copyFile(new URL("./bin/ffmpeg", import.meta.url), "/run/bin/ffmpeg");
+    await chmod("/run/bin/ffmpeg", 0o755);
+    return "/run/bin/ffmpeg";
+  })();
+  return ffmpeg;
+}
+
+export default {
+  async fetch() {
+    const { stdout } = await run(await ffmpegPath(), ["-version"]);
+    return new Response(stdout);
+  },
+};
+```
+
+`neon dev` runs this code on your machine, where `/run` may not exist and a linux-arm64 binary cannot execute. Point it at a host install from the shell, and leave `FFMPEG_PATH` out of the function's deployed `env`:
+
+```bash
+FFMPEG_PATH="$(command -v ffmpeg)" neon dev
+```
+
+The binary must be statically linked, or its shared libraries must exist in the runtime image. The copy costs memory: `/run` is RAM-backed and counts against the function's 2048 MiB.
+
+## Size limits
+
+`bundler: "none"`, a custom `bundler`, and `externalPackages` staging check the archive before upload:
+
+| Limit                    | Value   |
+| ------------------------ | ------- |
+| Compressed zip           | 10 MiB  |
+| Total uncompressed bytes | 64 MiB  |
+| Files in the archive     | 4,096   |
+
+Exceeding one fails the deploy. The byte-limit errors list the four largest files. Check an executable's size before building around it: a single static binary can use most of the 64 MiB.

package/dist/global-skills/neon-object-storage/SKILL.md

@@ -15,6 +15,7 @@ description: >-
 metadata:
   parent: neon
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-object-storage
+disable-model-invocation: true
 ---
 
 **FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.

package/dist/global-skills/neon-postgres/SKILL.md

@@ -13,6 +13,7 @@ description: >-
 metadata:
   parent: neon
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres
+disable-model-invocation: true
 ---
 
 **FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.

package/dist/global-skills/neon-postgres-branches/SKILL.md

@@ -12,6 +12,7 @@ description: >-
 metadata:
   parent: neon
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres-branches
+disable-model-invocation: true
 ---
 
 **FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.

package/dist/global-skills/neon-postgres-egress-optimizer/SKILL.md

@@ -12,6 +12,7 @@ description: >-
 metadata:
   parent: neon
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres-egress-optimizer
+disable-model-invocation: true
 ---
 
 **FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.