@agent-native/core 0.152.1 → 0.153.1

package/dist/templates/headless/.agents/skills/storing-data/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: storing-data
+description: >-
+  How to store application data in agent-native apps. All data lives in SQL.
+  Use when adding data models, deciding where to store data, or reading/writing
+  application data.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Storing Data — SQL is the Source of Truth
+
+## Rule
+
+All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. SQL stores structured records, metadata, references, and searchable text — not large raw file payloads. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+
+Large binary or file-like payloads (images, video/audio, PDFs, ZIPs, screenshots, session replay chunks, thumbnails, generated assets, `data:` URLs, and base64 file bodies) must go through configured file/blob storage such as `uploadFile()` or `putPrivateBlob()`. Persist only the returned URL, asset id, or opaque blob handle in SQL. If storage is unavailable in hosted or persistent-database mode, fail closed with setup guidance instead of falling back to base64 in `application_state`, `settings`, `resources`, or app tables. Local SQLite-only dev fallbacks may exist for tiny assets, but they must be capped, documented as dev-only, and kept off hot list/read paths.
+
+**Local File Mode exception:** some artifact apps (Content, Plans, Slides, Dashboards, Designs, etc.) can intentionally use repo files as the source of truth for the artifact itself. This must be explicit via `agent-native.json`, `AGENT_NATIVE_MODE=local-files`, or an app-owned local-file action helper. In that mode, the UI and agent still go through app actions, but those actions read/write scoped files through `@agent-native/core/local-artifacts` instead of SQL rows. App state, auth, settings, credentials, collaboration metadata, and hosted database mode remain SQL. File-to-database or file-to-provider synchronization is an explicit sync step, not an implicit side effect of editing.
+
+When you add a data model, a list, or a read path, also follow the `performance` skill: project only the columns a list renders, index the columns hot queries filter/sort on, and avoid query waterfalls — so apps stay fast as data grows.
+
+## How It Works
+
+Agent-native apps use Drizzle ORM over the configured SQL backend. Local development works out of the box with a SQLite file at `data/app.db`; production and shared preview deploys need a persistent `DATABASE_URL` because container/serverless filesystems can reset. The code should behave the same across backends, but the local SQLite file is not durable once deployed.
+
+For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
+
+### Naming migrations
+
+When you add an entry to a `runMigrations([...])` list (`@agent-native/core/db`), always give it a unique `name:` slug (e.g. `name: "analytics-alert-rules-table"`) alongside its `version`. Never renumber or reuse version numbers on existing entries.
+
+Why: version numbers alone are not a safe identity. Two branches that each independently extend the same migration list can ship different DDL under the same version numbers — whichever branch deploys first "claims" those version numbers in the bookkeeping table, and the other branch's DDL is silently treated as already applied even though it never ran. This exact collision took down analytics: parallel branches both extended their migration list through v75-v83 with different DDL, so `analytics_alert_rules`, `analytics_alert_incidents`, and `session_recordings.network_error_count` never made it to production despite the bookkeeping table showing every version as applied. A `name:` slug is tracked independently of version numbers, so it applies exactly once per database regardless of what any other branch already recorded.
+
+Existing unnamed migrations don't need to be renamed retroactively (the two gating strategies coexist), but any new entry should always carry a name.
+
+### Core SQL Stores (auto-created, available in all templates)
+
+| Store               | Purpose                                              | Access                                     |
+| ------------------- | ---------------------------------------------------- | ------------------------------------------ |
+| `application_state` | Ephemeral UI state (compose windows, navigation)     | `readAppState()` / `writeAppState()`       |
+| `settings`          | Persistent KV config (preferences, app settings)     | `getSetting()` / `putSetting()`            |
+| `oauth_tokens`      | OAuth credentials                                    | `@agent-native/core/oauth-tokens`          |
+| `sessions`          | Auth sessions                                        | `@agent-native/core/server`               |
+
+### Domain Data (per-template)
+
+Define schema with the framework Drizzle helpers in `server/db/schema.ts`. Get a database instance with `const db = getDb()` from `server/db/index.ts`. All queries are async.
+
+```ts
+import { eq } from "drizzle-orm";
+import { table, text, integer, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  completed: integer("completed", { mode: "boolean" })
+    .notNull()
+    .default(false),
+  createdAt: text("created_at").notNull().default(now()),
+});
+
+const rows = await db.select().from(tasks).where(eq(tasks.id, taskId));
+```
+
+Never import `sqliteTable` / `pgTable` or column helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Use `@agent-native/core/db/schema` so the same schema can run against SQLite, Postgres, libSQL/Turso, D1, and other supported backends.
+
+| Template     | Tables                                        |
+| ------------ | --------------------------------------------- |
+| **Mail**     | emails, labels (+ Gmail API when connected)   |
+| **Calendar** | events, bookings                              |
+| **Forms**    | forms, responses                              |
+| **Content**  | documents                                     |
+| **Slides**   | decks (JSON stored in SQL)                    |
+| **Videos**   | compositions in registry + localStorage       |
+
+### Agent Access
+
+The agent uses app-specific actions to read/write the database. Core DB scripts are for inspection and maintenance, not for implementing normal product behavior:
+
+- `pnpm action db-schema` — Show all tables, columns, types
+- `pnpm action db-query --sql "SELECT * FROM forms"` — Run SELECT queries
+- `pnpm action db-exec --sql "UPDATE ..."` — Last-resort ad-hoc maintenance for short columns, multi-column writes, or computed updates when no domain action exists. For several related writes, prefer `--statements '[{"sql":"...","args":[...]}]'` so they run sequentially in one transaction. Schema changes are blocked; use reviewed additive migrations/startup code instead.
+- `pnpm action db-patch --table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` — **Surgical search/replace on a large text column.** Sends the diff instead of re-transmitting the whole value, so it's dramatically more token-efficient than `db-exec UPDATE` when editing multi-kilobyte documents, slide HTML, dashboard/form JSON, etc. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` to replace every occurrence.
+- App-specific actions for domain operations — **always prefer these over raw SQL when one exists.** They encode business rules, power the client action hooks, and for editor-backed tables (documents, slides) also push live Yjs updates to open collaborative editors. `db-patch` is the generic fallback for tables without a dedicated edit action.
+
+**For one-off maintenance, how to choose between `db-exec UPDATE` and `db-patch`:**
+
+| Scenario                                                       | Use          |
+| -------------------------------------------------------------- | ------------ |
+| `SET status = 'published'` on one row                          | `db-exec`    |
+| `SET calories = calories + 50`                                 | `db-exec`    |
+| Updating several columns at once                               | `db-exec`    |
+| Inserting/updating several rows as one logical operation        | `db-exec --statements` |
+| Fixing a typo in a 50KB markdown document's `content` column   | `db-patch`   |
+| Changing a single key in a dashboard's JSON blob               | `db-patch`   |
+| Tweaking one paragraph of slide HTML stored in `decks.data`    | `db-patch`   |
+| Any edit where you'd otherwise re-send thousands of characters | `db-patch`   |
+
+All of these honor the per-user / per-org data scoping — you can't read or write rows outside the current user's data, regardless of which tool you choose.
+
+### Frontend Access
+
+The frontend calls actions using React Query hooks from the client API. The framework owns the HTTP transport behind these hooks, so components should not call action routes with raw `fetch`.
+
+```ts
+import { useActionQuery, useActionMutation } from "@agent-native/core/client/hooks";
+
+// Read data
+const { data } = useActionQuery("list-meals", { date: "2025-01-01" });
+
+// Write data
+const { mutate } = useActionMutation("log-meal");
+```
+
+Actions are the **preferred way** for the frontend to access data. You rarely need custom `/api/` routes — only for file uploads, streaming, webhooks, or OAuth callbacks.
+
+### Production / Cloud Deployment
+
+Local SQLite works out of the box for development. To deploy to production or any environment where data must survive restarts:
+
+1. Set `DATABASE_URL` to a persistent SQL database.
+2. Set `DATABASE_AUTH_TOKEN` only when the provider requires a separate token, such as Turso/libSQL.
+3. No code changes should be needed when the schema and queries stay portable.
+
+Turso is one valid option, not the required option. Common choices include Neon or Supabase Postgres, Turso/libSQL, plain Postgres, durable SQLite, Cloudflare D1 bindings, and managed platform SQL environments when available.
+
+### Real-time Sync
+
+Polling streams database changes to the UI. When the agent writes to the database via scripts, the UI updates automatically via `useDbSync()` which invalidates React Query caches.
+
+## Do
+
+- Use Drizzle ORM for structured domain data (forms, bookings, documents)
+- Use Drizzle query builder methods (`select`, `insert`, `update`, `delete`) and portable operators from `drizzle-orm` (`eq`, `and`, `or`, `inArray`, `desc`, etc.) for app reads/writes
+- Use framework schema helpers from `@agent-native/core/db/schema`, not dialect-specific Drizzle imports
+- Use the `settings` store for app configuration and user preferences
+- Use `application-state` for ephemeral UI state that the agent and UI share
+- Use `oauth-tokens` for OAuth credentials
+- Use `uploadFile()` or `putPrivateBlob()` for large files/blob data and store only URLs, ids, or handles in SQL
+- Use core DB scripts (`db-schema`, `db-query`, `db-exec`, `db-patch`) for ad-hoc database operations
+- Use `db-exec --statements` instead of several separate `db-exec` calls for related writes; it is faster and rolls back the whole batch if one statement fails
+- Reach for `db-patch` instead of `db-exec UPDATE` whenever you're making a small change to a large text/JSON column — it's much cheaper on tokens
+
+## Don't
+
+- Don't store structured app data as JSON files
+- Don't store app state in localStorage, sessionStorage, or cookies (except for UI-only preferences like sidebar width)
+- Don't keep state only in memory (server variables, global stores)
+- Don't use Redis or any external state store for app data
+- Don't store large files, base64 blobs, `data:` URLs, screenshots, videos, audio, PDFs, ZIPs, or session replay chunks directly in SQL rows, `application_state`, `settings`, or `resources`
+- Don't implement product features with raw SQL or `getDbExec()` when Drizzle can express the query
+- Don't write SQLite-only or Postgres-only SQL in app code
+- Don't interpolate user input directly into SQL queries — use Drizzle ORM's query builder
+
+## Security
+
+- **SQL injection** — Use Drizzle ORM's query builder, never raw string interpolation for SQL queries
+- **Validate before writing** — Check data shape before writing, especially for user-submitted data
+
+## Application State and Context Awareness
+
+When storing app-state, include **navigation state** — the agent needs to know what the user is looking at. The `application_state` table holds ephemeral UI state that both the agent and UI share. Key patterns:
+
+- **`navigation` key** — the UI writes current view and selection on every route change. The agent reads this before acting.
+- **`navigate` key** — the agent writes one-shot commands to navigate the UI. The UI processes and deletes them.
+- **Domain-specific keys** (e.g., `compose-{id}`) — bidirectional state for features like email drafts.
+
+When adding a new data model or feature, also consider what navigation and selection state needs to be exposed via application-state. See the **context-awareness** skill for the full pattern.
+
+## Related Skills
+
+- **context-awareness** — How to expose navigation and selection state via application-state
+- **real-time-sync** — Set up polling so the UI updates when the database changes
+- **actions** — Create actions with `defineAction` to query the database
+- **client-methods** — Keep route details behind named client helpers/hooks
+- **self-modifying-code** — The agent can also modify the app's source code

