@agentuity/skills 3.1.1

package/skills/agentuity-cloud/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: agentuity-cloud
+description: >-
+  Use when managing Agentuity Cloud from the terminal. Covers deployments,
+  deployment logs, environment variables and secrets, regions, project resource
+  linking, cloud resource commands, SSH, SCP, monitoring snapshots, and
+  agent-friendly CLI workarounds.
+license: Apache-2.0
+metadata:
+  author: agentuity
+  version: "1.0.0"
+---
+
+# Agentuity Cloud Operations
+
+Use this skill when operating Agentuity from the CLI: deployments, logs,
+environment values, resources, SSH access, and live debugging. Use
+`agentuity-services` or `agentuity-database` for app-code client usage.
+
+## Deployment Lifecycle
+
+Deploy from a linked project:
+
+```bash
+agentuity deploy
+```
+
+List recent deployments:
+
+```bash
+agentuity cloud deployment list
+agentuity cloud deployment list --count=25
+agentuity cloud deployment list --project-id=proj_abc123xyz
+```
+
+Show one deployment:
+
+```bash
+agentuity cloud deployment show deploy_abc123xyz
+agentuity cloud deployment show deploy_abc123xyz --project-id=proj_abc123xyz
+```
+
+View deployment logs:
+
+```bash
+agentuity cloud deployment logs deploy_abc123xyz
+agentuity cloud deployment logs deploy_abc123xyz --limit=50
+agentuity cloud deployment logs deploy_abc123xyz --no-timestamps
+agentuity cloud deployment logs deploy_abc123xyz --project-id=proj_abc123xyz
+```
+
+Deployment logs are currently a snapshot command, not a follow stream. If an
+agent needs to wait for new log output, poll with a bounded loop and stop when
+the deploy reaches a terminal state or enough evidence is collected.
+
+Rollback, undeploy, and delete:
+
+```bash
+agentuity cloud deployment rollback
+agentuity cloud deployment undeploy --force
+agentuity cloud deployment delete deploy_abc123xyz --force
+```
+
+Use destructive commands carefully. Prefer explicit `--force` or `--confirm`
+flags in automation when a command supports them.
+
+## Environment Variables and Secrets
+
+List and inspect project values:
+
+```bash
+agentuity cloud env list
+agentuity cloud env get NODE_ENV
+agentuity cloud env list --secrets
+```
+
+Set values:
+
+```bash
+agentuity cloud env set NODE_ENV production
+agentuity cloud env set API_KEY "sk_live_..." --secret
+```
+
+Sync `.env`:
+
+```bash
+agentuity cloud env push
+agentuity cloud env pull
+agentuity cloud env pull --force
+agentuity cloud env import .env.staging
+```
+
+There is no separate secret namespace command. Secrets are managed through `agentuity cloud env` with `--secret`.
+
+## Regions and Project Context
+
+Use explicit project and region options in non-interactive automation:
+
+```bash
+agentuity cloud region list
+agentuity cloud region current
+agentuity cloud region select usc
+agentuity project show --json
+```
+
+Project resolution usually comes from `agentuity.json` in the app directory. In
+monorepos, run commands from the app package or pass `--dir`.
+
+## Resource Management
+
+Use cloud commands to create, inspect, and manage resources. Use `--json` when an agent needs to parse output.
+
+| Resource | Commands to start with |
+|---|---|
+| Key-value | `agentuity cloud kv list-namespaces`, `get`, `set`, `keys`, `stats` |
+| Vector | `agentuity cloud vector list`, `upsert`, `search`, `get`, `delete` |
+| Object storage | `agentuity cloud storage create`, `list`, `upload`, `download` |
+| Database | `agentuity cloud db create`, `list`, `get --show-credentials`, `logs` |
+| Queues | `agentuity cloud queue create`, `publish`, `receive`, `destinations` |
+| Sandboxes | `agentuity cloud sandbox create`, `exec`, `files`, `cp`, `snapshot` |
+| Email | `agentuity cloud email create`, `send`, `list`, `stats` |
+| Schedules | `agentuity cloud schedule create`, `list`, `get`, `delete` |
+| Tasks | `agentuity cloud task list`, `get`, `create`, `update` |
+| Webhooks | `agentuity cloud webhook create`, `list`, `get`, `delete` |
+| Streams | `agentuity cloud stream create`, `list`, `get`, `delete` |
+| AI Gateway | `agentuity cloud aigateway models --recommended`, `--ids`, `--provider` |
+
+Link resources to the current project when app code needs local `.env` values:
+
+```bash
+agentuity project add database app_data
+agentuity project add storage my-bucket
+```
+
+Check `agentuity project add --help` for the supported resource types in the installed CLI.
+
+## SSH and File Transfer
+
+Add an SSH key first:
+
+```bash
+agentuity auth ssh add --file ~/.ssh/id_rsa.pub
+```
+
+Connect:
+
+```bash
+agentuity cloud ssh
+agentuity cloud ssh proj_abc123xyz
+agentuity cloud ssh deploy_abc123xyz
+agentuity cloud ssh 'ps aux'
+agentuity cloud ssh --show
+```
+
+Transfer files:
+
+```bash
+agentuity cloud scp upload ./config.json /app/config.json
+agentuity cloud scp download /var/log/app.log ./logs/
+```
+
+SSH is for debugging. Do not treat manual container changes as deployable source-of-truth changes.
+
+## Monitoring and Debugging
+
+Use snapshot output for automation:
+
+```bash
+agentuity cloud monitor --json
+agentuity cloud monitor --snapshot
+agentuity cloud monitor --deployment deploy_abc123xyz --snapshot
+```
+
+Inspect sessions when debugging request-specific behavior:
+
+```bash
+agentuity cloud session list --count=25
+agentuity cloud session list --success=false --count=25
+agentuity cloud session get sess_abc123xyz
+agentuity cloud session logs sess_abc123xyz --no-timestamps
+```
+
+## Agent-Friendly Workflow
+
+For deploy-debug loops:
+
+1. Run `agentuity deploy --json` when machine-readable output is needed.
+2. Capture the deployment ID from output.
+3. Run `agentuity cloud deployment show <id> --json`.
+4. Inspect recent logs with `agentuity cloud deployment logs <id> --limit=100`.
+5. Use `agentuity cloud monitor --deployment <id> --snapshot` for machine health.
+6. Use SSH only after logs and structured status point to runtime-only evidence.
+
+Known CLI gaps are tracked under the `agentic flow` GitHub label. Until
+wait/follow/status primitives exist, use bounded polling and explicit timeouts
+in automation.
+
+## Common Mistakes
+
+| Mistake | Better approach |
+|---|---|
+| Guessing URLs after deploy | Read deploy output or `cloud deployment show` |
+| Expecting deployment logs to follow live | Poll with a limit until follow support exists |
+| Managing secrets with a separate command | Use `cloud env set --secret` |
+| Running destructive commands without explicit confirmation flags | Use `--force` or `--confirm` when supported |
+| Editing a debug container and calling it deployed | Commit the source change and redeploy |
+
+## Useful Docs
+
+- Deployment: https://agentuity.dev/reference/cli/deployment
+- Debugging: https://agentuity.dev/reference/cli/debugging
+- Configuration: https://agentuity.dev/reference/cli/configuration
+- Monitoring: https://agentuity.dev/reference/cli/monitoring
+- Storage commands: https://agentuity.dev/reference/cli/storage

