Clawnify

View saved version →

---
name: build-a-clawnify-app
description: Author a Clawnify app end-to-end — the canonical Hono + React + Vite + @hono/zod-openapi + @clawnify/db (Drizzle) stack, schema.ts as the single schema source of truth (DDL generated via pnpm db:generate), OpenAPIHono routes (createRoute) that auto-generate an OpenAPI spec, and platform-injected identity via user()/orgId()/caller(). Use when building or modifying an app that deploys to the Clawnify platform.
---

# Build a Clawnify app

Canonical skill: how to author a Clawnify app end-to-end. Same content
for humans reading the docs and for AI coding agents injecting this as
instructions during an app build.

If you're an agent: this document is enough context to produce a
working app from scratch. Follow it literally. The patterns here
are exactly what `clawnify init` scaffolds and what the platform
expects.

## TL;DR

- **One stack.** Hono + React + Vite + `@hono/zod-openapi` +
  `@clawnify/db` (Drizzle) + `@clawnify/app` (entry, routing,
  identity) + Tailwind v4. Nothing else.
- **Schema lives in `schema.ts` alone** — the Drizzle DSL your queries
  compile against. The DDL is generated from it (`pnpm db:generate` →
  `.clawnify/drizzle/*.sql`); never hand-write a `schema.sql` in a
  scaffolded app.
- **Queries through `getDB`** — `import { getDB, eq } from
  "@clawnify/db"`. JSON columns auto-serialize.
- **API routes are `OpenAPIHono` + `createRoute`** — Zod-validated
  request/response.
- **`createApp()`** (from `@clawnify/app`) builds the entry — it returns an
  `OpenAPIHono` with API discovery already mounted (`/api/openapi.json` +
  `/llms.txt`, generated from your live routes). That descriptor *is* the
  tool surface agents discover. Never hand-write those routes.
- **One import.** `@clawnify/app` re-exports `createRoute`, `z` and
  `OpenAPIHono`, and adds `user` / `orgId` / `caller`. Import from it, not
  from `@clawnify/routes` directly.
- **`clawnify.json`** declares framework, env, and public routes.
  There is no `api.tools[]` — the agent discovers and calls your
  endpoints via `/llms.txt` (and the OpenAPI spec).
- **Identity is injected by the platform** — read it with `user(c)` /
  `orgId(c)` / `caller(c)` from `@clawnify/app`. Your app never
  authenticates anyone.

## Stack rationale

One template, one set of decisions. Don't deviate unless the user has
explicitly asked. `clawnify init` (type `app`) scaffolds either a
`blank` template (one GET route + a page) or a `crud` template (a
table with list/create/update/delete + a form). Both share the exact
same stack below.

## File layout

```
my-app/
  clawnify.json              ← Manifest (validated against /schema/v1/clawnify.json)
  package.json
  tsconfig.json
  vite.config.ts             ← @vitejs/plugin-react + @tailwindcss/vite; proxies /api → :8787
  index.html
  .gitignore
  .clawnify/                 ← Managed by the CLI (gitignored) — never edit
    wrangler.toml            ← Generated wrangler config
    drizzle.config.ts        ← Generated drizzle config (from clawnify.json + schema.ts)
    drizzle/                 ← Generated migration SQL (applied by dev + deploy)
    applied-migrations.json  ← Local-apply tracker
  src/
    server/
      index.ts               ← OpenAPIHono entry — mounts routes, serves /api/openapi.json
      routes.ts              ← OpenAPIHono + createRoute definitions — the API surface
      schema.ts              ← Drizzle table definitions — the single source of truth
      worker-env.d.ts        ← Cloudflare Workers types reference
      uploads.ts             ← R2 helpers (only when storage is enabled)
    client/
      main.tsx               ← React mount point
      app.tsx                ← Root component (plain fetch against /api/*)
      index.css              ← @import "tailwindcss"
```

## Schema — `schema.ts` is the single source of truth

`schema.ts` (Drizzle DSL) defines the tables. Do **not** hand-write a
`schema.sql` in a scaffolded app, and there is no toolchain co

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: build-a-clawnify-website
description: Build and ship a Clawnify website — Astro on Cloudflare Workers, the built-in form system (never hand-roll a form), images and assets, and the draft-then-publish deploy flow. Use when creating or editing a Clawnify website, or when a site needs a contact/waitlist/signup form.
---

# Build a Clawnify website

A Clawnify website is an **Astro** project deployed to Cloudflare Workers. One
site per organization. You write pages; the platform owns hosting, forms and
the publish flow.

