@agent-native/core 0.6.1 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",
@@ -20,15 +20,22 @@
     "./vite": "./dist/vite/index.js",
     "./server": "./dist/server/index.js",
     "./server/ssr-handler": "./dist/server/ssr-handler.js",
+    "./server/agent-discovery": "./dist/server/agent-discovery.js",
+    "./server/request-context": "./dist/server/request-context.js",
     "./db": "./dist/db/index.js",
     "./db/schema": "./dist/db/schema.js",
     "./client": "./dist/client/index.js",
+    "./client/onboarding": "./dist/client/onboarding/index.js",
+    "./onboarding": "./dist/onboarding/index.js",
     "./shared": "./dist/shared/index.js",
     "./scripts": "./dist/scripts/index.js",
     "./application-state": "./dist/application-state/index.js",
     "./settings": "./dist/settings/index.js",
     "./credentials": "./dist/credentials/index.js",
+    "./file-upload": "./dist/file-upload/index.js",
     "./resources": "./dist/resources/index.js",
+    "./resources/store": "./dist/resources/store.js",
+    "./resources/metadata": "./dist/resources/metadata.js",
     "./oauth-tokens": "./dist/oauth-tokens/index.js",
     "./org": "./dist/org/index.js",
     "./client/org": "./dist/client/org/index.js",
@@ -37,6 +44,7 @@
     "./collab": "./dist/collab/index.js",
     "./a2a": "./dist/a2a/index.js",
     "./mcp": "./dist/mcp/index.js",
+    "./mcp-client": "./dist/mcp-client/index.js",
     "./terminal": "./dist/client/terminal/index.js",
     "./terminal/server": "./dist/terminal/index.js",
     "./tailwind": "./dist/tailwind.preset.js",