package/skills/agentuity-database/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: agentuity-database
+description: >-
+  Use when adding relational data to an Agentuity app. Covers creating or linking
+  managed Postgres, DATABASE_URL, pg, Drizzle ORM, pooling, transactions,
+  migrations, safe parameter binding, and the narrow admin-script role for
+  DBClient.
+license: Apache-2.0
+metadata:
+  author: agentuity
+  version: "1.0.0"
+---
+
+# Agentuity Database
+
+Use database resources when your app needs SQL, joins, constraints,
+transactions, or relational user data. Agentuity-managed databases are Postgres
+databases. App code should connect through `DATABASE_URL` with the Postgres
+client or ORM your app owns.
+
+## Create or Link a Database
+
+Create a database and link it to the current project:
+
+```bash
+agentuity cloud db create --name app_data
+agentuity project add database app_data
+```
+
+Linking writes `DATABASE_URL` to `.env`. Recover the URL later with credentials shown only in a trusted shell:
+
+```bash
+agentuity cloud db get app_data --show-credentials
+```
+
+Use the `agentuity-cloud` skill for database CLI management and logs.
+
+## Choose a Client
+
+| Need | Use |
+|---|---|
+| Direct SQL with parameter binding | `pg` |
+| Schema-first TypeScript queries | `drizzle-orm/node-postgres` with `pg` |
+| Existing Prisma, Kysely, or another Postgres client | Keep it and point it at `DATABASE_URL` |
+| Trusted admin script by Agentuity database resource name | `DBClient` from `@agentuity/db` |
+
+`DBClient` is not the app query layer. It calls the Agentuity database service
+API by resource name and organization ID, which is useful for trusted scripts,
+introspection, or query logs.
+
+## Use `pg`
+
+```bash
+npm install pg
+npm install -D @types/pg
+```
+
+```typescript
+import { Pool } from 'pg';
+
+const databaseUrl = process.env.DATABASE_URL;
+
+if (!databaseUrl) {
+  throw new Error('DATABASE_URL is required');
+}
+
+export const pool = new Pool({
+  connectionString: databaseUrl,
+  max: 10,
+  idleTimeoutMillis: 30_000,
+});
+
+export async function findUserByEmail(email: string): Promise<{
+  readonly id: string;
+  readonly email: string;
+} | null> {
+  const { rows } = await pool.query<{
+    readonly id: string;
+    readonly email: string;
+  }>('SELECT id, email FROM users WHERE email = $1 LIMIT 1', [email]);
+
+  return rows[0] ?? null;
+}
+```
+
+Use placeholders such as `$1` for every request value, form value, queue payload,
+or model output. Do not concatenate untrusted values into SQL strings.
+
+## Use Drizzle
+
+```bash
+npm install drizzle-orm pg
+npm install -D drizzle-kit @types/pg
+```
+
+```typescript
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { boolean, pgTable, serial, text } from 'drizzle-orm/pg-core';
+import { Pool } from 'pg';
+
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  email: text('email').notNull().unique(),
+  active: boolean('active').notNull().default(true),
+});
+
+const databaseUrl = process.env.DATABASE_URL;
+
+if (!databaseUrl) {
+  throw new Error('DATABASE_URL is required');
+}
+
+export const db = drizzle(new Pool({ connectionString: databaseUrl }), {
+  schema: { users },
+});
+```
+
+Route usage:
+
+```typescript
+import { eq } from 'drizzle-orm';
+import { db, users } from '@/src/db/client';
+
+export async function GET(): Promise<Response> {
+  const activeUsers = await db
+    .select({ id: users.id, email: users.email })
+    .from(users)
+    .where(eq(users.active, true))
+    .limit(20);
+
+  return Response.json({ users: activeUsers });
+}
+```
+
+## Migrations
+
+Use `drizzle-kit` when the app uses Drizzle:
+
+```typescript
+import { defineConfig } from 'drizzle-kit';
+
+const databaseUrl = process.env.DATABASE_URL;
+
+if (!databaseUrl) {
+  throw new Error('DATABASE_URL is required for Drizzle migrations');
+}
+
+export default defineConfig({
+  schema: './src/db/schema.ts',
+  out: './drizzle',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: databaseUrl,
+  },
+});
+```
+
+```bash
+bunx drizzle-kit generate
+bunx drizzle-kit migrate
+```
+
+Use migration files for repeatable deploy-time schema changes. Use
+`bunx drizzle-kit push` only for quick development loops.
+
+## Transactions
+
+Use one transaction boundary for one write workflow:
+
+```typescript
+const client = await pool.connect();
+
+try {
+  await client.query('BEGIN');
+  await client.query('UPDATE accounts SET balance = balance - $1 WHERE name = $2', [100, 'Alice']);
+  await client.query('UPDATE accounts SET balance = balance + $1 WHERE name = $2', [100, 'Bob']);
+  await client.query('COMMIT');
+} catch (error) {
+  await client.query('ROLLBACK');
+  throw error;
+} finally {
+  client.release();
+}
+```
+
+Use your ORM's transaction helper when the app already uses an ORM.
+
+## DBClient for Trusted Scripts
+
+```bash
+npm install @agentuity/db
+```
+
+```typescript
+import { DBClient } from '@agentuity/db';
+
+const database = process.env.AGENTUITY_DB_DATABASE;
+const orgId = process.env.AGENTUITY_CLOUD_ORG_ID;
+
+if (!database || !orgId) {
+  throw new Error('AGENTUITY_DB_DATABASE and AGENTUITY_CLOUD_ORG_ID are required');
+}
+
+const db = new DBClient({ database, orgId });
+
+const result = await db.query('SELECT 1 AS ok');
+const tables = await db.tables();
+const logs = await db.logs({ limit: 50 });
+```
+
+Use `DBClient` only for trusted SQL such as introspection or administrative
+checks. It does not replace a parameterized app query client.
+
+## Common Mistakes
+
+| Mistake | Better approach |
+|---|---|
+| Creating a new pool inside every request | Create one pool at module scope |
+| Using KV for relational queries | Use Postgres for joins, constraints, and transactions |
+| Concatenating request values into SQL | Use placeholders or ORM query builders |
+| Treating `DBClient` as the app ORM | Use `pg`, Drizzle, Prisma, Kysely, or your existing client |
+| Forgetting to link the database | Run `agentuity project add database <name>` so `DATABASE_URL` is written |
+
+## Useful Docs
+
+- Database overview: https://agentuity.dev/services/database
+- Postgres clients: https://agentuity.dev/services/database/postgres
+- Drizzle ORM: https://agentuity.dev/services/database/drizzle
+- Database API reference: https://agentuity.dev/reference/api/database