```bash
npx clawnify@latest init --type website --name "My Site" website
cd website && pnpm install && pnpm dev     # http://localhost:4321
```

Always invoke the CLI as `npx clawnify@latest <command>` — never a
global or pinned install; stale CLIs miss deploy guards and fixes.

```
website/
  src/pages/          # one .astro file per route (index.astro → /)
  src/layouts/        # shared shell: nav, footer, <head>
  src/blocks/         # platform blocks you've adopted (see Forms below)
  public/             # images, favicons — served as-is from /
```

## Forms: use the built-in system. Do not build your own.

**This is the single most common mistake.** A site needs a contact or waitlist
form, and the obvious move is to write a `<form>` and POST it somewhere — your
own endpoint, a third-party form service, or the platform's submit URL with the
website id pasted in. All three are wrong, and the last one looks right enough
to survive review.

Clawnify has a form system. It captures submissions, stores them, can email you,
and can hand each one to an agent or a flow. You get all of it by using the
**Forms block** rather than writing a form yourself.

### How it works

- The submit target is **computed at render time** from `WEBSITE_ID` — a
  variable the platform bakes into your site's Worker — plus the form's id:

  ```astro
  const env = (Astro.locals as { runtime?: { env?: Record<string, string> } })?.runtime?.env;
  const websiteId = env?.WEBSITE_ID ?? "";
  const action = websiteId ? `https://provision.clawnify.com/forms/submit/${websiteId}/${formId}` : "";
  ```

  **Never hardcode the website id.** It is baked per Worker so a site can only
  ever submit to itself — hardcoding throws that away, and the literal goes
  stale the moment the site is recreated. An empty `action` in local `astro dev`
  is expected: there are no Worker vars locally, so the form simply no-ops.

- The submit script POSTs JSON with `Content-Type: text/plain;charset=UTF-8`.
  That is not a typo — `text/plain` is CORS-safelisted, so the request needs no
  preflight, which matters because the platform can't know your site's origin in
  advance. The route parses the text body as JSON.

- **Keep the Turnstile widget.** The ingest rejects a submission with no token,
  so a form without the widget fails every time with "Verification required".
  The sitekey shipped in the block is public and pairs with the platform's
  secret; the widget will not validate on `localhost`, only on a real hostname.

### Getting the block

Sites are seeded with the platform's block library at creation. If yours has
`src/blocks/Forms/Contact.astro`, import it and go. If it doesn't — an older
site, or one scaffolded bare by the CLI — copy it in from the website template
and adapt it.

**The design is yours; the plumbing is not.** Restyle the markup, labels and
classes freely. Preserve, exactly:

- the computed `action` (never a prop, never a literal),
- the Turnstile widget,
- the `data-clawnify-managed-form` attribute,
- `export const schema`,
- destructuring only known props — never splat leftover props onto `<form>`,
  or an injected `action` becomes a way to point your form at someone else.

There is no submit script to copy. The runtime lives in the framework catch-all
(`src/pages/[...path].astro`) and binds every `data-clawnify-managed-form` on
the page. If the block you inherited still has its own inline `<script>` and a
`data-clawnify-form` attribu

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: clawnify-knowledge
description: Route a question to the right Clawnify knowledge source before answering or building. Covers how-to-use-Clawnify product docs, your org's company knowledge (brand, pricing, policy, SOPs), a specific client or project's reference, and durable memory. Use whenever a task needs a company fact, a platform how-to, or client-specific context from a connected Clawnify organization.
---

# Clawnify knowledge router

You are connected to a Clawnify organization through the Clawnify connector.
Several knowledge sources sit behind it, and each answers a different kind of
question. Pick the right one and retrieve from it: these sources are current
and scoped to this organization, and your training data is neither.

## Route by question type

| The question is about | Use | Notes |
|---|---|---|
| How to use Clawnify itself: deploy an app, set up an agent, connections, platform features | docs.clawnify.com | Product docs; `https://docs.clawnify.com/llms.txt` indexes them. Check them before building against the platform. |
| Which of the org's apps handles something | `clawnify_docs_search` | Searches the org's apps by name and description. |
| The company's own facts: brand, pricing, policy, SOP, legal, FAQ | `company_knowledge_search`, then `company_knowledge_get` | The org's source of truth, a versioned wiki linked with `[[wikilinks]]`. |
| One specific client, engagement or project | `projects_list`, then `project_search` | Working reference for that project, not org-wide authority. |
| Something decided or learned before | `memory_recall` | Save durable facts back with `memory_write`, and `memory_pin` the ones that matter most. |
| A third-party library, framework or API | That vendor's own docs | Not in the Clawnify corpus. |
| Code in the repository you are working in | Read the code | The code beats any summary of it. |