@@ -44,11 +52,12 @@
   },
   "files": [
     "dist",
+    "docs",
     "tsconfig.base.json",
     "src/templates"
   ],
   "scripts": {
-    "build": "tsc && cp -r src/templates dist/templates",
+    "build": "tsc && rm -rf dist/templates && cp -r src/templates dist/templates",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest --run",
@@ -57,6 +66,7 @@
     "release": "npm version patch && npm publish --access public"
   },
   "dependencies": {
+    "@agent-native/shared-app-config": "workspace:*",
     "@anthropic-ai/sdk": "^0.80.0",
     "@clack/prompts": "^1.2.0",
     "@libsql/client": "^0.15.0",

package/src/templates/default/.agents/skills/actions/SKILL.md

@@ -84,7 +84,8 @@ This is the canonical approach for new apps. Action names must be lowercase with
 ## Guidelines
 
 - **One action, one job.** Keep actions focused on a single operation. The agent composes multiple action calls for complex operations.
-- **Use `parseArgs()`** for structured argument parsing. It converts `--key value` pairs to a `Record<string, string>`.
+- **Always use `defineAction` with a Zod `schema:`** for input validation. The framework validates automatically and returns clear error messages for invalid input. This prevents malicious or malformed input from reaching your code. The legacy `parseArgs()` format has no runtime validation — use it only for internal/dev scripts, not user-facing actions.
+- **Never construct SQL with string concatenation** — use the `db-exec`/`db-query` tools which parameterize queries automatically (`?` placeholders). Drizzle ORM queries are always safe.
 - **Use `loadEnv()`** if the action needs environment variables (API keys, etc.).
 - **Use `fail()`** for user-friendly error messages (exits with message, no stack trace).
 - **Write results to the database.** The agent and UI will pick them up via db sync polling.

package/src/templates/default/.agents/skills/security/SKILL.md

@@ -1,14 +1,144 @@
 ---
 name: security
 description: >-
-  Data security model, user/org scoping, and auth patterns. Use when adding
-  tables with user data, implementing multi-user features, setting up A2A
-  cross-app calls, or reviewing data access patterns.
+  Secure coding guide for agent-native apps. Covers input validation, SQL
+  injection prevention, XSS, secrets management, auth patterns, data scoping,
+  and A2A security. Read this when generating any code that handles user data.
 ---
 
-# Security & Data Scoping
+# Security
 
-## How Data Isolation Works
+The framework provides strong security primitives. Use them — don't reinvent security.
+
+## Input Validation
+
+**Always use `defineAction` with a Zod `schema:`** for every action that accepts user input. The framework validates automatically and returns clear error messages.
+
+```ts
+// SECURE — framework validates before run() is called
+export default defineAction({
+  description: "Create a note",
+  schema: z.object({
+    title: z.string().min(1).max(200),
+    content: z.string().optional(),
+  }),
+  run: async (args) => {
+    // args is guaranteed valid — { title: string; content?: string }
+  },
+});
+```
+
+The legacy `parameters:` format (plain JSON Schema) has **no runtime validation** — the agent receives whatever the caller sends. Do not use it for new code.
+
+Actions without a `schema:` are unvalidated. This is acceptable for internal/dev scripts but never for user-facing operations.
+
+## SQL Injection Prevention
+
+The framework's `db-query` and `db-exec` tools use **parameterized queries** (`?` placeholders). The database driver handles escaping — user input never touches the SQL string.
+
+```ts
+// WRONG — SQL injection vulnerability
+await exec(`INSERT INTO notes (title) VALUES ('${title}')`)
+await exec(`SELECT * FROM notes WHERE title LIKE '%${search}%'`)
+
+// RIGHT — parameterized queries (framework default)
+await exec({ sql: "INSERT INTO notes (title) VALUES (?)", args: [title] })
+await exec({ sql: "SELECT * FROM notes WHERE title LIKE ?", args: [`%${search}%`] })
+```
+
+**Drizzle ORM is always safe** — it generates parameterized queries automatically:
+
+```ts
+const notes = await db.select().from(notesTable).where(eq(notesTable.title, title));
+```
+
+**When is SQL injection a risk?**
+- Only when writing raw SQL with string concatenation in server routes or actions
+- Never when using `db-query`/`db-exec` with `args` arrays
+- Never when using Drizzle ORM
+
+## XSS Prevention
+
+React auto-escapes all JSX expressions by default. Trust it.
+
+```tsx
+// SAFE — React escapes the output
+<p>{userInput}</p>
+<span>{comment.text}</span>
+
+// DANGEROUS — bypasses React's escaping
+<div dangerouslySetInnerHTML={{ __html: userInput }} />  // NEVER with user content
+element.innerHTML = userInput;                             // NEVER
+eval(userInput);                                           // NEVER
+document.write(userInput);                                 // NEVER
+new Function(userInput);                                   // NEVER
+```
+
+**For rich text:** Use TipTap (framework dependency) with the Collaboration extension. TipTap sanitizes content through its schema — only allowed node types render.
+
+**For markdown:** Use `react-markdown` (already used in the framework). It parses markdown to React elements without `dangerouslySetInnerHTML`.
+
+**For HTML from external sources:** If you absolutely must render external HTML, use a sanitization library like `dompurify`. But prefer structured data (markdown, TipTap JSON) over raw HTML.
+
+## Secrets Management
+
+| Secret type | Where to store | Why |
+|-------------|---------------|-----|
+| API keys (OpenAI, Stripe, etc.) | `.env` file (gitignored) | Never committed, server-side only |
+| OAuth tokens (Google, GitHub) | `oauth_tokens` store | Per-user, per-provider, server-side |
+| App configuration | `settings` store | OK for non-secret config (themes, preferences) |
+| Session tokens | Framework handles | Automatic via Better Auth |
+
+**Rules:**
+- Never store secrets in `settings`, `application_state`, or source code
+- Never return secrets in action responses — they may appear in agent chat or client UI
+- Never log secrets (tokens, keys, passwords)
+- Never commit `.env` files — they're gitignored by default
+- Access env vars via `process.env` in actions/server code, never send them to the client
+
+## Auth Patterns
+
+### Use `defineAction` (recommended)
+
+Actions defined with `defineAction` are automatically protected by the auth guard. Unauthenticated requests get a 401 response. This is the safest pattern.
+
+```ts
+// Auto-protected — auth guard runs before this code
+export default defineAction({
+  description: "Delete a note",
+  schema: z.object({ id: z.string() }),
+  run: async (args) => {
+    // Only authenticated users reach here
+  },
+});
+```
+
+### Custom `/api/` routes (use sparingly)
+
+If you must create custom routes (file uploads, streaming, webhooks), always check auth:
+
+```ts
+// server/routes/api/upload.ts
+import { getSession } from "@agent-native/core/server";
+
+export default defineEventHandler(async (event) => {
+  const session = await getSession(event);
+  if (!session?.email) {
+    setResponseStatus(event, 401);
+    return { error: "Unauthorized" };
+  }
+  // ... handle upload with session.email
+});
+```
+
+### CSRF Protection
+
+The framework uses `SameSite=lax` cookies with `httpOnly` flag. This prevents most CSRF attacks. Additional rules:
+- State-changing actions should use POST (the default for `defineAction`)
+- GET actions (`http: { method: "GET" }`) should be read-only
+- Never perform writes in response to GET requests
+
+## Data Scoping
 
 In production, the framework enforces data isolation at the SQL level. Agents and users can only see and modify data they own. This is automatic — you don't write WHERE clauses yourself.
 
@@ -41,45 +171,17 @@ For multi-user apps where teams share data, add an `org_id` column:
 export const projects = table("projects", {
   id: text("id").primaryKey(),
   name: text("name").notNull(),
-  owner_email: text("owner_email").notNull(), // who created it
-  org_id: text("org_id").notNull(),           // which org it belongs to
+  owner_email: text("owner_email").notNull(),
+  org_id: text("org_id").notNull(),
 });
 ```
 
 When both columns are present, queries are scoped by **both**: `WHERE owner_email = ? AND org_id = ?`.
 
-The `org_id` comes from `AGENT_ORG_ID` which is automatically set from the user's active organization in Better Auth.
-
 ### Validation
 
 Run `pnpm action db-check-scoping` to verify all tables have proper ownership columns. Use `--require-org` for multi-org apps.
 
-## Auth Model
-
-### Better Auth (Default)
-
-The framework uses Better Auth for authentication. It's always on by default — users create an account on first visit.
-
-**Environment variables:**
-- `BETTER_AUTH_SECRET` — signing key (auto-generated if not set)
-- `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` — enable Google OAuth
-- `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET` — enable GitHub OAuth
-- `AUTH_MODE=local` — disable auth for solo local dev (escape hatch)
-
-### Organizations
-
-Better Auth's organization plugin is built-in. Every app supports:
-- Creating organizations
-- Inviting members (owner/admin/member roles)
-- Switching active organization
-- Per-org data scoping via `org_id`
-
-The active organization ID flows from `session.orgId` → `AGENT_ORG_ID` → SQL scoping automatically.
-
-### ACCESS_TOKEN (Legacy)
-
-For simple deployments, set `ACCESS_TOKEN` or `ACCESS_TOKENS` (comma-separated) as environment variables. This provides a shared token for all users — no per-user identity.
-
 ## A2A Security
 
 ### Cross-App Identity
@@ -87,7 +189,6 @@ For simple deployments, set `ACCESS_TOKEN` or `ACCESS_TOKENS` (comma-separated)
 When apps call each other via A2A, they need to verify identity. Set the same `A2A_SECRET` on all apps that need to trust each other:
 
 ```bash
-# On both apps
 A2A_SECRET=your-shared-secret-at-least-32-chars
 ```
 
@@ -102,7 +203,11 @@ Without `A2A_SECRET`, A2A calls are unauthenticated (fine for local dev, not pro
 ## Rules for Agents
 
 1. **Every new table with user data must have `owner_email`.** No exceptions.
-2. **Never bypass scoping** — don't raw-query tables without going through `db-query`/`db-exec`.
-3. **Don't expose user data in application state** — application state is per-session, not per-user. Use SQL tables with `owner_email` for persistent user data.
-4. **Don't hardcode emails** — use `AGENT_USER_EMAIL` environment variable.
-5. **Test with multiple users** — create two accounts and verify data isolation.
+2. **Always use `defineAction` with a Zod `schema:`** for input validation on user-facing actions.
+3. **Never concatenate user input into SQL** — use parameterized queries or Drizzle ORM.
+4. **Never use `dangerouslySetInnerHTML`** or `innerHTML` with user-controlled content.
+5. **Never store secrets outside `.env` or `oauth_tokens`** — no settings, no source code, no responses.
+6. **Never bypass scoping** — don't raw-query tables without going through `db-query`/`db-exec`.
+7. **Never create unprotected routes that modify data** — use `defineAction` or check `getSession()`.
+8. **Don't hardcode emails** — use `AGENT_USER_EMAIL` environment variable.
+9. **Don't expose user data in application state** — it's per-session, not per-user. Use SQL tables with `owner_email`.

package/src/templates/default/.agents/skills/storing-data/SKILL.md

@@ -78,7 +78,7 @@ Query via `getDb()` singleton from `server/db/index.ts`.
 
 ### 4. OAuth Tokens — credentials
 
-For OAuth tokens acquired at runtime (Google, etc.). Never store these in settings — use the dedicated encrypted store.
+For OAuth tokens acquired at runtime (Google, etc.). Never store these in settings — use the dedicated store.
 
 ```ts
 import { saveOAuthTokens, getOAuthTokens, listOAuthAccounts } from "@agent-native/core/oauth-tokens";
@@ -108,3 +108,9 @@ Infrastructure config stays in `.env` — these differ per deployment:
 - `ACCESS_TOKEN` — production auth token
 
 Everything else (user settings, tokens, app state) goes in SQL.
+
+## Security Rules
+
+- **Never store API keys or secrets in Settings or Application State** — use `.env` for API keys (gitignored) and the `oauth_tokens` store for OAuth credentials. Settings and application state are readable by the client.
+- **Every Drizzle table with user data must have `owner_email`** — the framework auto-scopes queries in production so users only see their own data. Run `pnpm action db-check-scoping` to verify. See the `security` skill for the full model.
+- **Never return secrets in action responses** — action responses may be visible in the agent chat or sent to the client. Keep credentials server-side only.

package/src/templates/default/_gitignore

@@ -1,5 +1,6 @@
 # React Router generated types
 .react-router/
+.agent-native/
 
 # Logs
 logs

package/src/templates/default/app/root.tsx

@@ -23,7 +23,10 @@ export function Layout({ children }: { children: React.ReactNode }) {
     <html lang="en" suppressHydrationWarning>
       <head>
         <meta charSet="utf-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta
+          name="viewport"
+          content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
+        />
         <link rel="manifest" href="/manifest.json" />
         <meta name="theme-color" content="#111111" />
         <meta name="mobile-web-app-capable" content="yes" />

package/src/templates/workspace-core/AGENTS.md

@@ -0,0 +1,62 @@
+# {{APP_TITLE}} — Enterprise Agent Instructions
+
+These instructions apply to **every app** in the {{APP_TITLE}} workspace. The
+framework auto-injects this file into each app's agent system prompt as a
+`<resource name="AGENTS.md" scope="workspace">` block. Individual apps can
+add their own template-specific AGENTS.md on top.
+
+## Company context
+
+Write a short paragraph here describing your company and what you do. The
+agent reads this first so every response can be grounded in the same
+business context without you having to repeat it per app.
+
+## Shared conventions
+
+- **All cross-app state lives in the shared database.** Apps in this
+  workspace share `DATABASE_URL` by default, so a record created by one
+  app can be read by another as long as it respects the `owner_email` and
+  `org_id` scoping conventions.
+- **All API secrets come from the central credential store.** Never
+  hardcode a token. Call `resolveCompanyCredential("KEY")` from
+  `@{{APP_NAME}}/core-module/credentials` — it pulls from env first and
+  falls back to the shared settings table so one rotation updates every
+  app.
+- **UI chrome comes from the workspace core.** Wrap every screen in
+  `<AuthenticatedLayout>` from `@{{APP_NAME}}/core-module/client`. Don't
+  re-implement the brand header, sidebar, or org switcher per app.
+- **Design system.** If the app needs a button, dialog, or form control,
+  import from our internal design system package (if you have one) or
+  from the shared UI re-exports in `@{{APP_NAME}}/core-module/client`.
+
+## Compliance and policy
+
+List any enterprise-wide rules the agent must follow — data handling, PII
+guidelines, approval flows, deployment constraints. The agent will apply
+these to every decision it makes in every app.
+
+Example rules:
+
+- Never expose raw customer email addresses in logs.
+- Any action that modifies data must first be shown to the user with a
+  preview and wait for confirmation.
+- Never make network calls to anything outside `*.{{APP_NAME}}.com` or
+  the approved third-party allowlist.
+
+## How to add a new app
+
+```bash
+cd apps
+pnpm exec agent-native create <app-name>
+```
+
+The new app will automatically inherit:
+
+1. The workspace auth plugin (Better Auth + company SSO)
+2. The agent chat plugin with this AGENTS.md pre-loaded
+3. Every skill in `packages/core-module/skills/`
+4. Every action in `packages/core-module/actions/`
+5. The shared Tailwind preset and React components
+
+The only files the new app needs to own are its own routes/screens and any
+template-specific actions.

package/src/templates/workspace-core/actions/company-directory.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared action: look up an employee in the company directory.
+ *
+ * Every app in the workspace inherits this action automatically — no
+ * wiring required. From the agent's perspective it behaves exactly like
+ * a template action: the tool shows up in every app's agent, and calling
+ * it from the UI via `useActionQuery("company-directory", { ... })` Just
+ * Works.
+ *
+ * Replace the stub implementation with a real call to your company
+ * directory (SCIM, Okta Users API, internal /people endpoint, etc.).
+ */
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description:
+    "Look up a person in the {{APP_TITLE}} company directory by name or email. Returns role, team, and manager.",
+  schema: z.object({
+    query: z.string().describe("Name, email, or partial match to search for"),
+  }),
+  run: async (args) => {
+    // TODO: replace with a real lookup. This stub just echoes the query
+    // so the agent has a reasonable no-op while you wire up the real
+    // directory integration.
+    return {
+      results: [
+        {
+          query: args.query,
+          name: "(stub) " + args.query,
+          role: "Unknown",
+          team: "Unknown",
+          manager: null,
+        },
+      ],
+    };
+  },
+});

