@agent-native/core 0.122.4 → 0.123.1

package/corpus/templates/clips/.agents/skills/crm-call-evidence/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: crm-call-evidence
+description: >-
+  The narrow `prepare-crm-call-evidence` contract and the approved CRM A2A
+  recipe boundary.
+  Use when a CRM, sales, or A2A workflow asks for call evidence, a clip link
+  for a deal, or a `clip.created` automation trigger.
+---
+
+# CRM Call Evidence
+
+## Rule
+
+Use `prepare-crm-call-evidence` only for a viewer-accessible recording that is
+explicitly identified by a user action or by the exact approved CRM A2A recipe.
+Never call it to fish for a plausible clip.
+
+## What it returns
+
+- An opaque clip ID.
+- A durable HTTPS `/r/<id>` page.
+- Optionally, the capture time for the CRM record.
+
+## What it never returns
+
+It never returns the event media URL, a transcript, a temporary token, a quote,
+or a summary. If a CRM workflow needs more than a link, stop and ask the user
+rather than widening the payload.
+
+## Automation triggers
+
+A CRM recipe may install a Clips-owned `clip.created` trigger only through an
+exact, user-approved A2A automation definition. Do not synthesize a trigger,
+broaden its filter, or reuse it for another recipe.
+
+## Related skills
+
+- `a2a-protocol` — how approved agent-to-agent recipes are defined and called.
+- `video-sharing` — the access model behind a viewer-accessible recording and
+  the `/r/<id>` share page.
+- `security` — why the payload stays link-only.

package/corpus/templates/clips/.agents/skills/dictate/SKILL.md

@@ -54,6 +54,10 @@ The `cleanup-transcript` action resolves credentials in this order — **always
 
 The "Cleanup transcripts with AI" toggle in Settings → Voice & Transcription gates whether cleanup runs automatically (default ON when Builder is connected).
 
+Pass bounded `voiceContext` (active app context, learned vocabulary, user notes,
+AGENTS.md preferences) into the shared cleanup path — see the `ai-video-tools`
+skill's "Bounded voice context" section.
+
 ## Navigation state
 
 The app exposes `view` and `dictationId`:

package/corpus/templates/clips/.agents/skills/external-integrations/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: external-integrations
+description: >-
+  How Clips connects to Slack and Atlassian/Jira, and the provider-API
+  boundary for credentialed integrations.
+  Use when installing or debugging the Slack app, connecting Atlassian/Jira, or
+  adding raw provider API access to a Clips integration.
+---
+
+# External Integrations
+
+## Slack
+
+Slack installs should go through the Clips Settings OAuth flow (`connect-slack`,
+`/api/slack/oauth/callback`) so each Slack workspace gets its own encrypted bot
+token in `app_secrets`. `SLACK_BOT_TOKEN` is only a legacy single-workspace
+fallback and must remain behind the team allowlist.
+
+Link previews are handled by the unfurl webhook; see the **video-sharing** skill
+for the `/api/slack/unfurl` contract, the required scopes and events, and which
+clips may produce a playable video block.
+
+## Atlassian / Jira
+
+Atlassian/Jira is available through the shared MCP integration catalog. It uses
+Atlassian Rovo MCP OAuth. Explain that an Atlassian organization admin may need
+to allow the Clips app domain and enable the required Read, Write, and Search
+permissions before the connection can complete.
+
+## Provider API boundary
+
+Credentialed provider integrations normally belong on the shared provider API
+substrate (`provider-api-catalog`, `provider-api-docs`,
+`provider-api-request`). Clips has one deliberate exception: Google Calendar.
+Calendar grants live in Clips `calendar_accounts` with encrypted `app_secrets`
+token refs rather than core `oauth_tokens`, so raw provider requests would
+bypass the account sharing/status boundary. See the **meetings** skill before
+touching that path.
+
+## Related skills
+
+- `video-sharing` — Slack unfurl route, scopes, and playable-clip rules.
+- `meetings` — Google Calendar connection model and why raw provider requests
+  are not wired up yet.
+- `security` — encrypted per-workspace credential storage in `app_secrets`.