## Rules

- **Retrieve, don't recall.** For a company, product or client fact, query the
  source. Never answer a Clawnify fact from memory of training data.
- **Cite company knowledge.** An answer grounded in a `company_knowledge` result
  cites it as `Per <Title> v<N>`.
- **A proposal is not published.** `company_knowledge_propose` creates a draft
  that a person reviews. Never present a proposal as a live fact.
- **No secrets or per-customer facts in company knowledge.** Those belong in a
  project, or nowhere.
- **Look before you build.** Before creating an app or an agent, check
  docs.clawnify.com for the current contract and `clawnify_list_apps` or
  `clawnify_list_agents` for what already exists.

View saved version →

---
name: organize-company-knowledge
description: >-
  Turn a dump of raw company files into a clean, foldered, citable Company
  Knowledge corpus — the company's brain. Use when the user has dropped many
  files into the Company Knowledge section (or connected a Drive) and wants the
  agent to distill and organize them: cluster by topic, distill each into a
  canonical markdown doc (merging across sources into reusable playbooks), file
  it into a folder, tag and link it, and propose it for review.
metadata:
  clawnify:
    displayName: Organize my knowledge
    trigger: manual
    inputs: []
---

# Organize Company Knowledge

The user dumped a pile of files and wants them turned into the company's
**brain** — organized, official Company Knowledge that every agent can draw on
and cite. Your job is to **curate, not mirror**: distill the material that is
*answer authority or reusable know-how* (policies, pricing, brand, SOPs, product
facts, FAQs, legal — **and the playbooks hidden inside the company's own
deliverables**) into a small set of clean markdown docs, each filed into the
right folder and linked to its neighbours — then hand the result to a human to
publish.

Nothing you create goes live automatically. You **propose**; a person reviews
and publishes from the dashboard.

## The mental model (read this first)

- **This builds the company brain, not a client filing cabinet.** Company
  Knowledge is the org-wide corpus every agent retrieves from and cites (`Per
  <Title> v<N>`). The goal of organizing a dump is to grow that shared brain.
  Almost everything answer-authority or reusable belongs here.

- **Deliverables are the richest brain material — distill the PATTERN, not the
  client.** An agency's dump is mostly *deliverables*: proposals, strategies,
  case studies, decks. A single raw proposal is not company fact — but the
  **pattern across all of them** ("how we structure a winning proposal", "how we
  run a festival digital strategy") is exactly the company's intelligence, and it
  IS citable. So **cluster deliverables across clients into canonical playbooks**
  — ONE "Proposal Playbook" distilled from seventeen proposals, not seventeen
  client-named docs. Strip the client-specific numbers; keep the reusable method.

- **Client-scoped facts are the rare exception, and you default away from them.**
  Only genuinely client-bound working facts (a specific client's budget, contacts,
  live campaign state) are *not* brain material. Those belong in that client's
  **Project** — but only when the org actually runs a per-client agent that needs
  them. Do **not** route deliverables there to "keep them separate": that buries
  the brain in silos. When unsure, it goes in the **brain** (the corpus).

- **Three axes inside Company Knowledge, kept separate.** A doc has:
  - a single **`folder`** — its ONE home, a slash-nested path like
    `playbooks/strategy`, shown as the browse tree (a doc appears in exactly one
    place). Omit for a top-level (Unfiled) doc.
  - many **`tags`** — cross-cutting labels for search/filter (e.g. `festival`,
    `enterprise`). NOT folders. A doc lives in one folder but can carry several
    tags.
  - optional **`meta`** — structured properties distilled from the material
    (e.g. `effective_date`, `owner`). Preserved for the human reviewer.

- **The dump's folder structure is a HINT, not a spec.** Whatever folders the
  client shipped (`Training Docs/`, `Strategies/`, `Proposals/`, `Brand/`) are
  *signal* about topic — read them, get inspired, reuse the parts already
  coherent. But you are curating, not copying: if their structure is messy,
  redundant, or one-doc-per-client, **re-derive a cleaner taxonomy** (e.g. collapse
  a `Proposals/` folder of per-client files into one `playbooks/` doc). Do not
  preserve a structure just because it was theirs.

- **Structure is also links.** Use `[[Doc Title]]` wikilinks between related docs.
  These render as the knowledge graph next to the folder tre

Preview of the first 4,000 characters. Read full instructions →