package/src/templates/workspace-core/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@{{APP_NAME}}/core-module",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./server": {
+      "types": "./src/server/index.ts",
+      "default": "./src/server/index.ts"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "default": "./src/client/index.ts"
+    },
+    "./credentials": {
+      "types": "./src/credentials.ts",
+      "default": "./src/credentials.ts"
+    },
+    "./tailwind": {
+      "types": "./tailwind.preset.ts",
+      "default": "./tailwind.preset.ts"
+    }
+  },
+  "dependencies": {
+    "@agent-native/core": "^0.6.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.23",
+    "react": "^18.3.1",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1"
+  }
+}

package/src/templates/workspace-core/skills/company-policies/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: company-policies
+description: {{APP_TITLE}}-wide policies the agent must enforce for every app — data handling, PII, approval flows, compliance rules.
+---
+
+# {{APP_TITLE}} Company Policies
+
+Every app in the workspace shares these policies. Read this skill before
+taking any action that touches customer data, external services, or
+deployed state.
+
+## Data handling
+
+- **PII minimization.** Only load the fields you actually need. Never
+  `SELECT *` on a table that contains customer records.
+- **No raw customer email in logs.** Hash or redact before logging.
+- **Retention.** Deleted records are soft-deleted first and purged by a
+  scheduled job. Do not write actions that hard-delete customer data.
+
+## Third-party calls
+
+- **Allowlist only.** Only call domains on the approved allowlist
+  (documented in the root `README.md`). If an integration needs a new
+  domain, surface a warning and wait for human approval before making
+  the call.
+- **Secrets come from `resolveCompanyCredential`.** Never hardcode.
+  Never check secrets into git. Rotating a key in the central store
+  updates every app on the next request.
+
+## Approval flows
+
+- **Destructive operations need a confirmation preview.** Any action
+  that modifies production data must first return a preview of the
+  change (what will be created / updated / deleted) and wait for
+  explicit user confirmation before executing.
+
+## Apply across apps
+
+This skill is loaded automatically in every workspace app. If an
+individual app needs different behavior, it can add a same-named skill
+under its own `.agents/skills/company-policies/SKILL.md` and that copy
+will win for that app only.

