@agent-native/core-corpus 0.214.0 → 0.216.0

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

@@ -0,0 +1,71 @@
+---
+name: shadcn-ui
+description: >-
+  Using the app's local UI adapter and Toolkit or shadcn primitives. Use when
+  choosing or composing standard controls, implementing dialogs, menus, or
+  forms, or changing component variants and theme tokens.
+scope: dev
+---
+
+# shadcn/ui and Local UI Adapters
+
+Use the components already provided by the app. Read the app's design-system
+configuration, Toolkit provider, and local UI components before adding or
+changing a control. Their exports, variants, and props are the contract; do
+not guess from upstream examples.
+
+## Keep imports behind the local adapter
+
+Product pages and domain components should import standard controls through the
+app's configured local UI alias. In the Chat starter, that is
+`@/components/ui/*`; its `app/components/ui/button.tsx` is a one-line
+re-export of `@agent-native/toolkit/ui/button`. Follow an adjacent local shim
+when the app needs another Toolkit primitive that is already exported there.
+
+Use the app's configured design system and provider mapping for controls passed
+to shared Toolkit surfaces. For shared Toolkit feature presentation, use the
+semantic components exposed by `@agent-native/toolkit/design-system`; keep the
+feature behavior in its existing controller and customize only its supported
+presentation seam.
+
+## Compose existing controls
+
+- Prefer a primitive's built-in variant and size. Put page layout on a parent
+  instead of overriding shared component appearance for one screen.
+- Use the app's semantic theme tokens for reusable UI, such as
+  `bg-background`, `text-muted-foreground`, `border-border`, and `bg-primary`.
+  Keep theme values in the app's existing CSS theme file.
+- Use the control that matches the choice: `Switch` for a binary setting,
+  `Checkbox` for independent multi-select, `RadioGroup` for one choice from a
+  short set, and `Select` or the app's combobox for a longer predefined list.
+- Compose cards and form fields from the primitives already available. Avoid
+  adding explanatory copy that repeats a visible title or label; see
+  `frontend-design` for the app's surface-density rules.
+- Put selectable items inside their menu or list group primitives. Keep tab
+  triggers inside the tab list. Supply an accessible title to dialog, sheet,
+  drawer, and alert-dialog content.
+- Match the trigger API to the actual local component. Toolkit wrappers may
+  expose a different API from the upstream primitive; inspect its props before
+  using options such as `asChild` or `render`.
+
+## Keep controls operable
+
+Use the app's existing field components and validation pattern. Associate
+errors with their inputs and expose invalid state to assistive technology.
+Icon-only actions need an accessible name and a usable focus target. Use the
+icon package already installed by the app.
+
+Do not recreate menus, popovers, dialogs, or confirmations with absolute
+positioning and custom click-outside handlers. Never use browser `alert`,
+`confirm`, or `prompt`; use the app's dialog primitives. Keep overlay focus,
+keyboard, dismissal, and stacking behavior from the existing primitive.
+
+For small visual refinements, use layout classes and semantic tokens. Avoid raw
+palette overrides, arbitrary one-off values, and manual overlay `z-index` unless
+you are fixing a reproduced bug. Use `gap-*` for layout spacing and the app's
+class-merging helper when it has one.
+
+## Related skill
+
+- **frontend-design** — Product UX, density, visual direction, and responsive
+  behavior.