package/dist/templates/workspace-core/.agents/skills/adding-a-feature/SKILL.md

@@ -101,8 +101,9 @@ placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
 real keys, internal data, or customer data into instructions as examples.
 
 If the feature adds or changes visible UI copy, prompts, toasts, labels, empty
-states, or formatting, read `internationalization` and update the app's i18n
-catalogs in the same change.
+states, or formatting, update the English source copy. Read the optional
+`internationalization` skill and update additional catalogs only when
+`translations.locales` in `agent-native.config.ts` includes them.
 
 For app-backed skills, declare skill visibility in the app-skill manifest:
 

package/dist/templates/workspace-core/.agents/skills/frontend-design/SKILL.md

@@ -36,7 +36,7 @@ Before coding, decide:
   can wait until context or intent makes it relevant?
 - **Differentiation**: What makes this feel designed for this exact domain?
 
-Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, copy, motion, empty states, loading states, focus states, and error states.
+Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, motion, empty states, loading states, focus states, and error states. Polish means removing copy, not writing more of it.
 
 ## Visual Direction Contract
 
@@ -54,80 +54,72 @@ before selecting its accent family. Shared behavior and semantic token names
 should stay consistent; palette, density, composition, type contrast, and
 shape language should not be identical by default.
 
-## High-Signal Minimalism And Progressive Disclosure
-
-Minimalism means fewer competing kinds of UI, not less useful information. Keep
-surfaces dense and scannable: reduce redundant prose, decorative containers,
-borders, badges, accent colors, and persistent controls before removing content
-that helps the user orient, compare, decide, or recover. The reference class is
-calm productivity software such as ChatGPT/Codex, Linear, and Vercel, not empty
-whitespace.
-
-### Product UX Philosophy
-
-Apply these principles as binding decision rules:
-
-- **Purpose over presence**: Every visible element must support orientation,
-  state comprehension, a decision, an action, or recovery. Before adding one,
-  name which; if it supports none or duplicates another element, remove or
-  defer it.
-- **Clarity over cleverness**: Use plain language, familiar patterns, explicit
-  hierarchy, and visible state. Do not make decoration or invented terminology
-  carry meaning. Preserve the labels, hit targets, focus states, and recovery
-  paths required for accessible use.
-- **Simple first, powerful on demand**: Keep the current task and state in the
-  default presentation. Put advanced, rare, diagnostic, and secondary work
-  behind contextual disclosure, menus, or Settings. Do not turn a discoverability
-  concern into permanent chrome, and do not hide information needed for the
-  current decision.
-- **Hierarchy over chrome**: Use typography, spacing, alignment, and restrained
-  emphasis to organize information. Treat prose, controls, borders, cards,
-  badges, and accent colors as a competition budget: reduce competing kinds of
-  elements before reducing useful information. When a surface has one clear
-  next decision, give it dominant emphasis and move secondary actions out of
-  the default path. Do not wrap every section in a card or add borders for
-  grouping alone; use spacing, alignment, typography, or dividers first. A
-  container must communicate grouping, state, or interaction.
-- **Coherence over novelty**: Reuse the product's primitives, interaction
-  patterns, and language. When given a screenshot or reference product, match
-  its underlying hierarchy, density, and behavior; do not copy decoration or
-  introduce a second visual language without a product reason.
-- **Quiet continuity**: Feedback must be immediate, contextual, and honest.
-  Preserve the user's place and layout, make loading, empty, and error states
-  understandable, and use motion only to explain a change.
-- **Respect repeated use**: Optimize for the hundredth use, not the first
-  impression. If a control repeats an explanation, occupies persistent space
-  for an occasional task, or turns routine work into ceremony, remove it or
-  move it to the contextual surface that owns it.
-
-### Progressive Disclosure And Information Timing
-
-Expose information and controls according to relevance, frequency, and
-consequence. Before coding, inventory the content and actions and assign them to
-the smallest useful visibility layer:
-
-1. **Orient and act**: location, current state, and context needed for the next
-   meaningful choice.
-2. **Support active work**: details and controls for the selected item or
-   current workflow.
-3. **Available on demand**: advanced settings, diagnostics, credentials,
-   metadata, destructive actions, documentation, and rare tools.
-
-Use a disclosure pattern that matches the task. Keep independent concerns easy
-to scan inside an expanded area instead of dumping every form, explanation,
-and secondary action into the first reveal. A collapsed row must retain its
-label and essential state; remove explanatory subtext unless it changes the
-next decision. For configuration with a known current state, show that state
-first and expose editing contextually instead of defaulting to a full form.
+## Default Surface Density
+
+This is the most repeated correction in this repo, tracked as `text-heavy-ui` in
+`node scripts/agent-friction-report.mjs`. Every item below has been asked for by
+name more than once, usually right after a previous surface was corrected for the
+same thing. So treat the list as the default shape you apply, not a tradeoff you
+weigh per surface. If the user wants one of these, they will ask.
+
+Density comes from data, not from prose. Linear, Vercel, and ChatGPT/Codex are
+dense — with rows, values, and state, and almost no explanatory sentences. That
+is the target: a surface full of information and nearly empty of narration. So
+"make it minimal" is never satisfied by removing data or by burying it behind
+extra clicks, and never blocked by deleting a sentence.
+
+Do not add, unless asked:
+
+- A page title that repeats the nav item or route the user just clicked, or a
+  breadcrumb on a page that already has a back arrow.
+- A description, subtitle, tagline, or eyebrow under any title — page, card,
+  panel, tab, dialog, settings group, or list row. A surface gets a title or a
+  description, never both.
+- A count, stat, or summary strip over content already on screen: "11 apps",
+  "25 results", "0 signals · 0 decisions · 0 runs".
+- An About, help, or "what this does" section in settings.
+- Helper text under each option in a chooser. The option label carries it.
+- A placeholder that restates its own label.
+
+The explanation goes in a tooltip, a `Manage` popover, a menu, or nowhere.
+Settings use one shape: a compact row with the label and its current state, one
+action on the right, and `Manage` revealing the form once something is
+configured. Do not spell every input out on the default surface.
+
+**Chrome is not content.** These rules govern strings you write into JSX. A
+`description` the user typed and the app stored is data — render it, and render
+nothing when it is empty. Never add a `|| "No description yet."` fallback; an
+empty field is empty, not an opening to explain the feature.
+
+### The Shape That Got Approved
+
+A multi-step connect flow the user accepted on 2026-08-12, after rejecting a
+dense dialog of the same content as "HORRIBLE ... overwhelming":
+
+- Full-screen takeover rather than a crowded modal. Generous empty space is fine.
+- One question per step as the heading ("Who should use this?"), at most one
+  short line under it, and nothing under the options.
+- Choices are single-line rows — icon plus label — with the common one
+  preselected, so the happy path is one click.
+- "Step 2 of 2" and a thin progress bar instead of every field at once.
+- Advanced and rare detail behind a labeled collapsed row ("Advanced details",
+  "App grants"): label only, no preview of the contents.
+- Current state shown rather than explained: "Dispatch can reuse this account".
+- Quiet Cancel on the left, primary action on the right.
+
+Use that same treatment for sibling flows. When the user points at another
+surface — "like forms", "like the integrations grid" — copy that surface's
+structure instead of inventing a second language for the same job.
+`templates/forms/` is the reference implementation: no page title, no
+breadcrumbs, no eyebrows, no card descriptions, and row subtext only where it
+renders a user-authored field.
 
 Before shipping, verify collapsed, expanded, loading, empty, error, and
 narrow-width states. The default state fails review when its first viewport
