@prismer/runtime 2.2.55 → 2.2.63

package/built-in-skills/prismer-box/references/cli-guide.md

@@ -0,0 +1,133 @@
+# Box CLI guide
+
+Run Box commands through the actual available terminal tool. Prefer the documented command in this skill over exploratory help calls. Use help only when a required option is absent here or the installed CLI rejects the syntax.
+
+## Use one command runner
+
+Resolve one command runner before any Box operation:
+
+1. Check whether `box` already resolves in the runtime shell (`command -v box` on macOS/Linux or `Get-Command box` in PowerShell). If it does, use that command as-is, regardless of where Hermes or Box CLI was installed.
+2. If it does not resolve, install and verify an isolated CLI under a writable, persistent Hermes runtime directory. Require `PRISMER_BOX_TOOLS_DIR` to be an approved absolute private tools directory. It isolates installation only, not Box credentials; authenticated runtime isolation is a separate prerequisite.
+3. If that directory is not writable, ask for a writable persistent directory in the runtime. Do not assume Hermes's source checkout, a global npm prefix, or a user home is writable. If a nonstandard existing CLI is not on `PATH`, ask for its executable path instead of scanning the machine.
+
+Only use `npm exec --prefix` after Hermes installed and verified that exact local copy. Run each installation block below as one terminal call, record the verified absolute prefix it prints, and use that literal path in later calls. Never depend on a shell variable surviving a separate Hermes terminal call, and never give the user an unverified `npm exec --prefix` command to run.
+
+Box CLI 4 requires Node.js 18 or newer. Before installing, run `node --version` and `npm --version` in the same runtime and shell Hermes will use. If Node is missing or its major version is below 18, ask for approval to install or activate a supported Node runtime using the environment's normal mechanism, then rerun both checks. If npm is unavailable or the filesystem is not writable, ask for the runtime-appropriate installation or writable Hermes home; do not assume a system package manager, a desktop, or elevated privileges.
+
+On macOS/Linux:
+
+```bash
+node --version
+npm --version
+BOX_CLI_HOME="${PRISMER_BOX_TOOLS_DIR:?Set an approved private absolute tools directory}"
+mkdir -p "$BOX_CLI_HOME"
+npm install --prefix "$BOX_CLI_HOME" @box/cli
+npm exec --prefix "$BOX_CLI_HOME" -- box --version
+cd "$BOX_CLI_HOME" && pwd -P
+```
+
+On Windows PowerShell:
+
+```powershell
+node --version
+npm --version
+if (-not $env:PRISMER_BOX_TOOLS_DIR) { throw "Set an approved private absolute tools directory" }
+$boxCliHome = $env:PRISMER_BOX_TOOLS_DIR
+New-Item -ItemType Directory -Force -Path $boxCliHome | Out-Null
+npm install --prefix $boxCliHome @box/cli
+npm exec --prefix $boxCliHome -- box --version
+Resolve-Path $boxCliHome
+```
+
+Keep the resolved runner for the whole task. When Hermes installed the local copy, replace the leading `box` in every example with the applicable `npm exec --prefix` runner below. Otherwise run the examples with the already-resolved `box` command.
+
+The examples in other references use `bash` fences and POSIX `\` continuations. In PowerShell, keep the same Box arguments but run the command on one line or use PowerShell's backtick continuation. Use PowerShell variables only in PowerShell examples.
+
+On macOS/Linux:
+
+```bash
+npm exec --prefix "<VERIFIED_ABSOLUTE_PREFIX>" -- box
+```
+
+On Windows PowerShell:
+
+```powershell
+npm exec --prefix "<VERIFIED_ABSOLUTE_PREFIX>" -- box
+```
+
+For example on macOS/Linux:
+
+```bash
+npm exec --prefix "<VERIFIED_ABSOLUTE_PREFIX>" -- box users:get me --json --fields id,name,login
+```
+
+Do not attempt a global npm install, use `sudo`, change npm's global prefix, or change `PATH`.
+
+## Check identity and control output
+
+On macOS/Linux:
+
+```bash
+command -v box
+box --version
+box users:get me --json --fields id,name,login
+box folders:items 0 --json --max-items 20 --fields id,name,type
+```
+
+On Windows PowerShell:
+
+```powershell
+Get-Command box -ErrorAction SilentlyContinue
+box --version
+box users:get me --json --fields id,name,login
+box folders:items 0 --json --max-items 20 --fields id,name,type
+```
+
+Use `--json` for machine-readable output and `--fields` to return only needed fields. Folder `0` is the current actor's root, not a complete access inventory: do not use its listing to reject a shared file or folder, and never use it to discover Box Hubs.
+
+## Environments and actors
+
+```bash
+box configure:environments:list
+box configure:environments:set-current <ENVIRONMENT_NAME>
+box users:get me --json --fields id,name,login
+```
+
+The CLI has one current environment. Confirm before switching it, then verify the actor. Perform ordinary Hermes work as the OAuth identity selected for that environment; do not impersonate another user.
+
+An isolated npm installation isolates the CLI executable, not its authenticated environments. Box CLI stores environments and tokens for the runtime's OS user, using the platform credential store when available and `~/.box` as a fallback. Hermes profiles and concurrent sessions running as the same OS user can therefore share the current Box environment. Warn about this shared state during setup, verify the actor before every task, and explain that changing the current environment can affect other Hermes sessions and ordinary Box CLI use under that OS account.
+
+On Linux, Box CLI secure storage depends on Secret Service/libsecret support. If the CLI reports a plaintext fallback, warn that credentials may be stored in `~/.box/box_environments.json` and token-cache files. Do not read or print those files. Recommend configuring the runtime's supported Secret Service/libsecret package or using a properly isolated runtime user before production use; do not assume a package manager or require another confirmation merely to deliver the warning.
+
+## Pagination and search
+
+```bash
+box folders:items <FOLDER_ID> --json --max-items 100 --fields id,name,type
+box search "quarterly review" --json --limit 20 --fields id,name,type,parent
+box metadata-query enterprise_12345.contractTemplate <ANCESTOR_FOLDER_ID> \
+  --query "status = :status" --query-param status=active --json
+```
+
+Paginate inventories fully before bulk work. Metadata queries require the template scope/key and an ancestor folder ID.
+
+## REST escape hatch
+
+When the CLI has no dedicated command, preserve its configured auth with `box request` and perform the ordinary requested operation. Do not stop to ask simply because this uses REST; read [REST API fallback](rest-api.md) for endpoint-specific bodies and headers.
+
+```bash
+box request /files/<FILE_ID> --json
+box request /files/<FILE_ID> -X PUT --body '{"name":"renamed.pdf"}' --json
+box request /folders -X POST --body '{"name":"New folder","parent":{"id":"0"}}' --json
+```
+
+Use `box request` as the CLI-based REST fallback. Use an SDK or raw HTTP only when the CLI is unavailable or application code genuinely needs direct REST.
+
+## Batch inputs and mutations
+
+Many Box CLI commands accept `--bulk-file-path` for CSV or JSON input. Use it only after inventorying the target set and confirming material writes. For ordered moves, version updates, and other recoverable mutations, keep an operation log and process serially. Use bounded concurrency in application SDK code only when its retry and rate-limit behavior is explicit.
+
+## Confirmation rules
+
+- Confirm before deletes, access changes, identity changes, broad moves, or an ambiguous target.
+- Confirm the scope before an AI-unit-consuming bulk request.
+- Do not pass `--yes` unless the user has already approved the exact operation.

package/built-in-skills/prismer-box/references/content-workflows.md

@@ -0,0 +1,86 @@
+# Content workflows
+
+Use IDs, not paths, once an item is resolved. If the current OAuth identity cannot see the target, verify the exact item ID and ask the owner to invite that identity to the intended file, folder, or Hub.
+
+## Browse and create folders
+
+```bash
+box folders:get <FOLDER_ID> --json --fields id,name,parent,item_collection
+box folders:items <FOLDER_ID> --json --max-items 100 --fields id,name,type
+box folders:create <PARENT_ID> "Customer-123" --json --fields id,name,parent
+```
+
+Duplicate names in one parent return `409`. Reuse the existing folder ID instead of retrying blindly.
+
+## Verify a shared file or folder
+
+When the current OAuth identity receives a file or folder invite, use the ID from its Box URL if available and fetch that exact item. Do not use an absence from folder `0` as proof that access failed; it is only that identity's root listing. If only a name is known, use Box search to resolve the ID, then fetch the item:
+
+```bash
+box search "Quarterly plan" --json --limit 20 --fields id,name,type,parent
+box files:get <FILE_ID> --json --fields id,name,parent
+box folders:get <FOLDER_ID> --json --fields id,name,parent
+```
+
+Use [Box Hubs](hubs.md) for a Hub invite: Hubs are not files or folders and are discovered separately.
+
+## Upload, download, and version files
+
+```bash
+box files:upload ./artifact.pdf --parent-id <FOLDER_ID> --json --fields id,name,size
+box files:get <FILE_ID> --json --fields id,name,size,sha1,parent
+box files:download <FILE_ID> --destination . --save-as local-copy.pdf
+box files:versions:upload <FILE_ID> ./updated.pdf --json --fields id,name,sha1
+box files:versions:list <FILE_ID> --json
+box files:versions:download <FILE_ID> <VERSION_ID> --destination . --save-as older.pdf
+```
+
+Download source bytes only when the task truly requires local editing or the user explicitly approves external analysis. Prefer a new version over replacing an unrelated file by name.
+
+## Create native Box Notes
+
+When the user asks for a Box Note, create a native note from Markdown through `box request`; do not substitute an uploaded text file named `.boxnote`. Read [REST API fallback](rest-api.md) for the exact request and verification command. Create it immediately when the destination is explicit or unambiguously the actor's root; otherwise ask which folder to use.
+
+## Rename, tag, and move
+
+```bash
+box files:update <FILE_ID> --name "Renamed.pdf" --json --fields id,name
+box files:update <FILE_ID> --description "Updated by Hermes" --tags "reviewed,2026" --json
+box files:move <FILE_ID> <NEW_PARENT_ID> --json --fields id,name,parent
+box folders:move <FOLDER_ID> <NEW_PARENT_ID> --json --fields id,name,parent
+```
+
+Read back the item or its parent after every write. Moving a folder moves its contents; confirm broad moves before executing them.
+
+## File descriptions
+
+Treat 255 characters as the safe file-description limit; Box can truncate longer values. Never use a description as a fallback for extracted metadata. Set one only when the user explicitly asks for a description, verify that the complete intended text fits before writing, then fetch the file and compare the returned description with the intended value. Use [Search and AI](search-and-ai.md) to persist extracted results as metadata or a JSON sidecar instead.
+
+## Collaborate and share
+
+```bash
+box collaborations:create <FOLDER_ID> folder --role editor --login collaborator@example.com --json
+box shared-links:create <FILE_ID> file --access company --json
+box shared-links:create <FOLDER_ID> folder --access open --json
+```
+
+Use the narrowest collaboration role. Creating or widening a shared link changes access, so require explicit confirmation.
+
+## Navigate without changing permissions
+
+Report these links for items already known to the caller; they do not create a shared link:
+
+- File: `https://app.box.com/file/<FILE_ID>`
+- Folder: `https://app.box.com/folder/<FOLDER_ID>`
+
+Include the item ID with the link. If a human cannot open an item visible only to the connected Box account, state that rather than creating a link with broader access.
+
+## Read and write metadata
+
+```bash
+box files:metadata:get <FILE_ID> --scope global --template-key properties --json
+box files:metadata:create <FILE_ID> --scope global --template-key properties \
+  --data invoice_id=INV-001 --json
+```
+
+`global.properties` is Box's built-in schema-free metadata instance; no template creation is required. Its values are not a reusable typed enterprise schema and cannot be used by the Metadata Query API. Read all existing metadata instances before writing so unrelated properties are preserved. Use [Search and AI](search-and-ai.md) when metadata must be extracted from document content; do not use a partial, unrelated, or incomplete enterprise template.