package/src/templates/workspace-core/src/client/AuthenticatedLayout.tsx

@@ -0,0 +1,37 @@
+/**
+ * Shared authenticated layout for every app in the @{{APP_NAME}} workspace.
+ *
+ * Provides the common chrome (brand header, user menu, agent chat sidebar)
+ * so individual apps only have to render their own content. Replace this
+ * with a real component that pulls in your design system. Every app
+ * imports it the same way:
+ *
+ *   import { AuthenticatedLayout } from "@{{APP_NAME}}/core-module/client";
+ *
+ *   export default function Home() {
+ *     return (
+ *       <AuthenticatedLayout>
+ *         <h1>My app's screen</h1>
+ *       </AuthenticatedLayout>
+ *     );
+ *   }
+ */
+import type { ReactNode } from "react";
+
+export interface AuthenticatedLayoutProps {
+  children: ReactNode;
+}
+
+// Workspace title — replaced at scaffold time by the create-workspace CLI.
+const WORKSPACE_TITLE = "{{APP_TITLE}}";
+
+export function AuthenticatedLayout({ children }: AuthenticatedLayoutProps) {
+  return (
+    <div className="min-h-screen flex flex-col">
+      <header className="border-b px-6 py-3">
+        <strong>{WORKSPACE_TITLE}</strong>
+      </header>
+      <main className="flex-1 p-6">{children}</main>
+    </div>
+  );
+}