package/corpus/templates/slides-2/.agents/skills/sharing/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: sharing
+description: >-
+  Framework-level sharing and privacy for user-authored resources
+  (dashboards, documents, forms, decks, etc.). Use when making a resource
+  table ownable, wiring list/read/update access checks, or dropping the
+  standard share dialog into a template.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Sharing — Private by Default, Explicit Share
+
+## Rule
+
+Any resource a user **creates** (dashboards, documents, forms, decks, compositions, booking links, issues, analyses) is **private to the creator** by default and visible to others only when they have been **explicitly shared** with or when the creator changes visibility to `org` or `public`.
+
+This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
+
+Workspace apps are the intentional organization-scoped exception: their default
+visibility is `org`, configurable by an organization owner/admin. The creator is
+stored as the app owner, and the creator or an organization owner/admin can
+change the app's visibility or manage its share grants.
+
+## Concepts
+
+### Three visibility levels
+
+- **`private`** — owner + explicit share grants only. Default.
+- **`org`** — owner + explicit grants + anyone in the same org (read-only).
+- **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
+
+Visibility is coarse. Explicit share grants are fine-grained (per user, reusable
+organization group, or per org).
+
+### 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.
+
+Share roles apply to one resource; organization roles apply to a team; app
+roles apply within one app. These are separate permissions. For role setup,
+use `agent-native-docs` to find the current organization and app-role guide.
+
+Before adding an admin gate, identify which role system protects that operation
+and use its existing role descriptor and permission checks. Do not replace role
+checks with an email comparison or a custom `isAdmin` column.
+
+### Anonymous public URLs stay separate
+
+Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
+
+## Make a resource ownable
+
+In your template's `server/db/schema.ts`:
+
+```ts
+import { sql } from "drizzle-orm";
+import { pgTable, text } from "drizzle-orm/pg-core";
+import {
+  createSharesTable,
+  ownableColumns,
+} from "@agent-native/core/db/schema";
+
+export const decks = pgTable("decks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  data: text("data").notNull(),
+  createdAt: text("created_at").notNull().default(sql`now()`),
+  updatedAt: text("updated_at").notNull().default(sql`now()`),
+  ...ownableColumns(), // adds owner_email, org_id, visibility
+});
+
+export const deckShares = createSharesTable("deck_shares");
+```
+
+Then register it **in `server/db/index.ts`** (not the schema file — keeps the schema file free of the `getDb` closure and avoids circular imports):
+
+```ts
+// server/db/index.ts
+import * as schema from "./schema.js";
+import { createGetDb } from "@agent-native/core/db";
+import { registerShareableResource } from "@agent-native/core/sharing";
+
+export const getDb = createGetDb(schema);
+export { schema };
+
+registerShareableResource({
+  type: "deck",
+  resourceTable: schema.decks,
+  sharesTable: schema.deckShares,
+  displayName: "Deck",
+  titleColumn: "title",
+  getResourcePath: (deck) => `/deck/${deck.id}`,
+  getDb,
+});
+```
+
+The `type` string is the stable id the UI and actions use. `getDb` is required — the framework-level share actions use it to reach your template's DB.
+
+### Restricting public visibility and cross-org user shares
+
+Some resources should NOT be reachable by an arbitrary authenticated user even with the link, and should NOT be shareable to an email outside the org. Two optional registration flags lock these axes down:
+
+```ts
+registerShareableResource({
+  type: "extension",
+  // ...
+  allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
+  requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+  supportsGroupShares: true, // enable reusable organization groups for this resource
+});
+```
+
+- **`allowPublic: false`** — `set-resource-visibility('public')` throws `ForbiddenError`, `accessFilter` / `resolveAccess` treat any stored `'public'` row as private (defense in depth against bad data), and the share popover hides the "Public" option. `list-resource-shares` returns `policy.allowPublic: false` so the UI follows the server.
+- **`requireOrgMemberForUserShares: true`** — `share-resource` looks up `principalId` in `org_members` and `org_invitations` (pending) for the resource's `orgId` and rejects user shares to anyone else. The same flag also pins `principalType: "org"` shares to the resource's own org — sharing to a *different* org would let that org's members run code in the viewer's auth context (same threat model as a public extension). (The flag name is kept for backward compatibility; treat it as "lock both user and org shares to the resource's org".)
+
+Use both for resources that execute code or expose privileged data with the *viewer's* credentials. A public or cross-org-shared resource with that access could let an unrelated user act with the viewer's credentials.
+
+Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
+
+### Reusable organization groups
+
+The workspace organization model stores reusable groups in
+`workspace_user_groups`. Organization owners/admins manage the groups and their
+members through the existing group actions. Set `supportsGroupShares: true` on a
+resource registration to enable `principalType: "group"` in the generic share
+actions and the shared popover's autocomplete. Group ids are always checked
+against the resource's organization, and membership is evaluated at access time
+so group changes apply to existing shares.
+
+Workspace apps opt into this flag and use the organization default visibility
+setting. The app creator is the durable `owner_email`, while organization
+owners/admins receive admin access through the registration's
+`canManageAccess` callback.
+
+## Filter list/read queries
+
+```ts
+import { accessFilter } from "@agent-native/core/sharing";
+
+const rows = await db
+  .select()
+  .from(schema.decks)
+  .where(accessFilter(schema.decks, schema.deckShares));
+```
+
+`accessFilter` admits rows the current user owns, has been shared on, or that the user can reach via `org` visibility. `public` rows are NOT admitted by default — see the visibility section above for why and how to opt in.
+
+## Guard write actions
+
+```ts
+import { assertAccess } from "@agent-native/core/sharing";
+
+export default defineAction({
+  schema: z.object({ id: z.string(), title: z.string() }),
+  run: async (args) => {
+    await assertAccess("deck", args.id, "editor");
+    // ...proceed
+  },
+});
+```
+
+For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
+
+`authorize` is a different axis, not an alternative: it gates whether the caller may run the operation at all, while `assertAccess` scopes which row they may touch. A write action restricted to some teammates needs both — `authorize: appAccess.requireAny(...)` on the action, `assertAccess` inside `run`.
+
+## Create actions must set owner
+
+When inserting a new row, fill `ownerEmail` and `orgId` from the request context:
+
+```ts
+import { fail } from "@agent-native/core/action";
+import {
+  getRequestUserEmail,
+  getRequestOrgId,
+} from "@agent-native/core/server/request-context";
+
+const ownerEmail = getRequestUserEmail();
+// Never fall back to a shared sentinel owner; require an authenticated session.
+if (!ownerEmail) fail("Not authenticated", { statusCode: 401 });
+
+await db.insert(schema.decks).values({
+  id: crypto.randomUUID(),
+  title,
+  data,
+  ownerEmail,
+  orgId: getRequestOrgId(),
+  // visibility defaults to 'private'
+  // ...
+});
+```
+
+## Drop in the share UI
+
+```tsx
+import { ShareButton } from "@agent-native/toolkit/app/sharing";
+
+// In the resource's header/toolbar:
+<ShareButton
+  resourceType="deck"
+  resourceId={deck.id}
+  resourceTitle={deck.title}
+/>;
+```
+
+For list views, show `<VisibilityBadge visibility={row.visibility} />` next to each resource.
+
+## Standard share surface
+
+All app share popovers should use the same compact surface contract:
+
+- Use the text-only `ShareTrigger` from `@agent-native/toolkit/sharing`.
+- Render ordinary links with `ShareCopyRow`, which exposes a Copy action without
+  printing the raw URL.
+- Keep general access and individual people access in the standard Core sharing
+  flow. The people flow supports email invites, roles, notifications, and
+  removal through the shared share actions.
+- Add `ShareAgentsSection` only when the resource has a real agent-readable
+  link or prompt. Keep it collapsed by default and supply domain-specific
+  content through the shared section shell.
+- When `supportsGroupShares` is enabled, keep the existing people input as the
+  only entry point and include organization groups in its autocomplete. Do not
+  add a separate group-management surface to each resource.
+- App-specific tabs or controls may remain when they represent a real domain
+  action (for example, an embed-code editor), but they should retain the same
+  trigger, copy-row, access, and spacing language.
+
+`ShareDisclosureSection` is the toolkit-owned shell for optional expandable
+share details; use its `ShareAgentsSection` or `SharePeopleSection` wrappers
+instead of creating another collapsible share panel in a template.
+
+## Actions available everywhere
+
+The framework auto-mounts these actions in every template — no per-template boilerplate:
+
+| Action                     | Args                                                                           | Purpose                                   |
+| -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user, group, or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
+| `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
+| `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
+| `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |
+
+Both the agent and the UI use these same actions. The agent calls them as tools;
+UI code should use `ShareButton` / `ShareDialog` or the action client hooks
+instead of hand-writing route calls.
+
+To re-skin the share notification email for the whole app, register
+`overrideTransactionalEmail("core.resource-shared", render)` from a server
+plugin. Do not fork `share-resource` or add another per-resource hook: the
+registration's `getBrandName` / `getLogoUrl` / `getSender` / `getHeroHtml` /
+`getShareEmailExtras` hooks still feed the default template and the override's
+props. See
+`/docs/deployment#email-templates`.
+
+## Migration pattern for existing tables
+
+When retrofitting an existing resource table:
+
+1. Add `owner_email`, `org_id`, `visibility` columns (defaults `'local@localhost'`, `NULL`, `'private'`).
+2. Backfill `owner_email` from any prior creator trail; otherwise leave the default.
+3. Add the companion `{type}_shares` table.
+4. Register via `registerShareableResource`.
+5. Update list/read actions to use `accessFilter`.
+6. Update update/delete actions to `assertAccess` with the correct role.
+7. Add `<ShareButton>` to the resource header.
+8. Add `getResourcePath` in the registration so agent-triggered shares can email a direct link even when no UI supplied `resourceUrl`.
+
+## Templates that opt out
+
+Sharing doesn't apply to:
+
+- **Personal-data apps** (mail) — user-scoped by design.
+- **External source-of-truth data** — apply the access policy enforced by the upstream system.
+- **Demo/boilerplate** (starter) — no resources.
+
+For these, add a short note to the template's `AGENTS.md` explaining why.
+
+## Debugging
+
+- `ForbiddenError` from an action means the current user isn't owner / hasn't been shared / can't meet the role bar.
+- If the agent can't see a resource it just created, check that the insert actually set `owner_email` from the request context.
+- If a share doesn't take effect in the UI, confirm the template's `list-*` action uses `accessFilter` — the share rows are there but nothing is reading them yet.