package/corpus/templates/clips/.agents/skills/frontend-design/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: frontend-design
 description: >-
-  Create distinctive, production-grade frontend interfaces with high design
-  quality. Use when building web components, pages, artifacts, posters, or
-  applications (websites, landing pages, dashboards, React components,
-  HTML/CSS layouts, or when styling/beautifying any web UI). Generates
-  creative, polished UI that avoids generic AI aesthetics.
+  Sets the visual direction for a new or redesigned surface, with production
+  quality that avoids generic AI aesthetics. Use when building a new page,
+  app, or marketing surface, defining visual identity, or doing a design pass
+  ("make this look good"). Do not load it for routine UI edits: adding a field
+  to an existing form, fixing spacing, wiring a button, or changing copy.
 scope: dev
 license: Complete terms in LICENSE.txt
 source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
+local-changes: >-
+  Description narrowed and Verification rescoped deliberately; an upstream sync
+  must not restore the broad auto-load triggers or screenshot-everything step.
 metadata:
   internal: true
 ---
@@ -141,11 +144,22 @@ Avoid:
 
 ## Verification
 
+Match verification effort to the size of the change. For one component, one
+form, one page, or a restyle, run the app's existing checks — formatter,
+`pnpm typecheck`, existing tests — and stop there.
+
+Escalate to browser verification only when the user asks for it, or when the
+change is a multi-step user-visible flow that cannot be confirmed any other
+way. Never author a new Playwright/Puppeteer script, add a browser-automation
+dependency, or stand up an e2e harness to check work the user did not ask you
+to test that way; use an available browser tool, or say what you could not
+verify.
+
 For substantial frontend work:
 
 1. Run the relevant formatter/checks.
 2. Start the dev server when the app needs one.
-3. Verify with browser screenshots at desktop and mobile widths.
+3. Verify with the available browser tooling at desktop and mobile widths.
 4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
 5. When registering or changing a company adapter, run
    `@agent-native/toolkit/conformance`, including mixed-overlay focus,

package/corpus/templates/clips/.agents/skills/meetings/SKILL.md