package/src/templates/workspace-core/src/client/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Client-side entry for @{{APP_NAME}}/core-module.
+ *
+ * This is where shared React components, hooks, and providers that EVERY
+ * app in your workspace needs live. Think of it as the "app shell" layer
+ * between the framework's primitives (@agent-native/core/client) and the
+ * individual app's screens:
+ *
+ *   - Authenticated layouts (header / sidebar / footer with brand)
+ *   - Org switchers wired to your company's org plugin
+ *   - Common chrome: loading states, error boundaries, empty states
+ *   - Wrappers around @agent-native/core components that apply your
+ *     enterprise design tokens
+ *
+ * Apps import from here instead of re-implementing or copy-pasting:
+ *
+ *   import { AuthenticatedLayout } from "@{{APP_NAME}}/core-module/client";
+ *
+ * NOTE: This package does not ship shadcn/ui or a generic design system
+ * by default. If you already have an internal `@{{APP_NAME}}/design-system`
+ * package, add it as a dep here and re-export from this file. Otherwise
+ * you can drop any shadcn components the apps share into `./ui/` and
+ * export them from this index.
+ */
+
+export { AuthenticatedLayout } from "./AuthenticatedLayout.js";

package/src/templates/workspace-core/src/credentials.ts

@@ -0,0 +1,29 @@
+/**
+ * Centralized credential helpers for the @{{APP_NAME}} workspace.
+ *
+ * Every enterprise has a few API keys that multiple apps need to share:
+ * a Slack bot token, a Sentry DSN, an OpenAI key, internal service
+ * credentials. Instead of each app reading them separately, we namespace
+ * them here so there's a single place to update when a key rotates.
+ *
+ * Under the hood this is a thin wrapper over @agent-native/core's
+ * `resolveCredential()`, which reads `process.env.<KEY>` first and
+ * falls back to `credential:<KEY>` in the shared settings table.
+ * Apps inside the workspace share the same DATABASE_URL by default,
+ * so storing a credential once makes it available everywhere.
+ */
+import { resolveCredential } from "@agent-native/core/credentials";
+
+/**
+ * Resolve a company-wide credential. Prefer this over `resolveCredential()`
+ * directly — it keeps your keys organized under a workspace namespace and
+ * makes "where does this secret come from" greppable.
+ *
+ * Example:
+ *   const slackToken = await resolveCompanyCredential("SLACK_BOT_TOKEN");
+ */
+export async function resolveCompanyCredential(
+  key: string,
+): Promise<string | undefined> {
+  return await resolveCredential(key);
+}

package/src/templates/workspace-core/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @{{APP_NAME}}/core-module — enterprise-wide workspace core.
+ *
+ * Every agent-native app in this workspace inherits from this package:
+ *   - Server plugins (auth, org, agent-chat) — see src/server
+ *   - Shared React components and hooks — see src/client
+ *   - Shared agent actions — see actions/
+ *   - Shared agent skills — see skills/
+ *   - Enterprise-wide agent instructions — see AGENTS.md
+ *   - Shared Tailwind preset — see tailwind.preset.ts
+ *
+ * Apps don't import from this root entry directly — they import from
+ * the specific sub-path they need:
+ *
+ *   import { authPlugin } from "@{{APP_NAME}}/core-module/server";
+ *   import { AuthenticatedLayout } from "@{{APP_NAME}}/core-module/client";
+ *   import { resolveCompanyCredential } from "@{{APP_NAME}}/core-module/credentials";
+ *
+ * This root file is for package metadata only.
+ */
+export const WORKSPACE_CORE_NAME = "@{{APP_NAME}}/core-module";