package/corpus/templates/slides-2/.agents/skills/slide-design/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: slide-design
+description: >-
+  Visual craft for beautiful slides: typography, composition, color,
+  imagery, rhythm, and a critique pass. Use when generating slides or
+  when asked to make a deck or slide beautiful, polished, prettier, more
+  designed, or less generic. Defers to the linked design system and reference
+  deck.
+---
+
+# Slide Design
+
+"Make it beautiful" is a request for visual craft, not new content. Keep the
+user's copy, facts, images, and slide order; change how they look. A beautiful
+deck reads as the work of a studio with a point of view, not a template.
+
+## Precedence
+
+This skill supplies craft, not a direction. The direction comes from the
+user's prompt and the brief `create-deck` builds from it; never swap in a
+preset style. The `design-systems` Precedence list decides what wins:
+
+- **Design system linked:** it owns tokens (colors, fonts and weights, type
+  sizes, spacing, radius, accents, logos, image style, custom CSS) through the
+  `--ds-*` wrapper. Add nothing it does not define and never detach it. Beauty
+  comes from using fewer of its elements more deliberately: scale contrast
+  within its sizes, composition, negative space, alignment, a scarce accent.
+- **Reference deck:** owns layouts, chrome, and markup idiom, and tokens too
+  when no system is linked. Tighten inside its patterns; when none fits,
+  compose from its conventions. It is a pattern library, not an outline.
+- **Attached style reference:** match its measured type scale, weights,
+  colors, alignment, and margins.
+- **Existing deck with an established look** (including a starter template):
+  its slides are the reference. Refine it; change the style only when asked.
+- **Nothing linked:** realize the direction the prompt implies with this
+  whole skill.
+
+Explicit constraints in the current request beat all of these. If a selected
+system or reference is unavailable, tell the user the deck was styled without
+it instead of silently using this skill's defaults.
+
+## Typography
+
+Type does most of the work.
+
+- **Use registered fonts.** The Slides 2 editor can search the Google Fonts
+  catalog and import a chosen variant to configured file storage. Apply the
+  returned font family and asset handle through the design-token panel or
+  `update-deck-design-tokens`. The sandbox loads only the selected registered
+  font files. Source CSS still cannot use remote font URLs, `@import`, or
+  `@font-face`; unsupported families fall back silently.
+- **Extreme scale contrast.** Let one element dominate. On 960x540: statement
+  or big number 72-120px, headline 32-56px, body 16-20px, labels 12-14px. A
+  96px number over 13px labels is striking; 40px over 28px is flat. Body never
+  drops below 16px.
+- **Tight display type:** letter-spacing -0.02 to -0.05em, line-height
+  0.95-1.1. Body line-height 1.35-1.5, about 60 characters per line max.
+- **Labels as labels:** small uppercase with +0.06 to +0.12em tracking, or
+  mono, for eyebrows, running heads, axis labels, and page numbers.
+- **Weight is hierarchy.** One heavy and one regular weight; mid-weights
+  everywhere look mushy. Size and weight before color.
+- **Details:** curly quotes, en dashes for ranges, tabular numerals for aligned
+  figures, no orphaned last word on a headline (rebalance with `max-width` or a
+  `<br>`).
+
+## Composition
+
+- **Grid:** 12 columns inside the wrapper padding, 16-24px gutters. Snap every
+  edge.
+- **Asymmetry over centering.** Headline in 5-7 columns, evidence large in the
+  rest. Center only title and statement slides.
+- **Negative space is a material.** One line of type in the lower-left third of
+  an empty slide can be the best slide in the deck.
+- **One spacing scale** (the system's gaps, else 8/16/24/40/64): close for
+  related, far for unrelated. Equal gaps everywhere read as amateur.
+- **Optical alignment:** nudge large type to look flush with small text.
+- **One focal point.** Squint; one thing should land first.
+- **One idea per slide; split, do not shrink.** A slide over the `create-deck`
+  Fit budget becomes two slides, not smaller type or clipped overflow.
+- Keep layout in normal flex/grid flow; `slide-editing` owns flow and fit
+  constraints.
+
+## Color
+
+With a system or reference, use only its colors; these rules govern how.
+
+- **Restrained palette:** background, ink, one or two tinted neutrals, one
+  accent.
+- **No pure defaults:** warm or tinted off-white (`#F4F1EA`) over `#FFFFFF`,
+  near-black or deep navy over `#000000`, greys leaning with the palette.
+- **Accent is scarce:** one number, bar, word, or rule per slide.
+- **Fixed canvas:** rhythm comes from composition and accent, not alternating
+  light and dark slides.
+- Readable contrast is part of beauty; `audit-contrast` is the check.
+
+## Imagery and graphics
+
+- **One treatment:** the same crop, color grade, and radius on every image;
+  respect the system's `imageStyle`.
+- **Go big or leave it out:** a full-height column or most of the canvas.
+  Small floating thumbnails read as placeholders.
+- **Screenshots as hero shots:** crop to what the headline is about, scale up,
+  set on a fitting surface.
+- **One graphic vocabulary:** 1-2px rules, large index numbers ("01"), one
+  repeated shape motif. Every shape needs a semantic role.
+- **Charts in the deck's type and palette:** thin strokes, direct labels, the
+  key series in the accent, the rest neutral, no gridline or legend clutter.
+
+## Rhythm
+
+- Reuse a small layout family: title, section, statement, big number, headline
+  + image, split, grid of 3, quote, closing. Alternate dense and sparse; avoid
+  three identical layouts in a row.
+- Fixed chrome in the same place on every slide: a small running head, a page
+  number like `04 / 12` from the `create-deck` slide-number tokens (never typed
+  digits, which go stale on reorder), maybe a hairline.
+- Title and section slides carry the strongest expression of the direction.
+
+## What reads as generic
+
+Everything centered at similar sizes in one weight; purple-to-blue gradients,
+glass, glows, gradient text; rows of rounded icon + title + description cards;
+emoji or decorative icons; shadows and borders on every block; stock
+people-at-laptops; bullet walls or shrunk text; default blue and default chart
+colors; mixed radii, alignments, and gaps; decoration filling space that should
+stay empty.
+
+## Critique pass
+
+After rendering, before `get-layout-overflows` and `audit-contrast`, check
+each changed slide:
+
+1. **Squint:** one clear focal point, balanced masses.
+2. **Direction:** delivers the requested look and matches the other slides;
+   with a system linked, every color, font, radius, and logo comes from it.
+3. **Scale:** real contrast between the largest and smallest type.
+4. **Grid:** edges align within and across slides; chrome never moves.
+5. **Subtract:** remove what does not serve the slide.
+6. **Portfolio:** would a strong designer show it? If not, make the one change
+   that would.
+7. **Craft:** no orphans, straight quotes, awkward breaks, blurry images, or
+   off-system colors and fonts.
+
+Fix findings in one correction pass.