-contains multiple unrelated forms, repeated explanatory copy, documentation
-links, or controls for unrelated tasks. It also fails when useful information
-has been replaced with empty whitespace or extra clicks solely to look minimal.
-The default state passes when users can identify their location, current state,
-current task, and relevant next choice without reading documentation, while
-the useful information remains dense and scannable.
+carries explanatory paragraphs, several unrelated forms, or controls for another
+task. `guard:no-default-chrome` checks the structural half of this on lines your
+branch adds; it cannot see a sentence you wrote, so the list above is still
+yours to apply.
 
 ## Aesthetic Guidelines
 
@@ -212,8 +204,9 @@ the useful information remains dense and scannable.
 Before shipping a new app or a substantial redesign, review the surface as an
 operator would use it repeatedly:
 
-- Can users identify where they are, what state they are in, and what
-  meaningful choices or next steps are available?
+- Count the sentences in the first viewport. If any of them explains the UI
+  rather than reporting state, delete it. "Could a user identify where they are?"
+  is a question every surface passes; a sentence count is not.
 - Remove competing or redundant elements, then place optional inputs, provider
   choices, diagnostics, long explanations, and secondary actions where they
   remain discoverable without crowding the current task.
@@ -229,8 +222,8 @@ operator would use it repeatedly:
   consistent, but a repeated palette, hero composition, type pairing, and
   radius language without a product reason is visual drift, not consistency.
 - Check the result with realistic content at the target desktop width and a