package/built-in-skills/prismer-box/references/hubs.md

@@ -0,0 +1,77 @@
+# Box Hubs
+
+Use a Box Hub for recurring Q&A over a curated knowledge base. A direct Box AI Ask request handles up to 25 selected files; a Hub request sends one `hubs` item and searches the Hub's indexed content. Do not use a Hub for metadata extraction or text generation.
+
+## Check availability and discover an existing Hub
+
+The Box Free Developer Plan includes the Hubs API, Box AI APIs, and a monthly AI-unit allowance for building and testing. Do not apply Box web-app plan wording as a blanket API restriction. The CLI calls the same APIs and does not bypass account entitlements: production availability still depends on the organization's plan and Box configuration.
+
+Before the first Hub AI request, explain that Box AI must be enabled and consumes AI units; do not wait for acknowledgement. Explain that answers only use indexed files the current actor can access. Hubs are not files or folders: never use `folders:items 0` to discover or reject a Hub invitation. Confirm the current actor, then list accessible Hubs before proposing a new one:
+
+```bash
+box users:get me --json --fields id,name,login
+box hubs --scope all --max-items 1000 --json
+box hubs --query "Product" --scope all --sort relevance --json
+box hubs:get <HUB_ID> --json
+box hubs:items <HUB_ID> --max-items 100 --json
+```
+
+For a known Hub URL or ID, run `box hubs:get <HUB_ID>` directly even if the list is empty. Report each Hub as `https://app.box.com/hubs/<HUB_ID>`. Check `is_ai_enabled` before asking a question, then make one bounded Hub Ask request to verify actual API availability. Box AI for Hubs must have been enabled before the Hub was created so Box can index its content. If Hub AI is unavailable, distinguish a disabled feature, a Hub created before AI enablement, indexing delay, missing Hub collaboration, missing access to underlying files, and exhausted AI units; do not silently download source files into Hermes' model context.
+
+## Ask questions across a Hub
+
+Use one Hub item and `single_item_qa`. Request citations so Hermes can report the source files behind an answer. Use `box request` (or the SDK) for Hub Q&A rather than relying on `box ai:ask`, whose installed CLI versions may not accept Hub item types. This uses the Box AI Ask endpoint; the `box-version: 2025.0` header is required for `/hubs` management endpoints, not this request.
+
+```bash
+box request /ai/ask -X POST \
+  --body '{"mode":"single_item_qa","items":[{"id":"<HUB_ID>","type":"hubs"}],"prompt":"Summarize the approved renewal terms and cite each source.","include_citations":true}' \
+  --json
+```
+
+State the Hub ID and navigation link with the answer. List cited file IDs, names, and file links when Box returns citations. Treat an answer as bounded by indexed, accessible Hub content; do not claim it searched files that have not indexed or that the actor cannot access.
+
+## Create and populate a Hub
+
+Do not create a Hub automatically. For Q&A over more than 25 files or a reusable curated collection, discover an existing accessible Hub first. If none fits, offer to create a curated Hub and obtain explicit approval before creating or populating it. If the user declines, narrow the one-off scope with search or metadata instead.
+
+After approval, create it, report its link, and verify it:
+
+```bash
+box hubs:create "Policy knowledge base" --description "Approved policy reference" --json
+box hubs:get <HUB_ID> --json
+```
+
+Adding an item curates a reference; it does not move the underlying file or folder. A clearly requested small addition may proceed without a redundant prompt. Confirm before bulk additions or removals, then verify every returned result and read back the Hub items. The API can return partial success for multi-item changes, so do not treat a successful request alone as proof that every item was added.
+
+```bash
+box hubs:items:manage <HUB_ID> \
+  --add id=<FILE_ID>,type=file --json
+box hubs:items:manage <HUB_ID> \
+  --add id=<FOLDER_ID>,type=folder --json
+box hubs:items <HUB_ID> --max-items 100 --json
+```
+
+Without `parent-id`, the CLI adds the item to the first Item List block. To target a specific Item List block, first list pages with `box hubs:document:pages <HUB_ID> --json`, retrieve blocks with `box hubs:document:blocks <HUB_ID> <PAGE_ID> --json`, then pass the returned Item List block ID as `parent-id`.
+
+Confirm before enabling or disabling Hub AI, deleting or copying a Hub, or changing shared access. Verify each change with `box hubs:get`, `box hubs:items`, or `box hubs:collaborations`:
+
+```bash
+box hubs:update <HUB_ID> --ai-enabled --json
+box hubs:collaborations <HUB_ID> --max-items 100 --json
+box hubs:collaborations:create <HUB_ID> --role viewer --user-id <USER_ID> --json
+```
+
+## Handle indexing, permissions, and limits
+
+Newly added content usually indexes within minutes but can take up to an hour. Verify the item addition, wait or retry a bounded number of times, and report a retryable indexing state instead of declaring the source absent. Diagnose permissions separately: a successful `box hubs` or `box hubs:get` proves Hub access, not access to every underlying file. Hub answers respect the querying actor's access to underlying files.
+
+Box AI for Hubs has a service limit per Hub and across the enterprise. Box's dedicated Hubs guidance currently documents 20,000 files per Hub; verify current account or product documentation when operating near the boundary. Do not present that number as an immutable guarantee. Only the first 4 MB of a supported document's text representation is indexed. Explain AI-unit use before the first request and confirm a material batch or broad Hub population.
+
+## Sources
+
+- [Box Hubs API overview](https://developer.box.com/guides/hubs-api/)
+- [Box Free Developer Plan](https://developer.box.com/guides/getting-started/free-developer-plan/)
+- [Box AI Ask API](https://developer.box.com/reference/post-ai-ask/)
+- [Ask questions about a Hub](https://developer.box.com/guides/box-ai/ai-tutorials/ask-questions/)
+- [Box AI for Hubs](https://support.box.com/hc/en-us/articles/29347206309395-Box-AI-for-Hubs)
+- [Box Hubs limits](https://support.box.com/hc/en-us/articles/28323495455123-Box-Hubs-Known-Issues-and-Limitations)

package/built-in-skills/prismer-box/references/oauth-setup.md

@@ -0,0 +1,92 @@
+# OAuth setup
+
+Use OAuth for every Hermes-to-Box connection. OAuth follows the signed-in Box user's permissions and the app's scopes; it does not grant enterprise-wide access.
+
+## Choose the OAuth account
+
+Authorize the Box account that Hermes should act as. OAuth follows that account's permissions. If the user wants a narrower permission boundary, authorize an account that is invited only to the files, folders, or Hubs Hermes should access. Do not make that account an administrator merely to unlock an exceptional operation.
+
+Everyone who uses a shared or background Hermes deployment receives the access of the one Box account it authorizes, so do not connect it to a broader personal or administrator account. Before starting the browser flow, make sure the authorization browser is signed in as the intended Box account.
+
+Choose a descriptive environment name, such as `hermes-box-oauth`. Do not overwrite or reauthorize an existing environment until its identity is confirmed.
+
+## Same-host interactive path
+
+First resolve the Box command runner using [CLI guide](cli-guide.md). Then ask whether Hermes runs on the same computer as the browser the user will use to authorize Box. Use this path only when they confirm that it does. This is normally a local computer setup. Do not infer this from the operating system alone. Use the resolved runner; do not reconstruct a local npm prefix unless Hermes installed and verified that exact local copy.
+
+Start one official local login operation without `--code`, leave its terminal process running until it exits, then verify the actor. The examples below use `box`; replace that executable with the previously verified local runner only when Hermes installed and verified a private CLI copy:
+
+```bash
+box login --default-box-app --name <ENVIRONMENT_NAME>
+box users:get me --json --fields id,name,login
+```
+
+The browser flow creates and selects the named environment. Run the action through Hermes's terminal rather than asking the user to copy a runner command. Announce the pending authorization, wait for the CLI process to finish, then continue with the actor check. Let the CLI open the authorization page and receive the local callback. Do not use browser tools, inspect browser tabs, request the resulting URL, navigate to Box, or ask the user to paste a code.
+
+If the callback server cannot bind port 3000, the browser opens an unusable authorization result, or the callback never reaches the waiting CLI, stop that login process before retrying. Retry the official app on the supported ports `3001`, `4000`, `5000`, and `8080`, one at a time, and verify the actor after each successful completion:
+
+```bash
+box login --default-box-app --port 3001 --name <ENVIRONMENT_NAME>
+```
+
+Do not switch a same-host setup to `--code` merely because port 3000 failed. Use `--code` only after the supported local ports fail or the user confirms that the authorization browser is on another host.
+
+## Separate-host or headless path
+
+Use this path only after the user explicitly confirms that Hermes runs on a remote host—such as a VPS, container, or cloud VM—or that it is headless and the authorization browser is on a different computer. Use the same previously resolved runner and run:
+
+```bash
+box login --default-box-app --code --name <ENVIRONMENT_NAME>
+```
+
+Open the displayed URL with a browser tool only when it controls the human's authorization browser. Otherwise present the URL and pause for the user to sign in and approve access, then continue the CLI's code-and-state prompts and verify the actor. Do not use this path when the same-host callback is available.
+
+## Shared-host account isolation
+
+An isolated npm prefix is not an isolated Box credential store. Do not use a
+shared OS user's current default environment concurrently for multiple tenants.
+Require an isolated connector process/account configuration from the runtime;
+verify `box users:get me` before each batch. Never switch another session's
+current account to make a command work. Missing isolation is a blocked write,
+not permission to create a new identity.
+
+## Existing environments
+
+The Box CLI stores multiple named environments but uses one current default:
+
+```bash
+box configure:environments:list
+box configure:environments:set-current <ENVIRONMENT_NAME>
+box users:get me --json --fields id,name,login
+```
+
+Request approval before switching the current environment, especially on a shared or background installation. Switch it only after approval and verify the resulting actor. If the returned identity is API-only or has no normal Box login, do not use it for Hermes; connect a normal Box account through OAuth instead.
+
+## Custom OAuth Platform App
+
+Use this path only when the requested operation needs a scope unavailable through the official CLI app, such as **Manage webhooks**. Open the [Box Developer Console](https://app.box.com/developers/console), create or select a Platform App with **User Authentication (OAuth 2.0)**, and enable only the required scopes. Never broaden scopes merely to avoid an authorization error.
+
+Use the same topology decision as the official app. For a same-host browser, add `http://localhost:3000/callback` as an OAuth redirect URI in the app's **Configuration** tab, save it, then run:
+
+```bash
+box login --platform-app --port 3000 --name <ENVIRONMENT_NAME>
+```
+
+If port 3000 cannot bind, choose another free local port, add the exact `http://localhost:<PORT>/callback` URI to the Platform App, save the configuration, stop the failed login process, and retry with the matching `--port`. Unlike the official app, a custom Platform App may use any port whose exact callback URI is registered.
+
+For a remote or headless Hermes runtime whose authorization browser is on a different computer, register the same loopback callback URI and add `--code`:
+
+```bash
+box login --platform-app --code --port 3000 --name <ENVIRONMENT_NAME>
+```
+
+Before starting the remote flow, explain that the browser may finish on an unreachable localhost page; this is expected. The resulting URL contains both `code` and `state`, which the waiting CLI requests. Ask the user for only those two values, submit them to the existing process, and then verify the actor. Do not inspect unrelated browser tabs or switch to the local callback workflow on a remote host.
+
+Let the CLI prompt for the Client ID and Client Secret. Do not ask the user to paste the Client Secret into chat, write it to Hermes configuration, or give the user an unverified local-runner command to copy. Authenticate the intended user in the browser, then verify the resulting actor. Keep administrator-only operations outside the normal Hermes OAuth identity.
+
+## Official links
+
+- [Box CLI quick start](https://developer.box.com/guides/cli/quick-start/)
+- [Box CLI headless login](https://developer.box.com/guides/cli/headless-login/)
+- [OAuth 2.0 guide](https://developer.box.com/guides/authentication/oauth2/)
+- [Box OAuth scopes](https://developer.box.com/guides/api-calls/permissions-and-errors/scopes/)

package/built-in-skills/prismer-box/references/rest-api.md

@@ -0,0 +1,37 @@
+# REST API fallback
+
+Use `box request` to extend the CLI when it has no dedicated subcommand. It reuses the configured Box identity, so continue ordinary requested work without asking the user to choose a REST fallback. Confirm only for deletes, access or identity changes, broad or costly batches, or an ambiguous target or scope. Use direct REST only when the CLI is unavailable or application code needs a raw endpoint that an SDK cannot cover.
+
+Using REST does not bypass Box metadata safety rules: inspect metadata instances and existing schemas first, never create or change a metadata template, and retrieve and compare the metadata instance after every write. Never use a file description as an implicit metadata fallback.
+
+## CLI request escape hatch
+
+```bash
+box request /files/<FILE_ID> --json
+box request /files/<FILE_ID> -X PUT --body '{"name":"renamed.pdf"}' --json
+box request /folders -X POST --body '{"name":"New folder","parent":{"id":"0"}}' --json
+```
+
+## Create a native Box Note
+
+When asked to create a Box Note, create the native note with the Box Notes API; do not upload plain text with a `.boxnote` suffix. Use the intended parent folder (use `0` only when the user's target is unambiguously their root), then fetch the returned file to verify it:
+
+```bash
+box request /notes/convert -X POST \
+  --header "box-version: 2026.0" \
+  --body '{"content":"# Hello world\n\nhello world","content_format":"markdown","parent":{"id":"0"},"name":"hello-world"}' \
+  --json
+box files:get <RETURNED_FILE_ID> --json --fields id,name,type,parent
+```
+
+`content` is Markdown and is limited to 1 MB. Report the returned file ID and its normal Box file link.
+
+## OAuth identity boundary
+
+`box request` uses the selected OAuth CLI environment. It does not bypass that user's Box permissions. If the CLI is unavailable, use an OAuth-authorized SDK client as described in [SDK development](sdk-development.md). Never echo, log, or commit OAuth tokens or client secrets.
+
+## Sources
+
+- [Box API reference](https://developer.box.com/reference/)
+- [Box Notes API: create a note from Markdown](https://developer.box.com/guides/box-notes/convert-markdown/)
+- [OAuth 2.0](https://developer.box.com/guides/authentication/oauth2/)

package/built-in-skills/prismer-box/references/sdk-development.md

@@ -0,0 +1,85 @@
+# SDK development
+
+Use this reference for shipped Box applications. For a one-off Hermes task, use the CLI references instead.
+
+## Start with the application
+
+Inspect the repository for existing Box clients, `BOX_` configuration, token storage, webhook handlers, retry policy, and language conventions. Extend the existing integration instead of mixing SDK and raw REST without a reason.
+
+## Choose an identity
+
+| Identity | Use when |
+| --- | --- |
+| OAuth | each end user connects their own Box account |
+
+OAuth follows the signed-in user's permissions and app scopes. For a shared or background application, the Box account that authorizes the application defines its access boundary; invite that account only to the files, folders, or Hubs the application needs.
+
+## Use an official SDK
+
+- [Python SDK Gen](https://github.com/box/box-python-sdk-gen)
+- [The `box` npm package](https://developer.box.com/guides/tooling/box-npm-package)
+- [Existing Node SDK projects](https://github.com/box/box-node-sdk)
+- [Other Box SDKs](https://developer.box.com/guides/tooling/sdks/)
+
+Use the SDK matching the project language. For a new JavaScript or TypeScript application, use the project's existing package manager to install the unified `box` package; with npm, run:
+
+```bash
+npm install box
+```
+
+Import its Node SDK from the explicit SDK subpath:
+
+```typescript
+import BoxSDK from "box/sdk";
+```
+
+The package also exposes a project-local Box CLI through `npx box`. Use that runner for development inside the application when useful, but do not silently replace the separately resolved Hermes CLI runner or its authenticated environment. If the project already uses `box-node-sdk`, extend that integration instead of migrating it without a concrete reason. For Python or another language, install its current official Box SDK rather than the npm package.
+
+Store OAuth tokens and any custom Platform App client secret in the project's approved secret mechanism, not source control. When a custom Platform App needs additional scopes, use **User Authentication (OAuth 2.0)** and have the intended Box user grant access; do not add an impersonation path for normal application work. Keep exceptional enterprise administration outside the normal Hermes runtime and application identity; do not elevate the account the application normally uses.
+
+## OAuth client
+
+Use the generated SDK's OAuth support rather than rebuilding authorization-code exchange or token refresh logic. Follow the installed SDK's current OAuth method names and its language-specific authorization guide when implementing a concrete call. Initialize the OAuth client before calling any SDK method, associate stored tokens with the Box user who granted them, and verify that user before performing work. Do not copy a partial SDK call into an application without its OAuth initialization and token-refresh path.
+
+## Build document-aware apps with Box AI
+
+When an application must understand Box documents, prefer Box AI: it preserves Box permissions, processes source files through Box's governed AI integration, keeps source-file bodies out of the application's external model context, and scales document work without downloading every file:
+
+- ask for Q&A and summaries;
+- structured extract for repeatable fields or a metadata template;
+- extract for variable fields;
+- text generation for output grounded in one Box file.
+
+Before the first request, explain that Box AI must be enabled and consumes AI units. Do not silently switch to external processing when Box AI is unavailable; offer an explicitly chosen alternative neutrally. Treat Box AI responses as potentially confidential application data.
+
+## Build Hub-backed knowledge experiences
+
+For a recurring Q&A experience over a curated collection, use a Box Hub rather than assembling more than 25 file items per Ask request. Discover existing Hubs first; creating a Hub, populating it, enabling its AI features, or changing its collaborations changes shared resources and requires explicit product approval. Box Hubs endpoints use API version `2025.0`.
+
+Use the generated SDK matching the project language. The exact generated method names can vary by SDK release; keep the request shape below and follow the installed SDK's current names.
+
+```python
+from box_sdk_gen import AiItemAsk, AiItemAskTypeField, CreateAiAskMode
+
+answer = client.ai.create_ai_ask(
+    CreateAiAskMode.SINGLE_ITEM_QA,
+    "What changed in the latest policy?",
+    [AiItemAsk(id=hub_id, type=AiItemAskTypeField.HUBS)],
+    include_citations=True,
+)
+```
+
+```typescript
+const answer = await client.ai.createAiAsk({
+  mode: "single_item_qa",
+  prompt: "What changed in the latest policy?",
+  items: [{ id: hubId, type: "hubs" }],
+  includeCitations: true,
+});
+```
+
+Querying a Hub uses its indexed content and only returns information from files the current actor can access. Newly added Hub content can take minutes, and occasionally up to an hour, to index; surface a retryable indexing state rather than treating an early answer as complete. The Free Developer Plan includes the Hubs and Box AI APIs for building and testing, with a monthly AI-unit allowance. Production availability depends on the organization's plan and configuration. In every environment, verify that the Hub exists, has AI enabled, and was created after Hub AI was enabled so its content can be indexed. Read [Box Hubs](hubs.md) for the CLI and operational workflow.
+
+## Webhooks and reliability
+
+Verify webhook signatures, persist idempotency keys, fetch authoritative state after events, and keep retry/backoff policy explicit. Bound concurrent API calls and make retries safe before increasing throughput. See [Webhooks and events](webhooks-and-events.md).