package/skills/agentuity-frameworks/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: agentuity-frameworks
+description: >-
+  Use when adding Agentuity code to a framework app and choosing where routes,
+  pages, server functions, config, or service clients belong. Covers Next.js,
+  Nuxt, SvelteKit, Astro, Hono, React Router, Vite with React, and TanStack Start
+  file placement.
+license: Apache-2.0
+metadata:
+  author: agentuity
+  version: "1.0.0"
+---
+
+# Agentuity Framework Placement
+
+Agentuity works with your framework's normal file layout. Put routes, pages,
+server functions, and config where the framework expects them. Add Agentuity
+clients only in server-side code.
+
+## Create-Supported Frameworks
+
+`agentuity create` can scaffold these frameworks:
+
+| Framework | API route location | App UI location | Dev script owner |
+|---|---|---|---|
+| Next.js | `src/app/api/<name>/route.ts` | `src/app/page.tsx` | Next.js |
+| Nuxt | `server/api/<name>.get.ts` or `.post.ts` | `app/app.vue` | Nuxt |
+| SvelteKit | `src/routes/<path>/+server.ts` | `src/routes/+page.svelte` | Vite/SvelteKit |
+| Astro | `src/pages/api/<name>.ts` | `src/pages/index.astro` | Astro |
+| Hono | `src/index.ts` route handlers | `src/landing.tsx` when scaffolded | Hono server script |
+
+Use the framework's route handler to validate the request, then call a shared function for the real work.
+
+## Existing-App Adoption
+
+For apps you already have, install the CLI and import the project without changing the app shape:
+
+```bash
+npm install -D @agentuity/cli
+agentuity project import --name existing-app --confirm
+```
+
+Useful route locations:
+
+| Framework | Server route shape |
+|---|---|
+| React Router | `app/routes/api.agentuity.ts`, registered in `app/routes.ts` |
+| TanStack Start | `src/routes/api.agentuity.tsx` with server handlers |
+| Vite + React | A server boundary such as `server.ts`; browser code calls that server |
+| Express or other routers | Existing route module; import Agentuity clients server-side |
+
+## Server-Only Rule
+
+Do not expose Agentuity SDK keys to browser bundles. Service clients belong in
+routes, server actions, workers, scripts, or other server-only modules.
+
+```typescript
+import { KeyValueClient } from '@agentuity/keyvalue';
+
+const kv = new KeyValueClient();
+
+export async function GET(): Promise<Response> {
+  const result = await kv.get<{ checkedAt: string }>('health', 'latest');
+  return Response.json({ ok: true, exists: result.exists });
+}
+```
+
+Browser components should call your server route:
+
+```typescript
+const response = await fetch('/api/agentuity-health');
+const status = await response.json();
+```
+
+## Thin Route, Shared Function
+
+Prefer this split for AI features, background work, and service calls:
+
+```typescript
+// lib/triage.ts
+export async function triageMessage(message: string): Promise<{ priority: string }> {
+  return { priority: message.includes('urgent') ? 'high' : 'normal' };
+}
+```
+
+```typescript
+// framework route file
+import { triageMessage } from '@/lib/triage';
+
+export async function POST(request: Request): Promise<Response> {
+  const body = (await request.json()) as { message?: string };
+  if (!body.message) {
+    return Response.json({ error: 'message is required' }, { status: 400 });
+  }
+
+  const result = await triageMessage(body.message);
+  return Response.json(result);
+}
+```
+
+This keeps route-specific code small and lets the core function move between
+frameworks, tests, queues, schedules, and scripts.
+
+## Hono Middleware Option
+
+In Hono apps, use direct clients by default when portability matters. Use
+`@agentuity/hono` when accessing clients through Hono context improves
+readability:
+
+```typescript
+import { Hono } from 'hono';
+import { agentuity } from '@agentuity/hono';
+import type { Services } from '@agentuity/hono';
+
+const app = new Hono<{ Variables: Pick<Services, 'kv'> }>();
+
+app.use('*', agentuity());
+
+app.get('/api/preferences/:userId', async (c) => {
+  const result = await c.var.kv.get('preferences', c.req.param('userId'));
+  return c.json({ exists: result.exists });
+});
+```
+
+AI Gateway, database, object storage, webhooks, and Coder are direct clients.
+
+## Common Mistakes
+
+| Mistake | Better approach |
+|---|---|
+| Putting service clients in browser components | Call a server route that owns the client |
+| Adding new folders that bypass framework conventions | Use the framework's route/page locations |
+| Duplicating AI or service logic in every route | Put shared work in a plain function and import it |
+| Assuming every framework uses the same API route path | Check the route table before editing |
+| Putting SDK keys in public env prefixes | Keep `AGENTUITY_SDK_KEY` server-side |
+
+## Useful Docs
+
+- Frameworks: https://agentuity.dev/frameworks
+- Project structure: https://agentuity.dev/get-started/project-structure
+- Add to existing app: https://agentuity.dev/get-started/import-existing-app
+- Standalone packages: https://agentuity.dev/reference/standalone-packages