-  narrow width. If it feels like documentation instead of a tool, reduce noise
-  or clarify the hierarchy.
+  narrow width. If it feels like documentation instead of a tool, subtract until
+  it does not — restyling it is not the fix.
 
 ## shadcn/ui Design Rules
 
@@ -241,7 +234,7 @@ operator would use it repeatedly:
 - Use `cn()` from the local utils alias for conditional classes.
 - Dialog, Sheet, Drawer, and AlertDialog content must have an accessible title. Use `sr-only` only when the visible design already communicates the title.
 - Put menu/list items inside their group primitives: `SelectGroup`, `DropdownMenuGroup`, `CommandGroup`, and equivalents.
-- Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
+- Compose cards from `CardHeader`, `CardTitle`, `CardContent`, and `CardFooter`. Do not add `CardDescription`, and do not hand-roll a muted `<p>` under a `CardTitle` — a card gets a title or a description, never both.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
 - Page and section data loading uses layout-matching `Skeleton` geometry. Do
@@ -263,9 +256,9 @@ task without a clear product reason:
   preserve discoverability and reduce noise.
 - Full-width banners, persistent helper rows, decorative cards, or explanatory
   chrome for status that could be communicated more clearly with less weight.
-- Hiding essential meaning or operability behind progressive disclosure. Defer
-  complexity when it is contextual or infrequent, but preserve labels, focus,
-  hit targets, accessibility, and recovery paths.
+- Dropping a label, focus state, hit target, accessible name, or recovery path in
+  the name of minimalism. Defer complexity freely; never defer the ability to
+  operate the control.
 - UI cards nested inside other cards.
 - Text or icons that resize or shift fixed-format UI on hover/loading.
 