@@ -91,6 +91,15 @@ When meetings are enabled, the Clips desktop app also watches for native Zoom (`
 
 All actions go through `accessFilter` / `assertAccess`. AI work delegates via `sendToAgentChat` per the `delegate-to-agent` skill — never inline LLM calls.
 
+### Calendar provider-API boundary
+
+These calendar-sourced actions are shortcuts, not a capability ceiling — but do
+not add raw `provider-api-request` access for Google Calendar until the provider
+API runtime can resolve Clips `calendar_accounts` through sharing/access checks
+and read their encrypted `app_secrets` token refs. Clips calendar grants are not
+stored in core `oauth_tokens`, so bypassing that model would break the account
+sharing/status boundary.
+
 ## Sharing meeting notes and transcripts
 
 Meeting share links always include generated notes: the summary, key points,

package/corpus/templates/clips/.agents/skills/recording/SKILL.md

@@ -59,6 +59,16 @@ routes with native capture primitives:
 Mobile audio M4A is an MP4 container and uses the recording route's MP4 MIME
 alias. The bytes are not converted or loaded whole into JavaScript memory.
 
+Because the phone persists each audio/video file before any network work and
+resumes bounded chunk uploads from its durable queue, a transient upload failure
+never loses the capture. Do not ask users to keep a capture screen open or to
+re-record after a failed upload; tell them to reconnect Clips and retry the
+saved job from mobile Home.
+
+Mobile meeting capture is microphone-only; never claim it has the desktop
+mic-plus-system-audio fidelity. See the **meetings** skill for what that means
+for attendee attribution.
+
 ## Seekable playback (don't ship raw MediaRecorder output)
 
 Raw `MediaRecorder` files are not friendly to progressive HTTP playback, which
@@ -109,6 +119,12 @@ dimensions. When Loom exposes a signed public transcript JSON URL on the share
 page, the action imports that transcript into Clips and stores normalized
 segments; never store Loom's signed CDN URLs.
 
+When Loom exposes a downloadable public MP4, `import-loom-recording` downloads
+it, reuploads the bytes to Clips storage, and creates a ready, playable
+Clips-hosted recording, importing Loom's public transcript when the share page
+exposes one. If Loom does not expose a downloadable MP4, ask the user to download
+the original from Loom and use "Upload video".
+
 Loom imports are embed-backed, not Clips-owned video files. The player renders a
 Loom iframe and the native Clips editor is hidden for those recordings. If the
 user needs Clips-native trimming, exports, frame extraction, or upload-based
@@ -131,6 +147,35 @@ most seamless native capture. Set `VITE_CLIPS_CHROME_EXTENSION_ENABLED=0` to hid
 the Chrome option again, or `VITE_CLIPS_CHROME_EXTENSION_URL` to point at a
 different listing.
 
+`save-browser-diagnostics` is UI/internal. It stores bounded console logs plus
+fetch/XHR method, URL path/query keys, status, and duration. It never captures
+headers, bodies, cookies, or network URL query values. Console text keeps useful
+non-secret values while redacting credential-looking keys and headers. Use
+`get-recording-player-data` for the full diagnostics payload when you have
+editor access; see the **video-sharing** skill for the narrower redacted stream
+that public agent context exposes.
+
+## Chrome extension
+
+The extension lives in `chrome-extension/`. It launches `/record` with
+`clipsExtensionId` and `clipsCaptureSessionId`, and the recorder sends
+`CLIPS_CAPTURE_START` / `CLIPS_CAPTURE_STOP` / `CLIPS_CAPTURE_CANCEL` back to the
+extension. It uses the Chrome debugger API only on the tab the user launched
+from, only while a recording is active, and returns the same redacted
+diagnostics shape saved by `save-browser-diagnostics`.
+
+The extension also enhances GitHub issue and PR markdown: a narrow `github.com`
+content script detects Clips `/r/`, `/share/`, and `/embed/` links, then renders
+the existing `/embed/:id` player in an extension-owned preview iframe so the
+video is playable without leaving GitHub. Keep this scoped to GitHub unless there
+is a deliberate permission review.
+
+## Folders, spaces, and bulk moves
+
+Use `move-recording` for both single and bulk folder moves. Pass `id` for one
+clip or `ids` for the selected clips, and `folderId: null` to move them to the
+library or space root.
+
 ## Pause / resume
 
 `MediaRecorder.pause()` / `.resume()` are supported in all evergreen browsers. Keep a single `MediaRecorder` instance across pauses — don't tear down the stream, or the permission prompt will fire again. While paused, the upload worker keeps draining its buffer so we catch up before the user stops.

package/corpus/templates/clips/.agents/skills/screen-memory/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: screen-memory
+description: >-
+  Screen Memory — the disabled-by-default, local-only desktop buffer of recent
+  screen/app/window context, plus its status and query actions.
+  Use when the user asks what was on screen recently, or when reading,
+  exporting, enabling, or describing Screen Memory.
+---
+
+# Screen Memory
+
+## Rule
+
+Screen Memory is a disabled-by-default, local-only desktop buffer of recent
+screen, app, and window context. It is not a hosted Clips recording, and never
+describe it as hosted, shared, exhaustive, or enabled by default.
+
+## Reading it from the in-app agent
+
+1. Call `get-screen-memory-status` before relying on it at all.
+2. Then call `query-screen-memory-context` for bounded recent snippets when
+   local context files are present.
+
+If the local Screen Memory MCP built-in is connected, the agent may also use
+`screen_memory_status`, `screen_memory_recent_context`, and
+`screen_memory_recent_segments`. Only inspect or export segment file paths when
+the user explicitly asks.
+
+## User control and external agents
+
+Users enable, pause, export, and clear the buffer from the desktop tray
+settings. External local agents can read recent app/window context through
+`agent-native mcp screen-memory`.
+
+Do not upload raw Screen Memory segments or treat them as shareable Clips unless
+the user explicitly exports and imports them.
+
+## Related skills
+
+- `recording` — the hosted capture path Screen Memory is not part of.
+- `security` — why local-only context stays local.
+- `context-awareness` — the supported way the agent learns what is on screen
+  inside Clips.

package/corpus/templates/clips/.agents/skills/security/SKILL.md

@@ -127,6 +127,8 @@ Two more CI guards (also wired into `pnpm prep`) target the 2026-04 cross-tenant
 - `scripts/guard-no-env-mutation.mjs` — bans `process.env.<KEY> = …` (and bracket / compound forms) anywhere in production code. On serverless, every warm container handles many concurrent requests in one Node process, so `process.env` mutation leaks across in-flight requests (the "restore" line at the end of a handler races and never helps — most recently the Zoom webhook). Use `runWithRequestContext({ userEmail, orgId, timezone }, fn)` from `@agent-native/core/server` instead — it's AsyncLocalStorage-backed and per-request safe. Allowlisted paths: `scripts/`, `*.spec.ts` / `*.test.ts`, `packages/core/src/dev**`, `templates/*/test/`, anything under `/cli/` or `/scaffold/`. Per-line opt-out: `process.env.X = y // guard:allow-env-mutation — <reason>`.
 - `scripts/guard-no-localhost-fallback.mjs` — bans the literal `"local@localhost"` / `'local@localhost'` / `` `local@localhost` `` in production code. The bug class: `getRequestUserEmail() ?? "local@localhost"` silently pools every unauthenticated request into a single shared tenant, leaking credentials, tools, and `application_state` rows between accounts. The right behavior is to throw / 401 when there's no session. Allowlisted paths: the dev-mode auth shim (`packages/core/src/server/auth.ts`), `packages/core/src/dev**`, tests, `scripts/`, `seed/` / `seeds/`, plus a few framework helpers that intentionally inspect or migrate the dev identity. SQL DDL `DEFAULT 'local@localhost'` and the Drizzle helper `.default('local@localhost')` are skipped per-line — schema column defaults are intentional dev fixtures, not the dangerous fallback pattern. Per-line opt-out: `email ?? "local@localhost" // guard:allow-localhost-fallback — <reason>`.
 
+  The same guard also bans the **ambient process identity** as a request-scoped fallback: `?? process.env.AGENT_USER_EMAIL`, `|| process.env.WORKSPACE_OWNER_EMAIL`, and `?? getAmbientUserEmail()`. Those name the identity of the *deployment*, not the caller, so a handler reading one authorizes whoever the deploy env names rather than whoever signed in — it fails open toward more privilege. Exempt paths are the ones with no request by construction: `scripts/` (including `templates/*/scripts/`), `src/cli/`, `src/scripts/`, `script-helpers.ts` / `script-entries.ts`, tests, and seeds. It deliberately matches only the `??` / `||` fallback position, so reading the same env var to build an admin allowlist (`envEmails("WORKSPACE_OWNER_EMAIL").includes(email)`) is untouched. Known gaps, both requiring dataflow analysis the guard does not do: an env read aliased through a local (`const fallback = process.env.AGENT_USER_EMAIL; … ?? fallback`) and a destructured `const { AGENT_USER_EMAIL } = process.env`.
+
 ## Auth
 
 - All actions are protected by the auth guard automatically.

package/corpus/templates/clips/.agents/skills/self-modifying-code/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: self-modifying-code
 description: >-
-  How the agent can modify the app's own source code. Use when the agent needs
-  to edit components, routes, styles, or scripts, when designing UI for agent
-  editability, or when deciding what the agent should and shouldn't modify.
+  Tiers, checkpoints, and off-limits paths for an agent editing the app's own
+  source. Use when designing UI for agent editability, deciding whether a file
+  is safe for the agent to change, or when tempted to patch config, `.env`, or
+  an `@agent-native/*` package. Do not load it for ordinary source edits.
 scope: dev
 metadata:
   internal: true

package/corpus/templates/clips/.agents/skills/shadcn-ui/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: shadcn-ui
 description: >-
-  Use when adding, updating, debugging, styling, or composing shadcn/ui
-  components, forms, dialogs, menus, charts, sidebars, themes, registries, or
-  any project with a components.json file.
+  The shadcn CLI, component composition, theming, and registry workflow. Use
+  when adding, replacing, upgrading, or debugging a shadcn/ui primitive itself,
+  or when changing a theme or registry. Do not load it for ordinary edits to a
+  file that happens to import a shadcn component.
 scope: dev
 source: https://ui.shadcn.com/docs/skills
+local-changes: >-
+  Description narrowed deliberately; an upstream sync must not restore the
+  "any project with a components.json file" trigger.
 metadata:
   internal: true
 ---

package/corpus/templates/clips/.agents/skills/video-sharing/SKILL.md

@@ -20,6 +20,12 @@ Embedded bug-report recordings are the exception and default to organization
 visibility. Callers can still explicitly create a private or organization-only
 recording, and owners/admins can change visibility from the Share dialog.
 
+Organization admins can use `set-organization-branding` with
+`defaultVisibility=public|org|private` to choose the visibility applied when new
+recordings omit an explicit visibility. The default remains `public`, and an
+explicit visibility always wins — which is why bug-report recordings still land
+on `org`.
+
 Clips **adds two things** on top of the framework system:
 
 1. **Password** — an optional bcrypt'd string on the `recordings` row. When set, all non-owner viewers must enter it to play the recording.
@@ -84,7 +90,17 @@ Use `list-recordings --view=shared` to list recordings the current user can
 access but does not own. The filter composes with `accessFilter`, so it includes
 direct user/org grants and organization-visible recordings while excluding
 public-link-only clips. The UI exposes the same collection at `/shared`; use
-`navigate --view=shared` to open it.
+`navigate --view=shared` to open it. `view-screen` returns the recordings
+currently visible in that collection.
+
+## Discovery boundary for public clips
+
+Public recordings are unlisted-by-link for agent purposes: an agent may discover
+only recordings the current user owns or has already viewed. Do not use
+`list-recordings` or `search-recordings` to discover another user's public clips,
+to answer a time/date question about the clip already in context, or to recover
+from a failed direct lookup. If the user supplies another clip's share URL or id,
+use that explicit reference; otherwise stop and report the lookup failure.
 
 ## Access resolution
 
@@ -196,9 +212,14 @@ temporary agent-link path:
 - Password-protected clips require `password=<pw>` once; successful JSON
   responses include short-lived tokenized links so the plaintext password is not
   copied into downstream agent prompts, browser history, or logs.
+- If a discovery, context, or transcript payload reports `agentReadiness.state`
+  as `"preparing"` (the clip is `"uploading"` or `"processing"`), wait 15 seconds
+  and retry `agentContextUrl`. Do not open the share page, fetch frames, or draw
+  conclusions until the recording status is `"ready"`.
 - If the context or transcript response reports `transcript.status` as
   `"pending"`, wait 15-30 seconds and retry the context/transcript URL a few
   times before falling back to frames or telling the user no transcript exists.
+  Long recordings are the common case here.
 - If transcription failed because Builder transcription credits are exhausted,
   tell the user to upgrade or connect Builder.io credits, or configure a Groq
   key for backup speech-to-text. Generic OpenAI or Anthropic chat keys do not
@@ -206,6 +227,22 @@ temporary agent-link path:
 - Frame extraction must use the checked recording media path and must not expose
   raw provider URLs.
 
+Public agent context also exposes the recording's redacted browser diagnostics:
+the console stream (all levels) as `browserDiagnostics.consoleLogs` and the
+fetch/XHR stream as `browserDiagnostics.networkRequests` (method, sanitized URL
+with query values redacted, status, duration), plus `consoleIssues` and
+`failedNetworkRequests` highlights. All of it is bounded, and page URL, headers,
+bodies, and cookies stay omitted.
+
+Password-protected clips require the password once to mint a short-lived token,
+which is returned inside the agent-context links.
+
+Use the `@agent-native/core/server` and `@agent-native/core/shared` agent-access
+helpers for scoped token mint/verify and bot-visible URL construction. Keep
+Clips-specific visibility, password, transcript, frame, and player behavior in
+Clips. New URLs should use `agent_access`; existing agent API routes should keep
+accepting legacy `t` tokens so already-copied links do not break.
+
 The share popover's "Share with agents" field should copy an agent context URL
 or tokenized share page URL, not raw transcript text. Its "Copy agent prompt"
 field may wrap that URL with instructions to fetch transcripts, frames, and