package/skills/agentuity-project/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: agentuity-project
+description: >-
+  Use when creating, importing, running, building, or deploying an Agentuity app.
+  Covers framework-first project structure, agentuity.json, .env setup,
+  agentuity dev, agentuity build, agentuity deploy, monorepo --dir usage, and
+  deployment bundle inspection.
+license: Apache-2.0
+metadata:
+  author: agentuity
+  version: "1.0.0"
+---
+
+# Agentuity Project Lifecycle
+
+Agentuity deploys framework apps as they are. Keep the framework's routing,
+pages, server functions, and config in their normal locations. Agentuity adds
+project metadata, local environment wiring, build packaging, deployment, and
+managed services.
+
+## Choose Create or Import
+
+Use `agentuity create` for a new app:
+
+```bash
+agentuity create --name my-app --framework nextjs
+```
+
+Use `agentuity project import` for an existing framework app:
+
+```bash
+agentuity project import --name my-app --confirm
+```
+
+For monorepos, run commands from the app package or pass `--dir`:
+
+```bash
+agentuity project import --dir apps/web --name web --confirm
+agentuity deploy --dir apps/web
+```
+
+## What Agentuity Adds
+
+After create/import, expect these files next to the app's `package.json`:
+
+| File | Purpose |
+|---|---|
+| `agentuity.json` | Project, org, region, and deployment metadata |
+| `.env` | Local SDK key and linked resource values |
+| `.agentuity/launch.json` | Build output contract produced by `agentuity build` |
+
+The framework still owns `dev`, `build`, and route files. Agentuity adds deploy tooling and cloud resource wiring.
+
+## Development Loop
+
+Use the framework's normal dev command for everyday framework work. Run through
+Agentuity when you want the CLI to inject linked project credentials, expose the
+Agentuity tunnel, or validate the deployed-like environment:
+
+```bash
+agentuity dev
+```
+
+Read the terminal output for the actual local URL and tunnel URL. Do not invent
+localhost ports or public deployment URLs.
+
+## Build and Deploy
+
+Build locally when you need to inspect packaging:
+
+```bash
+agentuity build
+```
+
+Check `.agentuity/launch.json` after a build. It describes the process Agentuity will start after deployment.
+
+Deploy from a linked project:
+
+```bash
+agentuity deploy
+```
+
+The deploy flow syncs non-Agentuity `.env` values, builds the app, packages the
+bundle, uploads assets, provisions the deployment, and prints the deployment ID
+plus URLs.
+
+## Existing App Checklist
+
+Before deploying an existing app:
+
+1. Run `agentuity project import --validate-only`.
+2. Fix any reported framework, package, or build issues.
+3. Run `agentuity project import --name <name> --confirm`.
+4. Run `agentuity build`.
+5. Inspect `.agentuity/launch.json`.
+6. Run `agentuity deploy`.
+
+## Working With Services
+
+When adding Agentuity services to app code, import standalone clients in the server-side module that owns the work:
+
+```typescript
+import { KeyValueClient } from '@agentuity/keyvalue';
+
+const kv = new KeyValueClient();
+
+export async function saveDraft(userId: string, draft: string): Promise<void> {
+  await kv.set('drafts', userId, { draft }, { ttl: 60 * 60 * 24 });
+}
+```
+
+For service selection and client examples, use the `agentuity-services` skill.
+For terminal management of resources, use the `agentuity-cloud` skill.
+
+## Common Mistakes
+
+| Mistake | Better approach |
+|---|---|
+| Moving framework files into Agentuity-owned folders | Keep route and page files where the framework expects them |
+| Creating project metadata by hand | Use `agentuity create` or `agentuity project import` |
+| Treating `agentuity dev` as mandatory | Use it only for CLI env wiring, tunnel output, or deploy-like validation |
+| Guessing deployment URLs | Read `agentuity deploy` output or inspect deployments with the CLI |
+| Importing from the repo root in a monorepo | Run from the app package or use `--dir` |
+
+## Useful Docs
+
+- Project structure: https://agentuity.dev/get-started/project-structure
+- Import existing app: https://agentuity.dev/get-started/import-existing-app
+- Deployment: https://agentuity.dev/reference/cli/deployment
+- Build configuration: https://agentuity.dev/reference/cli/build-configuration