@agent-native/core 0.7.54 → 0.7.55

package/docs/content/sharing.md

@@ -0,0 +1,155 @@
+---
+title: "Sharing & Privacy"
+description: "Google-Docs-style sharing, built into the framework. Every user-created resource — docs, dashboards, designs, decks, clips, recordings, forms — gets the same private-by-default model with one consistent share UI."
+---
+
+# Sharing & Privacy
+
+Every resource a user creates in an agent-native app — a document, a dashboard, a design, a deck, a video edit, a screen recording, a meeting transcript, a form, a booking link — is **private to the creator by default**. Other people see it only when the creator explicitly shares it, or changes its visibility to `org` or `public`.
+
+It looks and works like Google Docs. The same share button, the same dialog, the same three-tier visibility model, the same per-user/per-org grants — across every template, with no per-app reinvention.
+
+## Why one model {#why}
+
+Most app frameworks make sharing a per-feature project. The result: every doc-like surface ends up with its own share dialog, its own permissions schema, its own access-check bugs. In agent-native, sharing is a **framework primitive**. The schema columns, the access-check helpers, the share popover, and the agent-callable share actions all ship with the core. A new template gets the full sharing story by adding two columns and one line of registration.
+
+This also means the agent never has to learn a new sharing model per app. Tell the agent "share this with Alice as an editor" in any template and the same `share-resource` action fires.
+
+## The three visibility levels {#visibility}
+
+Coarse visibility lives on the resource itself; fine-grained grants live in a companion shares table.
+
+| Visibility | Who can see it                                                                                      |
+| ---------- | --------------------------------------------------------------------------------------------------- |
+| `private`  | Owner + people explicitly granted. **Default for every new resource.**                              |
+| `org`      | Owner + explicit grants + anyone in the same organization (read-only).                              |
+| `public`   | Owner + explicit grants + anyone with the link (read-only). Doesn't appear in others' lists/search. |
+
+`public` is a deliberately quiet level: a public resource is reachable by direct link, but it does **not** show up in other users' sidebars, lists, or search. That keeps "public for sharing the URL" separate from "public for cross-user discovery." Galleries and template catalogs that genuinely want cross-user discovery opt in explicitly.
+
+## Roles on a share grant {#roles}
+
+When you share with a specific user or org, you pick a role:
+
+- **Viewer** — read only.
+- **Editor** — read + write.
+- **Admin** — read + write + manage shares (can add/remove other people).
+
+`admin` does NOT change ownership — there's still exactly one owner per resource, distinct from the share grants.
+
+## What's covered {#covered}
+
+Every template that stores user-authored work uses this model. Concretely:
+
+- **Content** — documents
+- **Slides** — decks
+- **Design** — designs and assets
+- **Video** — compositions
+- **Clips** — screen recordings (Loom-style)
+- **Calls** — meeting recordings and transcripts (Granola-style)
+- **Meeting Notes** — transcripts and summaries
+- **Forms** — form definitions
+- **Calendar** — events and booking links
+- **Analytics** — dashboards (rolling out — see the analytics template's `AGENTS.md`)
+- **Tools** — sandboxed mini-apps (see [Tools](/docs/tools#sharing))
+
+Every one of these uses the same `ownableColumns()` schema helper, the same `share-resource` action, and the same `<ShareButton>` UI. Move from one template to another and the share dialog looks identical.
+
+## What's not covered {#not-covered}
+
+A few areas are intentionally outside the sharing system:
+
+- **Personal-data apps** (Mail, Macros) — user-scoped by design. There's no "share my inbox" concept.
+- **External source-of-truth apps** (Issues → Jira, Recruiting → Greenhouse) — access control lives in the upstream system, not the agent-native app.
+- **Anonymous public URLs** — form publish slugs and booking-link slugs that expose a URL to logged-out users are a separate axis. They live alongside the sharing system, not on top of it.
+
+## The share UI {#share-ui}
+
+Every shareable resource gets a share button in its header. Clicking it opens a popover anchored to the button (not a modal) with:
+
+- Visibility selector (`Private` / `Organization` / `Public link`).
+- "Add people or teams" autocomplete — search users in the org or paste an email.
+- A list of current grants with role pickers and a remove control.
+- A copy-link button that respects the current visibility.
+
+The share button is a single import:
+
+```tsx
+import { ShareButton } from "@agent-native/core/client";
+
+<ShareButton
+  resourceType="deck"
+  resourceId={deck.id}
+  resourceTitle={deck.title}
+/>;
+```
+
+For lists, drop a `<VisibilityBadge visibility={row.visibility} />` next to each row so users can see at a glance what's private vs. shared.
+
+## Same model, agent and UI {#agent-and-ui}
+
+The framework auto-mounts these actions in every template — the agent calls them as tools, the UI calls them as HTTP endpoints:
+
+| Action                    | What it does                                      |
+| ------------------------- | ------------------------------------------------- |
+| `share-resource`          | Grant a user or org access at a specific role.    |
+| `unshare-resource`        | Revoke access for a user or org.                  |
+| `list-resource-shares`    | Show current visibility plus all explicit grants. |
+| `set-resource-visibility` | Change to `private`, `org`, or `public`.          |
+
+Tell the agent "share this design with the marketing team as editors" and it calls `share-resource` against the same endpoint the UI uses. The result shows up in the share dialog the next render.
+
+## Building it into a new template {#building}
+
+If you're creating a template (see [Creating Templates](/docs/creating-templates)), wiring sharing in is short. Two additions to your schema:
+
+```ts
+import {
+  table,
+  text,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const decks = table("decks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  data: text("data").notNull(),
+  ...ownableColumns(), // adds owner_email, org_id, visibility
+});
+
+export const deckShares = createSharesTable("deck_shares");
+```
+
+One registration call in `server/db/index.ts`:
+
+```ts
+import { registerShareableResource } from "@agent-native/core/sharing";
+
+registerShareableResource({
+  type: "deck",
+  resourceTable: schema.decks,
+  sharesTable: schema.deckShares,
+  displayName: "Deck",
+  titleColumn: "title",
+  getDb,
+});
+```
+
+After that, list/read queries pass through `accessFilter()` and write actions use `assertAccess()` to enforce roles. The full pattern (including create-action ownership stamping and the migration recipe for existing tables) lives in the `sharing` agent skill — the agent reads it on demand when building a sharing-aware feature.
+
+## Security guarantees {#security}
+
+Sharing rides on the framework's broader data-scoping model. The two non-negotiable rules:
+
+- **No unscoped queries.** Every query against an ownable table must go through `accessFilter()` (lists), `resolveAccess()` (read-by-id), or `assertAccess()` (writes). A CI guard fails the build if a query against an ownable table runs without one of these helpers.
+- **Org isolation.** Resources tagged with an `org_id` are invisible to users from other orgs even to the agent. The active-org session value flows through to SQL, so cross-org leaks are impossible by construction.
+
+See [Security & Data Scoping](/docs/security) for the full model and threat surface.
+
+## See also {#see-also}
+
+- [Security & Data Scoping](/docs/security) — the access-filter and ownership model that sharing rides on.
+- [Authentication](/docs/authentication) — sessions, organizations, and how identity flows into the request context.
+- [Tools](/docs/tools#sharing) — sharing in the sandboxed mini-app surface.
+- [Creating Templates](/docs/creating-templates) — wiring `ownableColumns` into a new template's schema.

package/docs/content/template-clips.md

@@ -1,19 +1,21 @@
 ---
 title: "Clips"
-description: "Record your screen, get an AI-generated title, summary, and chapter markers automatically, and search across every recording you've ever made."
+description: "Async screen recording (Loom-style), calendar-synced meeting notes (Granola-style), and push-to-talk voice dictation (Wisprflow-style) — all transcribed, summarized, and searchable in one app you own."
 ---
 
 # Clips
 
-A screen-recording app where the agent does the post-production work for you. Record your screen, and Clips transcribes it, suggests a title and summary, builds chapter markers, and tags the content automatically. Ask "find the clip where we discussed the rollout plan" and the agent searches across every transcript you've ever made.
+A capture-everything app: screen recordings (Loom-style), meeting notes from your calendar (Granola-style), and Fn-hold voice dictation (Wisprflow-style). The agent transcribes, titles, summarizes, and indexes all of it — then lets you ask "find the clip where we discussed the rollout plan" and searches across every transcript you've ever made.
 
-Think along the lines of products that record short async videos for your team — but the agent is a first-class editor, and the recordings are yours, not a SaaS vendor's.
+Think along the lines of Loom + Granola + Wisprflow rolled into one app — but the agent is a first-class editor across every surface, and the recordings, meetings, and dictations are yours, not a SaaS vendor's.
 
 ## What you can do with it
 
 - **Record your screen** with a built-in recorder, webcam overlay, audio capture, and pause/trim.
+- **Capture meetings from your calendar.** Connect Google Calendar, see upcoming meetings in the sidebar, and hit record on any one. You get a live transcript plus AI summary, bullet notes, and action items the moment it ends.
+- **Push-to-talk dictation.** Hold Fn on your machine, speak, and the cleaned-up text drops into whatever app you're using. Every dictation is kept in a searchable history with originals and AI-cleaned versions side by side.
 - **Get an auto-generated title, summary, and chapter markers** for every recording — the agent fills them in and keeps them current.
-- **Search across every transcript** with full-text search. "Find the clip where we discussed the rollout plan."
+- **Search across every transcript** — screen recordings, meetings, and dictations all in one library. "Find the clip where we discussed the rollout plan."
 - **Share clips** with per-clip permissions (public, team, private). Link tracking and threaded comments work too.
 - **Smart library views.** Group by project, filter by speaker, auto-tag based on content.
 - **Edit the transcript through chat.** "Fix the mis-transcribed word at 1:42." "Pull three quotes for a blog post." The agent edits the transcript and the UI updates live.
@@ -43,7 +45,8 @@ Clips is a larger template with a native recorder (it ships a desktop companion
 Clips is a full cloneable SaaS — fork it and ask the agent to extend it. Some examples:
 
 - "Add a filler-word removal button that strips ums and uhs from the transcript and re-stitches the video."
-- "Auto-post a new clip to Slack #eng-demos whenever I finish a recording." (Connect Slack first via [Messaging](/docs/messaging).)
+- "Auto-post my standup notes to Slack #eng whenever a meeting ends." (Connect Slack first via [Messaging](/docs/messaging).)
+- "Add a hotkey that drops the last dictation into Linear as a new ticket."
 - "Group the library by project — detect the project from the first words of each transcript."
 - "Add a 'Generate blog post from this clip' button that drafts a post from the transcript and saves it as a draft."
 - "Let viewers leave timestamped reactions on a shared clip."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.7.54",
+  "version": "0.7.55",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",