package/dist/templates/workspace-core/.agents/skills/self-modifying-code/SKILL.md

@@ -90,9 +90,9 @@ el.dataset.selectedId = selectedItem?.id || "";
 **Use configuration-driven rendering** — Extract visual decisions (colors, layouts, sizes) into JSON config files in `data/`. The agent can modify the config (Tier 1) instead of the component source (Tier 2).
 
 **Keep localized copy in catalogs** — When editing visible UI copy, labels,
-toasts, empty states, prompts, or formatting, read `internationalization` and
-update `app/i18n/en-US.ts` plus existing locale catalogs instead of leaving new
-inline strings in components.
+toasts, empty states, prompts, or formatting, update the English source catalog.
+Read the optional `internationalization` skill and update additional catalogs
+only when `translations.locales` in `agent-native.config.ts` includes them.
 
 ## Don't
 

package/dist/templates/workspace-core/.agents/skills/shadcn-ui/SKILL.md

@@ -60,7 +60,7 @@ behavior comes from the company design system.
 ## Component Composition
 
 - Use existing primitives before custom markup: `Alert` for callouts, `Badge` for small status labels, `Separator` for dividers, `Skeleton` for placeholders, `Table` for tabular data, and `Card` for framed content.
-- Use full card anatomy when appropriate: `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, and `CardFooter`.
+- Compose cards from `CardHeader`, `CardTitle`, `CardContent`, and `CardFooter`. Leave `CardDescription` out: a card gets a title or a description, never both. See `frontend-design` → Default Surface Density.
 - Dialog, Sheet, Drawer, and AlertDialog content must include an accessible title. Use visually hidden titles only when the visible UI already communicates the title.
 - Put items inside their group components: `SelectItem` in `SelectGroup`, `DropdownMenuItem` in `DropdownMenuGroup`, `CommandItem` in `CommandGroup`, and equivalent menu groups.
 - `TabsTrigger` belongs inside `TabsList`.

package/dist/templates/workspace-core/.agents/skills/sharing/SKILL.md

@@ -31,6 +31,7 @@ Visibility is coarse. Explicit share grants are fine-grained (per user or per or
 ### Roles on a share grant
 
 - **`viewer`** — read only.
+- **`commenter`** — read + add comments, but cannot edit the resource or manage shares.
 - **`editor`** — read + write.
 - **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.