clawnify 0.16.1 → 0.16.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/{chunk-2I4XJ52D.js → chunk-SVYE433Z.js} +2 -2
- package/dist/{cli-KOUOVFNL.js → cli-6BGQXGSP.js} +209 -158
- package/dist/cli-6BGQXGSP.js.map +1 -0
- package/dist/index.js +2 -2
- package/dist/{mcp-SPP4XMFV.js → mcp-535MVWEO.js} +2 -2
- package/package.json +1 -1
- package/dist/cli-KOUOVFNL.js.map +0 -1
- /package/dist/{chunk-2I4XJ52D.js.map → chunk-SVYE433Z.js.map} +0 -0
- /package/dist/{mcp-SPP4XMFV.js.map → mcp-535MVWEO.js.map} +0 -0
|
@@ -20,7 +20,7 @@ import {
|
|
|
20
20
|
resolveOrgContext,
|
|
21
21
|
saveAuth,
|
|
22
22
|
saveProject
|
|
23
|
-
} from "./chunk-
|
|
23
|
+
} from "./chunk-SVYE433Z.js";
|
|
24
24
|
|
|
25
25
|
// src/cli.ts
|
|
26
26
|
import { Command, Option } from "commander";
|
|
@@ -175,8 +175,8 @@ async function loginCommand() {
|
|
|
175
175
|
}
|
|
176
176
|
|
|
177
177
|
// src/commands/deploy.ts
|
|
178
|
-
import
|
|
179
|
-
import
|
|
178
|
+
import fs3 from "fs";
|
|
179
|
+
import path3 from "path";
|
|
180
180
|
import readline2 from "readline";
|
|
181
181
|
import { spawn } from "child_process";
|
|
182
182
|
|
|
@@ -230,8 +230,8 @@ async function getOrCreateAnonContext(dir, name) {
|
|
|
230
230
|
saveAnon(dir, ctx);
|
|
231
231
|
return { ctx, created: true };
|
|
232
232
|
}
|
|
233
|
-
async function anonPostForm(
|
|
234
|
-
return api.request("POST",
|
|
233
|
+
async function anonPostForm(path12, formData, ctx) {
|
|
234
|
+
return api.request("POST", path12, { formData, token: ctx.deploy_token });
|
|
235
235
|
}
|
|
236
236
|
function explainAnonUnauthorized(dir) {
|
|
237
237
|
clearAnon(dir);
|
|
@@ -358,6 +358,32 @@ function hasUncommittedChanges(dir, filePath) {
|
|
|
358
358
|
}
|
|
359
359
|
}
|
|
360
360
|
|
|
361
|
+
// src/lib/drizzle.ts
|
|
362
|
+
import fs2 from "fs";
|
|
363
|
+
import path2 from "path";
|
|
364
|
+
var MANAGED_CONFIG = `import { defineConfig } from "drizzle-kit";
|
|
365
|
+
|
|
366
|
+
// Generated by the Clawnify CLI \u2014 do not edit. Derived from clawnify.json
|
|
367
|
+
// ("database": true) and src/server/schema.ts; regenerated on every
|
|
368
|
+
// dev / deploy / db generate run.
|
|
369
|
+
export default defineConfig({
|
|
370
|
+
schema: "./src/server/schema.ts",
|
|
371
|
+
out: "./.clawnify/drizzle",
|
|
372
|
+
dialect: "sqlite",
|
|
373
|
+
});
|
|
374
|
+
`;
|
|
375
|
+
function ensureDrizzleConfig(resolvedDir) {
|
|
376
|
+
const schemaTs = path2.join(resolvedDir, "src/server/schema.ts");
|
|
377
|
+
if (!fs2.existsSync(schemaTs)) return null;
|
|
378
|
+
const rootConfig = path2.join(resolvedDir, "drizzle.config.ts");
|
|
379
|
+
if (fs2.existsSync(rootConfig)) return rootConfig;
|
|
380
|
+
const clawnifyDir = path2.join(resolvedDir, ".clawnify");
|
|
381
|
+
fs2.mkdirSync(clawnifyDir, { recursive: true });
|
|
382
|
+
const managed = path2.join(clawnifyDir, "drizzle.config.ts");
|
|
383
|
+
fs2.writeFileSync(managed, MANAGED_CONFIG);
|
|
384
|
+
return managed;
|
|
385
|
+
}
|
|
386
|
+
|
|
361
387
|
// src/lib/servers.ts
|
|
362
388
|
async function resolveServerId(explicit) {
|
|
363
389
|
if (explicit) return explicit;
|
|
@@ -400,11 +426,11 @@ function ask(question) {
|
|
|
400
426
|
});
|
|
401
427
|
});
|
|
402
428
|
}
|
|
403
|
-
async function postFormWithRetry(
|
|
429
|
+
async function postFormWithRetry(path12, formData, orgId, attempts = 3) {
|
|
404
430
|
let lastErr;
|
|
405
431
|
for (let i = 0; i < attempts; i++) {
|
|
406
432
|
try {
|
|
407
|
-
return await api.postForm(
|
|
433
|
+
return await api.postForm(path12, formData, { orgId });
|
|
408
434
|
} catch (err) {
|
|
409
435
|
lastErr = err;
|
|
410
436
|
if (i === attempts - 1) break;
|
|
@@ -606,9 +632,9 @@ async function deployWebsite(dir, options) {
|
|
|
606
632
|
console.error("--from is app-only for now. Run `clawnify deploy` inside the website project directory.");
|
|
607
633
|
process.exit(EXIT_USAGE);
|
|
608
634
|
}
|
|
609
|
-
const resolvedDir = dir ?
|
|
635
|
+
const resolvedDir = dir ? path3.resolve(dir) : process.cwd();
|
|
610
636
|
const manifest = readManifest(resolvedDir);
|
|
611
|
-
const baseName = options.name || manifest?.name ||
|
|
637
|
+
const baseName = options.name || manifest?.name || path3.basename(resolvedDir);
|
|
612
638
|
const linkedProject = readProject(resolvedDir);
|
|
613
639
|
const { archive, files } = createArchive(resolvedDir);
|
|
614
640
|
if (isLoggedOut() && !options.org) {
|
|
@@ -736,12 +762,12 @@ async function deployWebsite(dir, options) {
|
|
|
736
762
|
}
|
|
737
763
|
}
|
|
738
764
|
function walkFiles(root, cb) {
|
|
739
|
-
if (!
|
|
765
|
+
if (!fs3.existsSync(root)) return;
|
|
740
766
|
const walk = (cur, prefix) => {
|
|
741
|
-
for (const name of
|
|
742
|
-
const abs =
|
|
767
|
+
for (const name of fs3.readdirSync(cur)) {
|
|
768
|
+
const abs = path3.join(cur, name);
|
|
743
769
|
const rel = prefix ? `${prefix}/${name}` : name;
|
|
744
|
-
if (
|
|
770
|
+
if (fs3.statSync(abs).isDirectory()) walk(abs, rel);
|
|
745
771
|
else cb(rel, abs);
|
|
746
772
|
}
|
|
747
773
|
};
|
|
@@ -749,25 +775,25 @@ function walkFiles(root, cb) {
|
|
|
749
775
|
}
|
|
750
776
|
function assembleAgentFiles(dir) {
|
|
751
777
|
const out = [];
|
|
752
|
-
const agentMd =
|
|
753
|
-
if (
|
|
754
|
-
out.push({ path: "AGENTS.md", content:
|
|
778
|
+
const agentMd = path3.join(dir, "AGENT.md");
|
|
779
|
+
if (fs3.existsSync(agentMd)) {
|
|
780
|
+
out.push({ path: "AGENTS.md", content: fs3.readFileSync(agentMd, "utf8") });
|
|
755
781
|
}
|
|
756
|
-
walkFiles(
|
|
757
|
-
if (
|
|
758
|
-
out.push({ path: `skills/${rel}`, content:
|
|
782
|
+
walkFiles(path3.join(dir, "skills"), (rel, abs) => {
|
|
783
|
+
if (path3.basename(abs) === ".gitkeep") return;
|
|
784
|
+
out.push({ path: `skills/${rel}`, content: fs3.readFileSync(abs, "utf8") });
|
|
759
785
|
});
|
|
760
|
-
const flowsDir =
|
|
761
|
-
if (
|
|
762
|
-
for (const name of
|
|
786
|
+
const flowsDir = path3.join(dir, "flows");
|
|
787
|
+
if (fs3.existsSync(flowsDir)) {
|
|
788
|
+
for (const name of fs3.readdirSync(flowsDir)) {
|
|
763
789
|
if (!name.endsWith(".json")) continue;
|
|
764
|
-
out.push({ path: `flows/${name}`, content:
|
|
790
|
+
out.push({ path: `flows/${name}`, content: fs3.readFileSync(path3.join(flowsDir, name), "utf8") });
|
|
765
791
|
}
|
|
766
792
|
}
|
|
767
793
|
return out;
|
|
768
794
|
}
|
|
769
795
|
async function deployAgent(dir, options) {
|
|
770
|
-
const resolvedDir = dir ?
|
|
796
|
+
const resolvedDir = dir ? path3.resolve(dir) : process.cwd();
|
|
771
797
|
const linked = readProject(resolvedDir);
|
|
772
798
|
const serverId = await resolveServerId(options.server || linked?.server_id);
|
|
773
799
|
const agentName = options.agent || linked?.agent_name || "main";
|
|
@@ -830,7 +856,7 @@ async function deployAgent(dir, options) {
|
|
|
830
856
|
async function deployCommand(dir, options = {}) {
|
|
831
857
|
assertNodeVersion();
|
|
832
858
|
if (!options.from) {
|
|
833
|
-
const resolvedDir = dir ?
|
|
859
|
+
const resolvedDir = dir ? path3.resolve(dir) : process.cwd();
|
|
834
860
|
const manifest = readManifest(resolvedDir);
|
|
835
861
|
if (!manifest && readWorkspaceConfig(resolvedDir)) {
|
|
836
862
|
console.error(
|
|
@@ -852,16 +878,16 @@ async function deployCommand(dir, options = {}) {
|
|
|
852
878
|
process.exit(EXIT_USAGE);
|
|
853
879
|
}
|
|
854
880
|
}
|
|
855
|
-
if (!manifest && (
|
|
881
|
+
if (!manifest && (fs3.existsSync(path3.join(resolvedDir, "astro.config.mjs")) || fs3.existsSync(path3.join(resolvedDir, "astro.config.ts"))) && fs3.existsSync(path3.join(resolvedDir, "src", "tree"))) {
|
|
856
882
|
console.error(
|
|
857
883
|
'This looks like a Clawnify website, but it has no clawnify.json so it\ncannot be told apart from an app \u2014 deploying it as one creates a broken app.\n\n Add a clawnify.json here:\n { "version": 1, "name": "website", "website": { "framework": "astro" } }\n\n Or push to the synced workspace repo, which rebuilds the site for you.'
|
|
858
884
|
);
|
|
859
885
|
process.exit(EXIT_USAGE);
|
|
860
886
|
}
|
|
861
887
|
}
|
|
862
|
-
let appId;
|
|
863
|
-
let slug;
|
|
864
|
-
let appToken;
|
|
888
|
+
let appId = "";
|
|
889
|
+
let slug = "";
|
|
890
|
+
let appToken = "";
|
|
865
891
|
let resolvedOrgId;
|
|
866
892
|
let syncTargetDir;
|
|
867
893
|
if (options.from) {
|
|
@@ -913,10 +939,10 @@ async function deployCommand(dir, options = {}) {
|
|
|
913
939
|
appToken = result2.data.app_token;
|
|
914
940
|
resolvedOrgId = orgId;
|
|
915
941
|
} else {
|
|
916
|
-
const resolvedDir = dir ?
|
|
942
|
+
const resolvedDir = dir ? path3.resolve(dir) : process.cwd();
|
|
917
943
|
syncTargetDir = resolvedDir;
|
|
918
944
|
const manifest = readManifest(resolvedDir);
|
|
919
|
-
const baseName = options.name || manifest?.name ||
|
|
945
|
+
const baseName = options.name || manifest?.name || path3.basename(resolvedDir);
|
|
920
946
|
const framework = manifest?.app?.framework || "vite-preact";
|
|
921
947
|
const linkedProject = readProject(resolvedDir);
|
|
922
948
|
await regenerateDrizzleMigrations(resolvedDir);
|
|
@@ -1057,9 +1083,9 @@ async function deployCommand(dir, options = {}) {
|
|
|
1057
1083
|
if (syncTargetDir && !options.noSync && resolvedOrgId) {
|
|
1058
1084
|
try {
|
|
1059
1085
|
const schema = await fetchSchema({ appId, orgId: resolvedOrgId });
|
|
1060
|
-
const target =
|
|
1086
|
+
const target = path3.join(syncTargetDir, "schema.sql");
|
|
1061
1087
|
const writeResult = await writeSchema(target, schema);
|
|
1062
|
-
const rel =
|
|
1088
|
+
const rel = path3.relative(process.cwd(), writeResult.path) || writeResult.path;
|
|
1063
1089
|
switch (writeResult.status) {
|
|
1064
1090
|
case "written":
|
|
1065
1091
|
console.log(` Synced ${rel} (${writeResult.bytes} bytes)
|
|
@@ -1090,11 +1116,10 @@ async function deployCommand(dir, options = {}) {
|
|
|
1090
1116
|
}
|
|
1091
1117
|
}
|
|
1092
1118
|
async function regenerateDrizzleMigrations(resolvedDir) {
|
|
1093
|
-
const
|
|
1094
|
-
|
|
1095
|
-
if (!fs2.existsSync(schemaTs) || !fs2.existsSync(drizzleConfig)) return;
|
|
1119
|
+
const drizzleConfig = ensureDrizzleConfig(resolvedDir);
|
|
1120
|
+
if (!drizzleConfig) return;
|
|
1096
1121
|
await new Promise((resolve) => {
|
|
1097
|
-
const proc = spawn("npx", ["drizzle-kit", "generate"], {
|
|
1122
|
+
const proc = spawn("npx", ["drizzle-kit", "generate", `--config=${drizzleConfig}`], {
|
|
1098
1123
|
cwd: resolvedDir,
|
|
1099
1124
|
stdio: ["ignore", "pipe", "pipe"],
|
|
1100
1125
|
env: { ...process.env }
|
|
@@ -1119,20 +1144,20 @@ async function regenerateDrizzleMigrations(resolvedDir) {
|
|
|
1119
1144
|
}
|
|
1120
1145
|
function assertDatabaseDdlPresent(resolvedDir, manifest) {
|
|
1121
1146
|
if (!manifest?.app?.database) return;
|
|
1122
|
-
const hasSchemaSql =
|
|
1147
|
+
const hasSchemaSql = fs3.existsSync(path3.join(resolvedDir, "schema.sql")) || fs3.existsSync(path3.join(resolvedDir, "src/server/schema.sql"));
|
|
1123
1148
|
if (hasSchemaSql) return;
|
|
1124
|
-
const drizzleDir =
|
|
1125
|
-
const hasDrizzleSql =
|
|
1149
|
+
const drizzleDir = path3.join(resolvedDir, ".clawnify", "drizzle");
|
|
1150
|
+
const hasDrizzleSql = fs3.existsSync(drizzleDir) && fs3.readdirSync(drizzleDir).some((f) => f.endsWith(".sql"));
|
|
1126
1151
|
if (hasDrizzleSql) return;
|
|
1127
1152
|
console.error(
|
|
1128
1153
|
`Deploy aborted: this app sets "database": true in clawnify.json, but no schema
|
|
1129
1154
|
would be applied \u2014 so every query would fail at runtime with "no such table".
|
|
1130
1155
|
|
|
1131
1156
|
Fix:
|
|
1132
|
-
\u2022
|
|
1157
|
+
\u2022 npx clawnify@latest db generate (emits .clawnify/drizzle/*.sql from src/server/schema.ts)
|
|
1133
1158
|
If that just failed, see the warning above \u2014 drizzle-kit ships as a
|
|
1134
1159
|
devDependency, so run your package manager's install first.
|
|
1135
|
-
\u2022 set "database": false
|
|
1160
|
+
\u2022 set "database": false (if this app genuinely has no database)
|
|
1136
1161
|
|
|
1137
1162
|
schema.ts is the source of truth; a hand-written schema.sql at the app root
|
|
1138
1163
|
is also accepted, but only for apps not using Drizzle.`
|
|
@@ -1274,8 +1299,8 @@ async function sessionsHistoryCommand(key, opts) {
|
|
|
1274
1299
|
}
|
|
1275
1300
|
|
|
1276
1301
|
// src/commands/agents.ts
|
|
1277
|
-
import
|
|
1278
|
-
import
|
|
1302
|
+
import fs4 from "fs";
|
|
1303
|
+
import path4 from "path";
|
|
1279
1304
|
async function agentsListCommand() {
|
|
1280
1305
|
const res = await api.get("/agents");
|
|
1281
1306
|
if (!res.ok) {
|
|
@@ -1322,15 +1347,15 @@ async function agentsPullCommand(dir, opts) {
|
|
|
1322
1347
|
process.exit(1);
|
|
1323
1348
|
}
|
|
1324
1349
|
const { files } = await res.json();
|
|
1325
|
-
const target = dir ?
|
|
1326
|
-
|
|
1350
|
+
const target = dir ? path4.resolve(dir) : process.cwd();
|
|
1351
|
+
fs4.mkdirSync(target, { recursive: true });
|
|
1327
1352
|
let written = 0;
|
|
1328
1353
|
for (const f of files ?? []) {
|
|
1329
|
-
const norm =
|
|
1354
|
+
const norm = path4.posix.normalize(f.path);
|
|
1330
1355
|
if (norm.startsWith("/") || norm.split("/").includes("..")) continue;
|
|
1331
|
-
const abs =
|
|
1332
|
-
|
|
1333
|
-
|
|
1356
|
+
const abs = path4.join(target, norm);
|
|
1357
|
+
fs4.mkdirSync(path4.dirname(abs), { recursive: true });
|
|
1358
|
+
fs4.writeFileSync(abs, f.content);
|
|
1334
1359
|
written++;
|
|
1335
1360
|
}
|
|
1336
1361
|
const existing = readProject(target) ?? {};
|
|
@@ -1339,14 +1364,14 @@ async function agentsPullCommand(dir, opts) {
|
|
|
1339
1364
|
console.log(`Edit AGENTS.md / skills / flows, then push: clawnify agents push${dir ? ` ${dir}` : ""}`);
|
|
1340
1365
|
}
|
|
1341
1366
|
async function agentsPushCommand(dir, opts) {
|
|
1342
|
-
const target = dir ?
|
|
1367
|
+
const target = dir ? path4.resolve(dir) : process.cwd();
|
|
1343
1368
|
const linked = readProject(target);
|
|
1344
1369
|
const serverId = await resolveServerId(opts.server || linked?.server_id);
|
|
1345
1370
|
const agent = opts.agent || linked?.agent_name || "main";
|
|
1346
1371
|
const files = [];
|
|
1347
1372
|
const add = (rel) => {
|
|
1348
1373
|
try {
|
|
1349
|
-
files.push({ path: rel, content:
|
|
1374
|
+
files.push({ path: rel, content: fs4.readFileSync(path4.join(target, rel), "utf8") });
|
|
1350
1375
|
} catch {
|
|
1351
1376
|
}
|
|
1352
1377
|
};
|
|
@@ -1354,7 +1379,7 @@ async function agentsPushCommand(dir, opts) {
|
|
|
1354
1379
|
const walk = (relDir) => {
|
|
1355
1380
|
let names;
|
|
1356
1381
|
try {
|
|
1357
|
-
names =
|
|
1382
|
+
names = fs4.readdirSync(path4.join(target, relDir));
|
|
1358
1383
|
} catch {
|
|
1359
1384
|
return;
|
|
1360
1385
|
}
|
|
@@ -1362,7 +1387,7 @@ async function agentsPushCommand(dir, opts) {
|
|
|
1362
1387
|
const rel = `${relDir}/${name}`;
|
|
1363
1388
|
let isDir = false;
|
|
1364
1389
|
try {
|
|
1365
|
-
isDir =
|
|
1390
|
+
isDir = fs4.statSync(path4.join(target, rel)).isDirectory();
|
|
1366
1391
|
} catch {
|
|
1367
1392
|
continue;
|
|
1368
1393
|
}
|
|
@@ -1373,7 +1398,7 @@ async function agentsPushCommand(dir, opts) {
|
|
|
1373
1398
|
walk("skills");
|
|
1374
1399
|
let flowNames = [];
|
|
1375
1400
|
try {
|
|
1376
|
-
flowNames =
|
|
1401
|
+
flowNames = fs4.readdirSync(path4.join(target, "flows"));
|
|
1377
1402
|
} catch {
|
|
1378
1403
|
}
|
|
1379
1404
|
for (const name of flowNames) if (name.endsWith(".json")) add(`flows/${name}`);
|
|
@@ -1496,7 +1521,7 @@ async function envUnsetCommand(key) {
|
|
|
1496
1521
|
}
|
|
1497
1522
|
|
|
1498
1523
|
// src/commands/api.ts
|
|
1499
|
-
async function apiCommand(
|
|
1524
|
+
async function apiCommand(path12, opts) {
|
|
1500
1525
|
const method = (opts.method || (opts.data !== void 0 ? "POST" : "GET")).toUpperCase();
|
|
1501
1526
|
let body;
|
|
1502
1527
|
if (opts.data !== void 0) {
|
|
@@ -1507,7 +1532,7 @@ async function apiCommand(path10, opts) {
|
|
|
1507
1532
|
process.exit(1);
|
|
1508
1533
|
}
|
|
1509
1534
|
}
|
|
1510
|
-
const p =
|
|
1535
|
+
const p = path12.startsWith("/") ? path12 : `/${path12}`;
|
|
1511
1536
|
const orgId = await resolveOrgContext({ orgFlag: opts.org });
|
|
1512
1537
|
const res = await api.call(method, p, { body, orgId });
|
|
1513
1538
|
const text = await res.text();
|
|
@@ -1616,8 +1641,8 @@ async function whoamiCommand() {
|
|
|
1616
1641
|
}
|
|
1617
1642
|
|
|
1618
1643
|
// src/commands/init.ts
|
|
1619
|
-
import
|
|
1620
|
-
import
|
|
1644
|
+
import fs5 from "fs";
|
|
1645
|
+
import path5 from "path";
|
|
1621
1646
|
import readline4 from "readline";
|
|
1622
1647
|
|
|
1623
1648
|
// src/lib/skills/detect.ts
|
|
@@ -1631,9 +1656,9 @@ var DETECTORS = [
|
|
|
1631
1656
|
{ agent: "aider", markers: ["CONVENTIONS.md", ".aider.conf.yml"], target: "CONVENTIONS.md" }
|
|
1632
1657
|
];
|
|
1633
1658
|
function exists(cwd, name) {
|
|
1634
|
-
const
|
|
1659
|
+
const path12 = join(cwd, name);
|
|
1635
1660
|
try {
|
|
1636
|
-
statSync(
|
|
1661
|
+
statSync(path12);
|
|
1637
1662
|
return true;
|
|
1638
1663
|
} catch {
|
|
1639
1664
|
return false;
|
|
@@ -1657,31 +1682,31 @@ function agentByName(name) {
|
|
|
1657
1682
|
var ALL_AGENTS = DETECTORS.map((d) => d.agent);
|
|
1658
1683
|
|
|
1659
1684
|
// src/lib/skills/content.gen.ts
|
|
1660
|
-
var CLI_VERSION = "0.16.
|
|
1685
|
+
var CLI_VERSION = "0.16.3";
|
|
1661
1686
|
var BUNDLED_SKILLS = [
|
|
1662
1687
|
{
|
|
1663
1688
|
name: "build-a-clawnify-app",
|
|
1664
|
-
description: "Author a Clawnify app end-to-end \u2014 the canonical Hono + React + Vite + @hono/zod-openapi + @clawnify/db (Drizzle) stack, schema.ts
|
|
1665
|
-
content: '# Build a Clawnify app\n\nCanonical skill: how to author a Clawnify app end-to-end. Same content\nfor humans reading the docs and for AI coding agents injecting this as\ninstructions during an app build.\n\nIf you\'re an agent: this document is enough context to produce a\nworking app from scratch. Follow it literally. The patterns here\nare exactly what `clawnify init` scaffolds and what the platform\nexpects.\n\n## TL;DR\n\n- **One stack.** Hono + React + Vite + `@hono/zod-openapi` +\n `@clawnify/db` (Drizzle) + `@clawnify/app` (entry, routing,\n identity) + Tailwind v4. Nothing else.\n- **Schema lives in two files kept in sync** \u2014 `schema.ts` (Drizzle\n DSL, the typed view your queries use) and `schema.sql` (the DDL the\n deploy applies to your app\'s D1). Change one, change the other.\n- **Queries through `getDB`** \u2014 `import { getDB, eq } from\n "@clawnify/db"`. JSON columns auto-serialize.\n- **API routes are `OpenAPIHono` + `createRoute`** \u2014 Zod-validated\n request/response.\n- **`createApp()`** (from `@clawnify/app`) builds the entry \u2014 it returns an\n `OpenAPIHono` with API discovery already mounted (`/api/openapi.json` +\n `/llms.txt`, generated from your live routes). That descriptor *is* the\n tool surface agents discover. Never hand-write those routes.\n- **One import.** `@clawnify/app` re-exports `createRoute`, `z` and\n `OpenAPIHono`, and adds `user` / `orgId` / `caller`. Import from it, not\n from `@clawnify/routes` directly.\n- **`clawnify.json`** declares framework, env, and public routes.\n There is no `api.tools[]` \u2014 the agent discovers and calls your\n endpoints via `/llms.txt` (and the OpenAPI spec).\n- **Identity is injected by the platform** \u2014 read it with `user(c)` /\n `orgId(c)` / `caller(c)` from `@clawnify/app`. Your app never\n authenticates anyone.\n\n## Stack rationale\n\nOne template, one set of decisions. Don\'t deviate unless the user has\nexplicitly asked. `clawnify init` (type `app`) scaffolds either a\n`blank` template (one GET route + a page) or a `crud` template (a\ntable with list/create/update/delete + a form). Both share the exact\nsame stack below.\n\n## File layout\n\n```\nmy-app/\n clawnify.json \u2190 Manifest (validated against /schema/v1/clawnify.json)\n package.json\n tsconfig.json\n vite.config.ts \u2190 @vitejs/plugin-react + @tailwindcss/vite; proxies /api \u2192 :8787\n index.html\n .gitignore\n .clawnify/ \u2190 CLI cache (gitignored)\n wrangler.toml \u2190 Generated per-dev wrangler config\n src/\n server/\n index.ts \u2190 OpenAPIHono entry \u2014 mounts routes, serves /api/openapi.json\n routes.ts \u2190 OpenAPIHono + createRoute definitions \u2014 the API surface\n schema.ts \u2190 Drizzle table definitions (typed view for queries)\n schema.sql \u2190 canonical DDL the deploy applies \u2014 keep in sync with schema.ts\n worker-env.d.ts \u2190 Cloudflare Workers types reference\n uploads.ts \u2190 R2 helpers (only when storage is enabled)\n client/\n main.tsx \u2190 React mount point\n app.tsx \u2190 Root component (plain fetch against /api/*)\n index.css \u2190 @import "tailwindcss"\n```\n\n## Schema \u2014 `schema.ts` + `schema.sql`, kept in sync\n\nTwo files describe the same tables. `schema.ts` (Drizzle DSL) is the\ntyped view your queries compile against; `schema.sql` is the DDL the\ndeploy applies to your app\'s D1. **When you change one, update the\nother** \u2014 they must describe the same tables.\n\nThe scaffold\'s starter table (blank template):\n\n```ts\n// src/server/schema.ts\nimport { sqliteTable, text, integer } from "@clawnify/db";\n\nexport const items = sqliteTable("items", {\n id: integer("id").primaryKey({ autoIncrement: true }),\n name: text("name").notNull(),\n createdAt: text("created_at").notNull().$default(() => new Date().toISOString()),\n});\n```\n\nReal apps are multi-tenant. Every user-facing table carries an\n`org_id`, every query filters by it. JSON columns and indexes use the\nDrizzle DSL re-exported from `@clawnify/db`:\n\n```ts\nimport { sqliteTable, text, integer, index } from "@clawnify/db";\n\nexport const notes = sqliteTable(\n "notes",\n {\n id: integer("id").primaryKey({ autoIncrement: true }),\n orgId: text("org_id").notNull(), // ALWAYS filter by this in queries\n title: text("title").notNull(),\n body: text("body").notNull().default(""),\n tags: text("tags", { mode: "json" }).$type<string[]>().notNull().default([]),\n createdAt: text("created_at").notNull().$default(() => new Date().toISOString()),\n },\n (t) => ({\n byOrg: index("notes_by_org").on(t.orgId, t.createdAt),\n }),\n);\n```\n\nRules:\n- JSON columns: `text(col, { mode: "json" }).$type<T>()` \u2014 Drizzle\n serializes on write and parses on read.\n- Multi-tenancy: every user-facing table has `org_id`. Every query\n filters by it. No exceptions.\n- Identifiers: snake_case in SQL, camelCase in TS (Drizzle bridges).\n\n## `schema.sql` \u2014 the DDL the deploy applies\n\nAlongside `schema.ts`, keep a `schema.sql` describing the same tables.\nThis is the DDL applied to your app\'s database on deploy.\n\n```sql\n-- src/server/schema.sql (mirror of the schema.ts tables)\nCREATE TABLE IF NOT EXISTS notes (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n org_id TEXT NOT NULL,\n title TEXT NOT NULL,\n body TEXT NOT NULL DEFAULT \'\',\n tags TEXT NOT NULL DEFAULT \'[]\', -- JSON column\n created_at TEXT NOT NULL\n);\nCREATE INDEX IF NOT EXISTS notes_by_org ON notes(org_id, created_at);\n```\n\nRules:\n- Always `CREATE TABLE IF NOT EXISTS` \u2014 the apply is additive and\n re-run-safe.\n- Add a new column with `ALTER TABLE <t> ADD COLUMN \u2026` at the **end** of\n `schema.sql`, and reflect it in `schema.ts`. The deploy adds it.\n- Deploys are **additive**: new tables and columns are added\n automatically. Destructive changes (dropping or retyping a column) are\n not applied automatically \u2014 do those deliberately, and never drop a\n table with user data unless explicitly asked.\n- **Never let `schema.ts` and `schema.sql` drift.** Change one, change\n the other \u2014 they must describe the same tables.\n\n## `src/server/index.ts` \u2014 the entry\n\n```ts\nimport { createApp } from "@clawnify/app";\nimport api from "./routes";\n\ntype Env = { Bindings: { DB: D1Database } };\n\n// db:false \u2014 this app reads the database per request via getDB(c.env),\n// which needs no init middleware.\nconst app = createApp<Env>({ title: "My app", version: "1.0.0", db: false });\n\napp.route("/", api);\n\nexport default app;\n```\n\nThe entry is thin: `createApp()` then mount your routes. `createApp`\nreturns an `OpenAPIHono` with **API discovery already mounted** \u2014 it\nserves both `/api/openapi.json` (generated from your `createRoute`\ndefinitions, with schemas) **and** `/llms.txt` (the same, agent-readable).\nAny `/api/*` route written as a plain `app.get` with no `createRoute` is\nstill listed from the live route table, so the endpoint inventory is\nalways complete. **Never hand-write a `/openapi.json` or `/llms.txt`\nhandler** \u2014 and don\'t call `mountDiscovery` yourself; `createApp` did it.\n\nWhen storage (file uploads) is enabled, the entry also wires the R2\nbucket in a middleware before mounting routes:\n\n```ts\nimport { createApp } from "@clawnify/app";\nimport { initUploads } from "./uploads";\nimport api from "./routes";\n\ntype Env = { Bindings: { DB: D1Database; UPLOADS: R2Bucket } };\n\nconst app = createApp<Env>({ title: "My app", version: "1.0.0", db: false });\n\napp.use("*", async (c, next) => {\n initUploads(c.env.UPLOADS);\n await next();\n});\n\napp.route("/", api);\n\nexport default app;\n```\n\n## `src/server/routes.ts` \u2014 routes with `createRoute`\n\nEach endpoint is a `createRoute({ method, path, summary, request, responses })`\ndefinition paired with a handler via `api.openapi(route, handler)`.\nRequest bodies and params are Zod-validated (`c.req.valid("json")`,\n`c.req.valid("param")`); response shapes are declared with\n`.openapi("Name")` Zod schemas so they land in the generated spec.\n\nBlank template \u2014 one read route:\n\n```ts\nimport { OpenAPIHono, createRoute, z } from "@clawnify/app";\nimport { getDB, desc } from "@clawnify/db";\nimport * as schema from "./schema";\n\ntype Env = { Bindings: { DB: D1Database } };\nconst api = new OpenAPIHono<Env>();\n\nconst ItemSchema = z.object({\n id: z.number(),\n name: z.string(),\n createdAt: z.string(),\n}).openapi("Item");\n\napi.openapi(\n createRoute({\n method: "get",\n path: "/api/items",\n summary: "List items",\n responses: {\n 200: {\n description: "List of items",\n content: { "application/json": { schema: z.array(ItemSchema) } },\n },\n },\n }),\n async (c) => {\n const db = getDB(c.env, { schema });\n const items = await db\n .select()\n .from(schema.items)\n .orderBy(desc(schema.items.createdAt));\n return c.json(items);\n },\n);\n\nexport default api;\n```\n\nCRUD template \u2014 the full list/create/update/delete surface:\n\n```ts\nimport { OpenAPIHono, createRoute, z } from "@clawnify/app";\nimport { getDB, eq, desc } from "@clawnify/db";\nimport * as schema from "./schema";\n\ntype Env = { Bindings: { DB: D1Database } };\nconst api = new OpenAPIHono<Env>();\n\nconst ItemSchema = z.object({\n id: z.number(),\n title: z.string(),\n status: z.string(),\n createdAt: z.string(),\n}).openapi("Item");\n\nconst CreateItemSchema = z.object({ title: z.string().min(1) }).openapi("CreateItem");\nconst UpdateItemSchema = z.object({\n title: z.string().min(1).optional(),\n status: z.string().optional(),\n}).openapi("UpdateItem");\nconst IdParamSchema = z.object({ id: z.string() });\nconst OkSchema = z.object({ ok: z.boolean() }).openapi("Ok");\n\napi.openapi(\n createRoute({\n method: "get",\n path: "/api/items",\n summary: "List items",\n responses: {\n 200: {\n description: "List of items",\n content: { "application/json": { schema: z.array(ItemSchema) } },\n },\n },\n }),\n async (c) => {\n const db = getDB(c.env, { schema });\n const items = await db\n .select()\n .from(schema.items)\n .orderBy(desc(schema.items.createdAt));\n return c.json(items);\n },\n);\n\napi.openapi(\n createRoute({\n method: "post",\n path: "/api/items",\n summary: "Create item",\n request: { body: { content: { "application/json": { schema: CreateItemSchema } } } },\n responses: {\n 201: {\n description: "Created item",\n content: { "application/json": { schema: ItemSchema } },\n },\n },\n }),\n async (c) => {\n const { title } = c.req.valid("json");\n const db = getDB(c.env, { schema });\n const [row] = await db\n .insert(schema.items)\n .values({ title: title.trim() })\n .returning();\n return c.json(row, 201);\n },\n);\n\napi.openapi(\n createRoute({\n method: "patch",\n path: "/api/items/:id",\n summary: "Update item",\n request: {\n params: IdParamSchema,\n body: { content: { "application/json": { schema: UpdateItemSchema } } },\n },\n responses: {\n 200: { description: "Updated", content: { "application/json": { schema: OkSchema } } },\n },\n }),\n async (c) => {\n const { id } = c.req.valid("param");\n const body = c.req.valid("json");\n const patch: Partial<typeof schema.items.$inferInsert> = {};\n if (body.title !== undefined) patch.title = body.title;\n if (body.status !== undefined) patch.status = body.status;\n if (Object.keys(patch).length === 0) return c.json({ ok: false }, 400);\n const db = getDB(c.env, { schema });\n await db.update(schema.items).set(patch).where(eq(schema.items.id, Number(id)));\n return c.json({ ok: true });\n },\n);\n\napi.openapi(\n createRoute({\n method: "delete",\n path: "/api/items/:id",\n summary: "Delete item",\n request: { params: IdParamSchema },\n responses: {\n 200: { description: "Deleted", content: { "application/json": { schema: OkSchema } } },\n },\n }),\n async (c) => {\n const { id } = c.req.valid("param");\n const db = getDB(c.env, { schema });\n await db.delete(schema.items).where(eq(schema.items.id, Number(id)));\n return c.json({ ok: true });\n },\n);\n\nexport default api;\n```\n\nPatterns to follow:\n- **Give every route a clear `summary`/`description`.** The generated\n OpenAPI spec is what the agent reads to decide which endpoint to\n call \u2014 a vague summary makes your endpoint invisible in practice.\n- **Validate input with Zod** via `request.body` / `request.params`\n and read it with `c.req.valid("json")` / `c.req.valid("param")`.\n Never parse `c.req.raw` by hand.\n- **Declare response shapes** with `.openapi("Name")` schemas \u2014 they\n become the documented return type in the spec.\n- **Filter by the org** on every user-facing query (see "who is\n calling" below). No exceptions.\n\n## `src/server` \u2014 who is calling\n\nThe platform authenticates every caller at its perimeter and injects a\nverified identity onto the request (it strips any client-supplied\nversion first, so it can\'t be spoofed). Your app never authenticates\nanyone: no `Authorization`, no cookies, no JWT, no login screen.\n\nRead it with the helpers from `@clawnify/app` \u2014 don\'t parse headers\nyourself:\n\n```ts\nimport { user, orgId, caller } from "@clawnify/app";\n\napp.get("/api/notes", async (c) => {\n const org = orgId(c);\n if (!org) return c.json({ error: "unauthorized" }, 401);\n\n const db = getDB(c.env, { schema });\n return c.json(\n await db.select().from(schema.notes).where(eq(schema.notes.orgId, org)),\n );\n});\n```\n\n| Helper | Returns |\n|--------|---------|\n| `orgId(c)` | Organization UUID \u2014 the tenant key. Filter every user-facing query by it. |\n| `user(c)` | `{ id, email, name, avatarUrl, firstName, lastName }` \u2014 or **`null`** when the caller isn\'t a person. |\n| `caller(c)` | `user`, `api`, `agent`, `agent-browser`, `public`, `bypass`, `system`, or `app`. |\n\nTwo rules that catch people out:\n\n- **`user(c)` is null for five of the eight caller kinds**\n (`agent-browser`, `public`, `bypass`, `system`, `app`). Always handle\n the null case \u2014 don\'t assume a person is present just because a\n request arrived. For per-user rows, store `user(c).id` in a `user_id`\n column and filter on it, exactly as you filter on `org_id`.\n- **`firstName` / `lastName` are a heuristic** split of a single stored\n full name (first word / the rest). Fine for a greeting; never persist\n them or treat them as someone\'s legal name \u2014 store `name`.\n\nDon\'t build app-level users, roles, or permissions. Authorization\nalready happened at the perimeter.\n\n## `src/client` \u2014 React + plain fetch\n\nThe client mounts React and talks to the API with plain `fetch`\nagainst the `/api/*` routes. No data-layer library is scaffolded.\n\n```tsx\n// src/client/main.tsx\nimport { StrictMode } from "react";\nimport { createRoot } from "react-dom/client";\nimport { App } from "./app";\nimport "./index.css";\n\ncreateRoot(document.getElementById("app")!).render(\n <StrictMode>\n <App />\n </StrictMode>\n);\n```\n\n```tsx\n// src/client/app.tsx (CRUD template shape)\nimport { useState, useEffect } from "react";\n\ninterface Item {\n id: number;\n title: string;\n status: string;\n createdAt: string;\n}\n\nexport function App() {\n const [items, setItems] = useState<Item[]>([]);\n const [title, setTitle] = useState("");\n\n async function load() {\n const res = await fetch("/api/items");\n setItems(await res.json());\n }\n\n useEffect(() => { load(); }, []);\n\n async function addItem(e: React.FormEvent) {\n e.preventDefault();\n if (!title.trim()) return;\n await fetch("/api/items", {\n method: "POST",\n headers: { "Content-Type": "application/json" },\n body: JSON.stringify({ title }),\n });\n setTitle("");\n load();\n }\n\n // ...toggleStatus / deleteItem call PATCH/DELETE the same way.\n\n return (\n <div className="max-w-xl mx-auto mt-10 px-4">\n {/* form + list */}\n </div>\n );\n}\n```\n\nIn local dev, Vite proxies `/api` to the Worker on `:8787` (see\n`vite.config.ts`), so the same relative fetch paths work in dev and\nin production. The API is the one contract: the UI calls it over\n`fetch`, and the agent calls it over the OpenAPI spec.\n\n## Design\n\nIf the project contains a `DESIGN.md`, it is the single source of\ntruth for visuals \u2014 follow its tokens, don\'t restyle around it. The\nscaffold ships Tailwind v4 (via `@tailwindcss/vite`, imported with\n`@import "tailwindcss";` in `index.css`) and nothing else \u2014 no\ncomponent library. The rules every Clawnify app follows:\n\n- **Neutral chrome.** White canvas and surfaces, one text ramp\n (foreground \u2192 muted \u2192 faint), hairline borders. Color is for\n meaning, not decoration.\n- **One primary CTA per screen.** Blue is reserved for links and\n focus rings; never a second accent.\n- **Status colors are muted pairs** \u2014 never pure-saturated fills.\n- **Style with Tailwind utilities.** Don\'t install another component\n library or write a bespoke CSS system unless the user asks.\n- **Sizes in rem**, so browser zoom and font settings are respected.\n\n## `clawnify.json` \u2014 the manifest\n\n```json\n{\n "$schema": "https://app.clawnify.com/schema/v1/clawnify.json",\n "version": 1,\n "name": "Notes",\n "description": "Take and organize notes. Searchable by tag.",\n "app": {\n "framework": "react+hono",\n "database": true,\n "storage": false\n },\n "env": {\n "optional": ["OPENROUTER_API_KEY"]\n },\n "api": {\n "public_routes": [\n { "path": "/api/feed", "methods": ["GET"] }\n ]\n }\n}\n```\n\n`clawnify init` writes the minimal form:\n`{ app: { framework: "react+hono", database: true, storage } }`. Add\nthe rest as needed.\n\nIf the app talks to third-party services the user has connected\n(ads platforms, CRMs, messaging), declare them:\n\n```json\n{ "app": { "credentials": ["metaads", "googleads"] } }\n```\n\nGet the ids and names from `clawnify connections list` \u2014 see the\nnaming rule below.\n\n`env` supports `required` (deploy warns if missing), `optional`\n(injected when available), and `oneOf` (at least one per group).\n\nRules:\n- **There is no `api.tools[]`.** The manifest\'s `api` object only\n accepts `public_routes` and `automation_bypass`. Your API surface\n is discovered from the generated OpenAPI spec, not a hand-authored\n tools list (see the next section).\n- **Public routes are the exception**, not the default. Every route\n is behind the Clawnify perimeter (auth-required) unless you\n explicitly add a matching path to `api.public_routes`. Use only for\n webhooks, RSS, embedded feeds.\n- **`framework: "react+hono"`** for new apps. Never `preact+hono` or\n `vite-preact` \u2014 those are legacy.\n- **`database: true`** if the app uses a DB. Ship both `schema.ts`\n (typed) and `schema.sql` (the applied DDL), kept in sync.\n\n## How the agent reaches your API (no `api.tools[]`)\n\nThe old tRPC stack emitted an `api.tools[]` array from procedure meta.\nThat mechanism is gone. Today the flow is:\n\n1. Your `createRoute` definitions auto-generate a live OpenAPI 3.0 spec\n plus a lean `/llms.txt` index, both served for you \u2014 never hand-write\n or route them yourself. **These are the agent\'s discovery channel:**\n it calls `call_app_api` with `GET /llms.txt` (index of every\n endpoint) or `GET /api/openapi.json` (full request/response schemas).\n Because both are generated from the live route table, they cannot\n drift from the code.\n2. The agent then drives your endpoints with `call_app_api` (a `method`\n + `path` on the live app). No per-app MCP registration and no\n manifest tools array. Use source reading to *modify* code, not to\n discover endpoints.\n\nSo you make an endpoint "agent-callable" by defining it with\n`createRoute()` + `app.openapi()` and giving it a clear\n`summary`/`description` with Zod-typed request/response. The clearer\nthose are, the more reliably the agent uses it.\n\n### `agent.md` \u2014 lead with the procedure, not the endpoint list\n\n`agent.md` is extracted into `agent_instructions` on every build. Since\ndiscovery is already covered by the generated surfaces above, **`agent.md`\nis not an API reference** \u2014 re-listing every payload there just creates a\nsecond source of truth that goes stale the first time a route changes.\nIt is the one place for what generation can\'t produce: **judgment**.\n\nWrite it in this order:\n\n1. **Division of labour, first and short.** What the agent should do\n itself vs. what it must delegate to the app \u2014 and say the wrong move\n out loud (*"never look up contact details yourself; post the records\n and let the app resolve them"*). This one block prevents more misuse\n than the rest of the file combined.\n2. **The procedure** \u2014 numbered steps for the app\'s main job, written so\n the agent can follow them on a request it has never seen.\n3. **Pages**, flagging the screenshot-friendly ones.\n4. **API anchors, not API docs** \u2014 method, path, and *when to reach for\n it*, plus the one or two request shapes the agent writes most often.\n For anything else, let it read `/llms.txt`.\n5. **How to read failures**, and any **cost discipline** \u2014 which calls\n spend the user\'s money and which are free.\n\n**Don\'t ship a per-app skill.** A skill\'s frontmatter stays resident in\nagent context, so one skill per app grows the agent\'s context floor as\nthe app count grows; `agent_instructions` and `/llms.txt` are pulled on\ndemand instead. Skills are for **cross-app** procedures \u2014 if one earns\nreuse across more than one app, promote that single procedure\n(parameterized) to the shared skills library rather than copying it into\nevery app.\n\n## Connections & secrets \u2014 `@clawnify/connections`\n\n**The naming rule \u2014 never invent an identifier.** Before declaring\n`credentials` or env names, run `clawnify connections list`: it shows\nthe org\'s canonical integration ids (`googleads`, never `google_ads`),\nthe fixed provider-key names (`OPENROUTER_API_KEY`, never\n`OPENROUTER_KEY`), and custom env vars already defined \u2014 each with\nconnected/set state. Reuse those exact identifiers; a misspelled one\ndoesn\'t fail the build, it silently resolves to nothing at runtime. If\nyou need a custom secret that isn\'t listed, pick a clear name and tell\nthe user to set it in the dashboard.\n\nIf the app needs a third-party service or a provider API key, use\nthe `@clawnify/connections` SDK. Never read credential bindings\ndirectly, never paste API keys, never hardcode a token or endpoint.\n\n```ts\nimport { connect, secret, describe, searchActions } from "@clawnify/connections";\n\n// A connected integration:\nconst meta = connect("metaads", env);\nconst accounts = await meta.adAccounts("name,currency");\n\n// A provider key the user supplied (null if absent):\nconst key = secret("OPENROUTER_API_KEY", env);\n\n// What\'s wired vs missing \u2014 drive your setup/empty state from this:\nconst status = await describe(env, undefined, REQUIRES);\n```\n\nHow to call a connected service \u2014 the mistake that silently breaks\nintegration apps, so get it right:\n\n- **Prefer the typed client\'s semantic methods** where they exist\n (`meta.adAccounts(...)`, `googleads.query(gaql)`).\n- **For anything else, discover and run an action:**\n ```ts\n const [best] = await searchActions("list google ads campaigns", env);\n const data = await connect(best.service, env).run(best.slug, body);\n ```\n- Some integrations also expose a raw REST client\n (`connect("bird", env).get("/path")`) \u2014 but if `.get()`/`.post()`\n throws for a service, that service only supports semantic methods\n and `run()`. When unsure, use `run()`.\n- **Need exact paths/arguments for a raw-REST provider?** Some carry\n a `spec_url` (the provider\'s published OpenAPI spec) \u2014\n `clawnify connections list --json` shows it. Download and query it \u2014\n `curl -s <spec_url> -o spec.json && jq \'.paths | keys\' spec.json` \u2014\n never read a whole spec into context (they run to 10+ MB).\n- **Never fall back to raw `fetch`** against a provider API, and\n never invent endpoints or guess tokens.\n\n**The one exception \u2014 a service we don\'t support at all.** If a\nprovider isn\'t in the connections registry (nothing to `connect()`\nto, and `clawnify connections list` doesn\'t show it), the sanctioned\npath *is* a raw call with a user-supplied key: declare the key(s) it\nneeds in `clawnify.json` `env` (`required`/`optional`/`oneOf`), tell\nthe user to set them in the dashboard, read them with\n`secret("THAT_KEY", env)`, and `fetch` the provider\'s documented\nendpoints directly. This is the escape hatch for the long tail of\nintegrations we don\'t model yet \u2014 it does **not** apply to a service\nwe *do* support (use `connect()` / `run()` for those, always). Keep\nthe endpoint and token server-side, never in the client bundle.\n\nBuild a `describe()`-driven setup state instead of assuming\nconnections exist \u2014 show the user what\'s missing and where to\nconnect it.\n\n## Scheduling & deferred work \u2014 the managed queue\n\nA deployed app **cannot bind Cloudflare Queues, Durable Objects, or cron\ntriggers** (the platform builds every app with a fixed binding set: `DB` +\n`ASSETS` + `UPLOADS`). To run work later \u2014 a scheduled publish, a reminder, a\nretry, a "do this in 10 minutes" \u2014 use the **Clawnify managed queue service**\nover HTTP. It owns the clock, retries, and at-least-once delivery, then calls an\nendpoint on *your own app* back at the scheduled time.\n\nIt\'s a thin seam over a platform primitive, same shape as `@clawnify/db` /\n`@clawnify/connections` (a `@clawnify/queue` package is coming; inline the seam\nuntil then). Auth is the build-injected `env.CLAWNIFY_TOKEN`; with no token\n(local dev) the seam degrades to a no-op.\n\n**Enqueue** a deferred call to your own endpoint:\n\n```ts\n// POST https://services.clawnify.com/queue/enqueue (Bearer CLAWNIFY_TOKEN)\nconst res = await fetch("https://services.clawnify.com/queue/enqueue", {\n method: "POST",\n headers: { Authorization: `Bearer ${env.CLAWNIFY_TOKEN}`, "Content-Type": "application/json" },\n body: JSON.stringify({\n target_url: `${origin}/api/internal/publish`, // an endpoint on THIS app\n payload: { post_id: id }, // echoed back to you on fire\n run_at: new Date(whenMs).toISOString(),\n idempotency_key: `post:${id}:${whenMs}`, // same key dedupes; new time = new job\n }),\n});\nconst { job_id } = await res.json(); // store it to cancel/reschedule\n```\n\nPersist `job_id` on the row (e.g. `posts.queue_job_id`). **Cancel / reschedule**:\n`DELETE https://services.clawnify.com/queue/jobs/{job_id}` (Bearer token);\nreschedule = cancel + a fresh enqueue.\n\n**The callback endpoint is a public, signature-verified route.** The queue calls\n`target_url` from outside the perimeter, so the endpoint must be declared in\n`clawnify.json` `public_routes` **and** verify the delivery signature itself \u2014\nthe signature *is* its auth (never trust an unsigned call):\n\n```jsonc\n// clawnify.json\n"api": { "public_routes": [ { "path": "/api/internal/publish", "methods": ["POST"] } ] }\n```\n\nDeliveries are signed with the platform\'s **ECDSA P-256 (ES256)** key,\nStripe-style over `${timestamp}.${rawBody}`, verified against\n`https://services.clawnify.com/.well-known/jwks.json` (public key \u2014 nothing\nbreaks on token rotation). Read the raw body, check the signature + a timestamp\ntolerance (~5 min) before doing anything:\n\n```ts\napp.post("/api/internal/publish", async (c) => {\n const raw = await c.req.text();\n const ok = await verifyDelivery(raw, {\n signature: c.req.header("x-clawnify-signature"),\n timestamp: c.req.header("x-clawnify-timestamp"),\n keyId: c.req.header("x-clawnify-key-id"),\n });\n if (!ok) return c.json({ error: "bad signature" }, 401);\n const { post_id } = JSON.parse(raw);\n // \u2026do the deferred work (short: it\'s one normal Worker invocation)\u2026\n return c.json({ ok: true });\n});\n```\n\nEach fire is a normal Worker request \u2014 size the work to one invocation (publish a\npost, send a digest). For long compute *now* (not deferred), hold the request\nopen and return when done; don\'t fire-and-forget past the response.\n\n## Migrations\n\nKeep `schema.ts` and `schema.sql` in sync by hand. The workflow is:\n\n1. Edit `src/server/schema.ts` for the new shape (types + queries).\n2. Make the matching edit in `src/server/schema.sql` \u2014 a new\n `CREATE TABLE IF NOT EXISTS`, or `ALTER TABLE \u2026 ADD COLUMN \u2026` at the\n **end** of the file for a new column.\n3. Run `clawnify dev` locally, then `clawnify deploy`.\n\nOn deploy your schema changes are applied to the app\'s database \u2014 new\ntables and columns are added automatically.\n\nDestructive changes (drop column, rename) are not applied automatically;\ndo them deliberately, and only when the user explicitly asks. Renames\nare risky on production data \u2014 prefer "add new column, backfill, switch\nqueries, drop old column" over a single-step rename.\n\n## What the agent must NOT do\n\n- Author a `/openapi.json` handler by hand. `app.doc("/api/openapi.json", \u2026)`\n generates it from your `createRoute` definitions.\n- Let `schema.ts` and `schema.sql` drift. They describe the same\n tables \u2014 change both, every time.\n- Hand-author migration SQL files. Make schema changes in `schema.sql`\n (and mirror them in `schema.ts`); the deploy applies them.\n- Invent an `api.tools[]` array in the manifest. It isn\'t a valid\n field \u2014 the OpenAPI spec is the tool surface.\n- Use `JSON.stringify` on query params. JSON columns auto-serialize\n via Drizzle. The raw SQL API has `json()` as a helper.\n- Skip the `org_id` filter on a user-facing query. Multi-tenant\n leak is the worst-class bug we can ship.\n- Read auth from `Authorization` / cookies / `Bearer` tokens, or\n hand-parse `X-Clawnify-*` headers. Use `user(c)` / `orgId(c)` /\n `caller(c)` from `@clawnify/app`.\n- Call third-party APIs with raw `fetch` or hardcoded tokens. Go\n through `@clawnify/connections` (`connect` / `secret` / `run`).\n- Install `drizzle-orm` as a separate top-level dependency.\n `@clawnify/db@^0.4.1` pulls it in transitively; only add it if you\n need to pin a specific version (rare).\n\n## What the agent SHOULD do\n\n- Import everything from `@clawnify/db` where possible\n (`getDB`, `eq`, `and`, `desc`, `sql`, `sqliteTable`, `text`,\n `integer`, `index`, etc. are all re-exported there). Drop to\n `drizzle-orm` directly only for things not re-exported.\n- Give every route a clear `summary`/`description` and Zod-typed\n request/response so the agent can discover and call it via the\n OpenAPI spec.\n- Test on the draft URL (`<slug>.draft.clawnify.com`) before\n publishing \u2014 the preview tier catches schema drift and type errors\n at build time.\n- When unsure about a Drizzle pattern, check the `@clawnify/db`\n README for the current API + version notes.\n\n## Schema-as-data exception\n\nApps that let END users define data shapes at runtime (CMS, no-code\ntable editor) can\'t model their schema in `schema.ts` \u2014 the table\ndefinitions live in rows. Those apps fall back to the raw SQL API\nfrom `@clawnify/db` (`query`, `get`, `run`, `json`). Open-cms is\nthe canonical example.\n\nIf you\'re building this kind of app, you still use Drizzle\'s\n`schema.ts` for the **registry** tables (content types, field\ndefinitions). Only the dynamically-spawned per-collection tables\nneed raw SQL. See open-cms\'s `src/server/schema-sync.ts` for the\nruntime DDL pattern.\n'
|
|
1689
|
+
description: "Author a Clawnify app end-to-end \u2014 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.",
|
|
1690
|
+
content: '# Build a Clawnify app\n\nCanonical skill: how to author a Clawnify app end-to-end. Same content\nfor humans reading the docs and for AI coding agents injecting this as\ninstructions during an app build.\n\nIf you\'re an agent: this document is enough context to produce a\nworking app from scratch. Follow it literally. The patterns here\nare exactly what `clawnify init` scaffolds and what the platform\nexpects.\n\n## TL;DR\n\n- **One stack.** Hono + React + Vite + `@hono/zod-openapi` +\n `@clawnify/db` (Drizzle) + `@clawnify/app` (entry, routing,\n identity) + Tailwind v4. Nothing else.\n- **Schema lives in `schema.ts` alone** \u2014 the Drizzle DSL your queries\n compile against. The DDL is generated from it (`pnpm db:generate` \u2192\n `.clawnify/drizzle/*.sql`); never hand-write a `schema.sql` in a\n scaffolded app.\n- **Queries through `getDB`** \u2014 `import { getDB, eq } from\n "@clawnify/db"`. JSON columns auto-serialize.\n- **API routes are `OpenAPIHono` + `createRoute`** \u2014 Zod-validated\n request/response.\n- **`createApp()`** (from `@clawnify/app`) builds the entry \u2014 it returns an\n `OpenAPIHono` with API discovery already mounted (`/api/openapi.json` +\n `/llms.txt`, generated from your live routes). That descriptor *is* the\n tool surface agents discover. Never hand-write those routes.\n- **One import.** `@clawnify/app` re-exports `createRoute`, `z` and\n `OpenAPIHono`, and adds `user` / `orgId` / `caller`. Import from it, not\n from `@clawnify/routes` directly.\n- **`clawnify.json`** declares framework, env, and public routes.\n There is no `api.tools[]` \u2014 the agent discovers and calls your\n endpoints via `/llms.txt` (and the OpenAPI spec).\n- **Identity is injected by the platform** \u2014 read it with `user(c)` /\n `orgId(c)` / `caller(c)` from `@clawnify/app`. Your app never\n authenticates anyone.\n\n## Stack rationale\n\nOne template, one set of decisions. Don\'t deviate unless the user has\nexplicitly asked. `clawnify init` (type `app`) scaffolds either a\n`blank` template (one GET route + a page) or a `crud` template (a\ntable with list/create/update/delete + a form). Both share the exact\nsame stack below.\n\n## File layout\n\n```\nmy-app/\n clawnify.json \u2190 Manifest (validated against /schema/v1/clawnify.json)\n package.json\n tsconfig.json\n vite.config.ts \u2190 @vitejs/plugin-react + @tailwindcss/vite; proxies /api \u2192 :8787\n index.html\n .gitignore\n .clawnify/ \u2190 Managed by the CLI (gitignored) \u2014 never edit\n wrangler.toml \u2190 Generated wrangler config\n drizzle.config.ts \u2190 Generated drizzle config (from clawnify.json + schema.ts)\n drizzle/ \u2190 Generated migration SQL (applied by dev + deploy)\n applied-migrations.json \u2190 Local-apply tracker\n src/\n server/\n index.ts \u2190 OpenAPIHono entry \u2014 mounts routes, serves /api/openapi.json\n routes.ts \u2190 OpenAPIHono + createRoute definitions \u2014 the API surface\n schema.ts \u2190 Drizzle table definitions \u2014 the single source of truth\n worker-env.d.ts \u2190 Cloudflare Workers types reference\n uploads.ts \u2190 R2 helpers (only when storage is enabled)\n client/\n main.tsx \u2190 React mount point\n app.tsx \u2190 Root component (plain fetch against /api/*)\n index.css \u2190 @import "tailwindcss"\n```\n\n## Schema \u2014 `schema.ts` is the single source of truth\n\n`schema.ts` (Drizzle DSL) defines the tables. Do **not** hand-write a\n`schema.sql` in a scaffolded app, and there is no toolchain config to\nmaintain: the drizzle config is a managed artifact the CLI materializes\ninto `.clawnify/` (from `clawnify.json` + the schema path), and the DDL\nis generated from `schema.ts` into `.clawnify/drizzle/*.sql` \u2014 which is\nwhat `clawnify dev` applies locally and the deploy applies to your D1.\n\nThe scaffold\'s starter table (blank template):\n\n```ts\n// src/server/schema.ts\nimport { sqliteTable, text, integer } from "@clawnify/db";\n\nexport const items = sqliteTable("items", {\n id: integer("id").primaryKey({ autoIncrement: true }),\n name: text("name").notNull(),\n createdAt: text("created_at").notNull().$default(() => new Date().toISOString()),\n});\n```\n\nReal apps are multi-tenant. Every user-facing table carries an\n`org_id`, every query filters by it. JSON columns and indexes use the\nDrizzle DSL re-exported from `@clawnify/db`:\n\n```ts\nimport { sqliteTable, text, integer, index } from "@clawnify/db";\n\nexport const notes = sqliteTable(\n "notes",\n {\n id: integer("id").primaryKey({ autoIncrement: true }),\n orgId: text("org_id").notNull(), // ALWAYS filter by this in queries\n title: text("title").notNull(),\n body: text("body").notNull().default(""),\n tags: text("tags", { mode: "json" }).$type<string[]>().notNull().default([]),\n createdAt: text("created_at").notNull().$default(() => new Date().toISOString()),\n },\n (t) => ({\n byOrg: index("notes_by_org").on(t.orgId, t.createdAt),\n }),\n);\n```\n\nRules:\n- JSON columns: `text(col, { mode: "json" }).$type<T>()` \u2014 Drizzle\n serializes on write and parses on read.\n- Multi-tenancy: every user-facing table has `org_id`. Every query\n filters by it. No exceptions.\n- Identifiers: snake_case in SQL, camelCase in TS (Drizzle bridges).\n\n## Generating the DDL \u2014 automatic, or `clawnify db generate`\n\n`clawnify dev` and `clawnify deploy` (local-directory deploys) generate\nthe migration SQL themselves \u2014 editing `schema.ts` and running dev or\ndeploy is the whole workflow. To refresh the SQL explicitly without\neither, run `npx clawnify@latest db generate` (the scaffold\'s\n`pnpm db:generate` is an alias for it). Always invoke the CLI as\n`npx clawnify@latest` \u2014 never a global or pinned install. Deploy refuses a database-enabled app with no DDL,\nso a broken generate fails loudly, not silently.\n\nOne artifact to leave alone: after a successful signed-in deploy the CLI\nsyncs a read-only `schema.sql` snapshot of the DEPLOYED schema into the\napp root. It is generated output for reference/diffing \u2014 never edit it,\nand never treat it as the source of truth (`schema.ts` is).\n\nRules:\n- Deploys are **additive**: new tables and columns are added\n automatically. Destructive changes (dropping or retyping a column) are\n not applied automatically \u2014 do those deliberately, and never drop a\n table with user data unless explicitly asked.\n- Never edit the generated `.clawnify/drizzle/*.sql` by hand \u2014 change\n `schema.ts` and regenerate.\n- A hand-written `schema.sql` at the app root is accepted **only** for\n apps that don\'t use Drizzle at all (e.g. some template repos). A\n scaffolded app never needs one.\n\n## `src/server/index.ts` \u2014 the entry\n\n```ts\nimport { createApp } from "@clawnify/app";\nimport api from "./routes";\n\ntype Env = { Bindings: { DB: D1Database } };\n\n// db:false \u2014 this app reads the database per request via getDB(c.env),\n// which needs no init middleware.\nconst app = createApp<Env>({ title: "My app", version: "1.0.0", db: false });\n\napp.route("/", api);\n\nexport default app;\n```\n\nThe entry is thin: `createApp()` then mount your routes. `createApp`\nreturns an `OpenAPIHono` with **API discovery already mounted** \u2014 it\nserves both `/api/openapi.json` (generated from your `createRoute`\ndefinitions, with schemas) **and** `/llms.txt` (the same, agent-readable).\nAny `/api/*` route written as a plain `app.get` with no `createRoute` is\nstill listed from the live route table, so the endpoint inventory is\nalways complete. **Never hand-write a `/openapi.json` or `/llms.txt`\nhandler** \u2014 and don\'t call `mountDiscovery` yourself; `createApp` did it.\n\nWhen storage (file uploads) is enabled, the entry also wires the R2\nbucket in a middleware before mounting routes:\n\n```ts\nimport { createApp } from "@clawnify/app";\nimport { initUploads } from "./uploads";\nimport api from "./routes";\n\ntype Env = { Bindings: { DB: D1Database; UPLOADS: R2Bucket } };\n\nconst app = createApp<Env>({ title: "My app", version: "1.0.0", db: false });\n\napp.use("*", async (c, next) => {\n initUploads(c.env.UPLOADS);\n await next();\n});\n\napp.route("/", api);\n\nexport default app;\n```\n\n## `src/server/routes.ts` \u2014 routes with `createRoute`\n\nEach endpoint is a `createRoute({ method, path, summary, request, responses })`\ndefinition paired with a handler via `api.openapi(route, handler)`.\nRequest bodies and params are Zod-validated (`c.req.valid("json")`,\n`c.req.valid("param")`); response shapes are declared with\n`.openapi("Name")` Zod schemas so they land in the generated spec.\n\nBlank template \u2014 one read route:\n\n```ts\nimport { OpenAPIHono, createRoute, z } from "@clawnify/app";\nimport { getDB, desc } from "@clawnify/db";\nimport * as schema from "./schema";\n\ntype Env = { Bindings: { DB: D1Database } };\nconst api = new OpenAPIHono<Env>();\n\nconst ItemSchema = z.object({\n id: z.number(),\n name: z.string(),\n createdAt: z.string(),\n}).openapi("Item");\n\napi.openapi(\n createRoute({\n method: "get",\n path: "/api/items",\n summary: "List items",\n responses: {\n 200: {\n description: "List of items",\n content: { "application/json": { schema: z.array(ItemSchema) } },\n },\n },\n }),\n async (c) => {\n const db = getDB(c.env, { schema });\n const items = await db\n .select()\n .from(schema.items)\n .orderBy(desc(schema.items.createdAt));\n return c.json(items);\n },\n);\n\nexport default api;\n```\n\nCRUD template \u2014 the full list/create/update/delete surface:\n\n```ts\nimport { OpenAPIHono, createRoute, z } from "@clawnify/app";\nimport { getDB, eq, desc } from "@clawnify/db";\nimport * as schema from "./schema";\n\ntype Env = { Bindings: { DB: D1Database } };\nconst api = new OpenAPIHono<Env>();\n\nconst ItemSchema = z.object({\n id: z.number(),\n title: z.string(),\n status: z.string(),\n createdAt: z.string(),\n}).openapi("Item");\n\nconst CreateItemSchema = z.object({ title: z.string().min(1) }).openapi("CreateItem");\nconst UpdateItemSchema = z.object({\n title: z.string().min(1).optional(),\n status: z.string().optional(),\n}).openapi("UpdateItem");\nconst IdParamSchema = z.object({ id: z.string() });\nconst OkSchema = z.object({ ok: z.boolean() }).openapi("Ok");\n\napi.openapi(\n createRoute({\n method: "get",\n path: "/api/items",\n summary: "List items",\n responses: {\n 200: {\n description: "List of items",\n content: { "application/json": { schema: z.array(ItemSchema) } },\n },\n },\n }),\n async (c) => {\n const db = getDB(c.env, { schema });\n const items = await db\n .select()\n .from(schema.items)\n .orderBy(desc(schema.items.createdAt));\n return c.json(items);\n },\n);\n\napi.openapi(\n createRoute({\n method: "post",\n path: "/api/items",\n summary: "Create item",\n request: { body: { content: { "application/json": { schema: CreateItemSchema } } } },\n responses: {\n 201: {\n description: "Created item",\n content: { "application/json": { schema: ItemSchema } },\n },\n },\n }),\n async (c) => {\n const { title } = c.req.valid("json");\n const db = getDB(c.env, { schema });\n const [row] = await db\n .insert(schema.items)\n .values({ title: title.trim() })\n .returning();\n return c.json(row, 201);\n },\n);\n\napi.openapi(\n createRoute({\n method: "patch",\n path: "/api/items/:id",\n summary: "Update item",\n request: {\n params: IdParamSchema,\n body: { content: { "application/json": { schema: UpdateItemSchema } } },\n },\n responses: {\n 200: { description: "Updated", content: { "application/json": { schema: OkSchema } } },\n },\n }),\n async (c) => {\n const { id } = c.req.valid("param");\n const body = c.req.valid("json");\n const patch: Partial<typeof schema.items.$inferInsert> = {};\n if (body.title !== undefined) patch.title = body.title;\n if (body.status !== undefined) patch.status = body.status;\n if (Object.keys(patch).length === 0) return c.json({ ok: false }, 400);\n const db = getDB(c.env, { schema });\n await db.update(schema.items).set(patch).where(eq(schema.items.id, Number(id)));\n return c.json({ ok: true });\n },\n);\n\napi.openapi(\n createRoute({\n method: "delete",\n path: "/api/items/:id",\n summary: "Delete item",\n request: { params: IdParamSchema },\n responses: {\n 200: { description: "Deleted", content: { "application/json": { schema: OkSchema } } },\n },\n }),\n async (c) => {\n const { id } = c.req.valid("param");\n const db = getDB(c.env, { schema });\n await db.delete(schema.items).where(eq(schema.items.id, Number(id)));\n return c.json({ ok: true });\n },\n);\n\nexport default api;\n```\n\nPatterns to follow:\n- **Give every route a clear `summary`/`description`.** The generated\n OpenAPI spec is what the agent reads to decide which endpoint to\n call \u2014 a vague summary makes your endpoint invisible in practice.\n- **Validate input with Zod** via `request.body` / `request.params`\n and read it with `c.req.valid("json")` / `c.req.valid("param")`.\n Never parse `c.req.raw` by hand.\n- **Declare response shapes** with `.openapi("Name")` schemas \u2014 they\n become the documented return type in the spec.\n- **Filter by the org** on every user-facing query (see "who is\n calling" below). No exceptions.\n\n## `src/server` \u2014 who is calling\n\nThe platform authenticates every caller at its perimeter and injects a\nverified identity onto the request (it strips any client-supplied\nversion first, so it can\'t be spoofed). Your app never authenticates\nanyone: no `Authorization`, no cookies, no JWT, no login screen.\n\nRead it with the helpers from `@clawnify/app` \u2014 don\'t parse headers\nyourself:\n\n```ts\nimport { user, orgId, caller } from "@clawnify/app";\n\napp.get("/api/notes", async (c) => {\n const org = orgId(c);\n if (!org) return c.json({ error: "unauthorized" }, 401);\n\n const db = getDB(c.env, { schema });\n return c.json(\n await db.select().from(schema.notes).where(eq(schema.notes.orgId, org)),\n );\n});\n```\n\n| Helper | Returns |\n|--------|---------|\n| `orgId(c)` | Organization UUID \u2014 the tenant key. Filter every user-facing query by it. |\n| `user(c)` | `{ id, email, name, avatarUrl, firstName, lastName }` \u2014 or **`null`** when the caller isn\'t a person. |\n| `caller(c)` | `user`, `api`, `agent`, `agent-browser`, `public`, `bypass`, `system`, or `app`. |\n\nTwo rules that catch people out:\n\n- **`user(c)` is null for five of the eight caller kinds**\n (`agent-browser`, `public`, `bypass`, `system`, `app`). Always handle\n the null case \u2014 don\'t assume a person is present just because a\n request arrived. For per-user rows, store `user(c).id` in a `user_id`\n column and filter on it, exactly as you filter on `org_id`.\n- **`firstName` / `lastName` are a heuristic** split of a single stored\n full name (first word / the rest). Fine for a greeting; never persist\n them or treat them as someone\'s legal name \u2014 store `name`.\n\nDon\'t build app-level users, roles, or permissions. Authorization\nalready happened at the perimeter.\n\n## `src/client` \u2014 React + plain fetch\n\nThe client mounts React and talks to the API with plain `fetch`\nagainst the `/api/*` routes. No data-layer library is scaffolded.\n\n```tsx\n// src/client/main.tsx\nimport { StrictMode } from "react";\nimport { createRoot } from "react-dom/client";\nimport { App } from "./app";\nimport "./index.css";\n\ncreateRoot(document.getElementById("app")!).render(\n <StrictMode>\n <App />\n </StrictMode>\n);\n```\n\n```tsx\n// src/client/app.tsx (CRUD template shape)\nimport { useState, useEffect } from "react";\n\ninterface Item {\n id: number;\n title: string;\n status: string;\n createdAt: string;\n}\n\nexport function App() {\n const [items, setItems] = useState<Item[]>([]);\n const [title, setTitle] = useState("");\n\n async function load() {\n const res = await fetch("/api/items");\n setItems(await res.json());\n }\n\n useEffect(() => { load(); }, []);\n\n async function addItem(e: React.FormEvent) {\n e.preventDefault();\n if (!title.trim()) return;\n await fetch("/api/items", {\n method: "POST",\n headers: { "Content-Type": "application/json" },\n body: JSON.stringify({ title }),\n });\n setTitle("");\n load();\n }\n\n // ...toggleStatus / deleteItem call PATCH/DELETE the same way.\n\n return (\n <div className="max-w-xl mx-auto mt-10 px-4">\n {/* form + list */}\n </div>\n );\n}\n```\n\nIn local dev, Vite proxies `/api` to the Worker on `:8787` (see\n`vite.config.ts`), so the same relative fetch paths work in dev and\nin production. The API is the one contract: the UI calls it over\n`fetch`, and the agent calls it over the OpenAPI spec.\n\n## Design\n\nIf the project contains a `DESIGN.md`, it is the single source of\ntruth for visuals \u2014 follow its tokens, don\'t restyle around it. The\nscaffold ships Tailwind v4 (via `@tailwindcss/vite`, imported with\n`@import "tailwindcss";` in `index.css`) and nothing else \u2014 no\ncomponent library. The rules every Clawnify app follows:\n\n- **Neutral chrome.** White canvas and surfaces, one text ramp\n (foreground \u2192 muted \u2192 faint), hairline borders. Color is for\n meaning, not decoration.\n- **One primary CTA per screen.** Blue is reserved for links and\n focus rings; never a second accent.\n- **Status colors are muted pairs** \u2014 never pure-saturated fills.\n- **Style with Tailwind utilities.** Don\'t install another component\n library or write a bespoke CSS system unless the user asks.\n- **Sizes in rem**, so browser zoom and font settings are respected.\n\n## `clawnify.json` \u2014 the manifest\n\n```json\n{\n "$schema": "https://app.clawnify.com/schema/v1/clawnify.json",\n "version": 1,\n "name": "Notes",\n "description": "Take and organize notes. Searchable by tag.",\n "app": {\n "framework": "react+hono",\n "database": true,\n "storage": false\n },\n "env": {\n "optional": ["OPENROUTER_API_KEY"]\n },\n "api": {\n "public_routes": [\n { "path": "/api/feed", "methods": ["GET"] }\n ]\n }\n}\n```\n\n`clawnify init` writes the minimal form:\n`{ app: { framework: "react+hono", database: true, storage } }`. Add\nthe rest as needed.\n\nIf the app talks to third-party services the user has connected\n(ads platforms, CRMs, messaging), declare them:\n\n```json\n{ "app": { "credentials": ["metaads", "googleads"] } }\n```\n\nGet the ids and names from `clawnify connections list` \u2014 see the\nnaming rule below.\n\n`env` supports `required` (deploy warns if missing), `optional`\n(injected when available), and `oneOf` (at least one per group).\n\nRules:\n- **There is no `api.tools[]`.** The manifest\'s `api` object only\n accepts `public_routes` and `automation_bypass`. Your API surface\n is discovered from the generated OpenAPI spec, not a hand-authored\n tools list (see the next section).\n- **Public routes are the exception**, not the default. Every route\n is behind the Clawnify perimeter (auth-required) unless you\n explicitly add a matching path to `api.public_routes`. Use only for\n webhooks, RSS, embedded feeds.\n- **`framework: "react+hono"`** for new apps. Never `preact+hono` or\n `vite-preact` \u2014 those are legacy.\n- **`database: true`** if the app uses a DB. `schema.ts` defines the\n tables; run `pnpm db:generate` after changing it.\n\n## How the agent reaches your API (no `api.tools[]`)\n\nThe old tRPC stack emitted an `api.tools[]` array from procedure meta.\nThat mechanism is gone. Today the flow is:\n\n1. Your `createRoute` definitions auto-generate a live OpenAPI 3.0 spec\n plus a lean `/llms.txt` index, both served for you \u2014 never hand-write\n or route them yourself. **These are the agent\'s discovery channel:**\n it calls `call_app_api` with `GET /llms.txt` (index of every\n endpoint) or `GET /api/openapi.json` (full request/response schemas).\n Because both are generated from the live route table, they cannot\n drift from the code.\n2. The agent then drives your endpoints with `call_app_api` (a `method`\n + `path` on the live app). No per-app MCP registration and no\n manifest tools array. Use source reading to *modify* code, not to\n discover endpoints.\n\nSo you make an endpoint "agent-callable" by defining it with\n`createRoute()` + `app.openapi()` and giving it a clear\n`summary`/`description` with Zod-typed request/response. The clearer\nthose are, the more reliably the agent uses it.\n\n### `agent.md` \u2014 lead with the procedure, not the endpoint list\n\n`agent.md` is extracted into `agent_instructions` on every build. Since\ndiscovery is already covered by the generated surfaces above, **`agent.md`\nis not an API reference** \u2014 re-listing every payload there just creates a\nsecond source of truth that goes stale the first time a route changes.\nIt is the one place for what generation can\'t produce: **judgment**.\n\nWrite it in this order:\n\n1. **Division of labour, first and short.** What the agent should do\n itself vs. what it must delegate to the app \u2014 and say the wrong move\n out loud (*"never look up contact details yourself; post the records\n and let the app resolve them"*). This one block prevents more misuse\n than the rest of the file combined.\n2. **The procedure** \u2014 numbered steps for the app\'s main job, written so\n the agent can follow them on a request it has never seen.\n3. **Pages**, flagging the screenshot-friendly ones.\n4. **API anchors, not API docs** \u2014 method, path, and *when to reach for\n it*, plus the one or two request shapes the agent writes most often.\n For anything else, let it read `/llms.txt`.\n5. **How to read failures**, and any **cost discipline** \u2014 which calls\n spend the user\'s money and which are free.\n\n**Don\'t ship a per-app skill.** A skill\'s frontmatter stays resident in\nagent context, so one skill per app grows the agent\'s context floor as\nthe app count grows; `agent_instructions` and `/llms.txt` are pulled on\ndemand instead. Skills are for **cross-app** procedures \u2014 if one earns\nreuse across more than one app, promote that single procedure\n(parameterized) to the shared skills library rather than copying it into\nevery app.\n\n## Connections & secrets \u2014 `@clawnify/connections`\n\n**The naming rule \u2014 never invent an identifier.** Before declaring\n`credentials` or env names, run `clawnify connections list`: it shows\nthe org\'s canonical integration ids (`googleads`, never `google_ads`),\nthe fixed provider-key names (`OPENROUTER_API_KEY`, never\n`OPENROUTER_KEY`), and custom env vars already defined \u2014 each with\nconnected/set state. Reuse those exact identifiers; a misspelled one\ndoesn\'t fail the build, it silently resolves to nothing at runtime. If\nyou need a custom secret that isn\'t listed, pick a clear name and tell\nthe user to set it in the dashboard.\n\nIf the app needs a third-party service or a provider API key, use\nthe `@clawnify/connections` SDK. Never read credential bindings\ndirectly, never paste API keys, never hardcode a token or endpoint.\n\n```ts\nimport { connect, secret, describe, searchActions } from "@clawnify/connections";\n\n// A connected integration:\nconst meta = connect("metaads", env);\nconst accounts = await meta.adAccounts("name,currency");\n\n// A provider key the user supplied (null if absent):\nconst key = secret("OPENROUTER_API_KEY", env);\n\n// What\'s wired vs missing \u2014 drive your setup/empty state from this:\nconst status = await describe(env, undefined, REQUIRES);\n```\n\nHow to call a connected service \u2014 the mistake that silently breaks\nintegration apps, so get it right:\n\n- **Prefer the typed client\'s semantic methods** where they exist\n (`meta.adAccounts(...)`, `googleads.query(gaql)`).\n- **For anything else, discover and run an action:**\n ```ts\n const [best] = await searchActions("list google ads campaigns", env);\n const data = await connect(best.service, env).run(best.slug, body);\n ```\n- Some integrations also expose a raw REST client\n (`connect("bird", env).get("/path")`) \u2014 but if `.get()`/`.post()`\n throws for a service, that service only supports semantic methods\n and `run()`. When unsure, use `run()`.\n- **Need exact paths/arguments for a raw-REST provider?** Some carry\n a `spec_url` (the provider\'s published OpenAPI spec) \u2014\n `clawnify connections list --json` shows it. Download and query it \u2014\n `curl -s <spec_url> -o spec.json && jq \'.paths | keys\' spec.json` \u2014\n never read a whole spec into context (they run to 10+ MB).\n- **Never fall back to raw `fetch`** against a provider API, and\n never invent endpoints or guess tokens.\n\n**The one exception \u2014 a service we don\'t support at all.** If a\nprovider isn\'t in the connections registry (nothing to `connect()`\nto, and `clawnify connections list` doesn\'t show it), the sanctioned\npath *is* a raw call with a user-supplied key: declare the key(s) it\nneeds in `clawnify.json` `env` (`required`/`optional`/`oneOf`), tell\nthe user to set them in the dashboard, read them with\n`secret("THAT_KEY", env)`, and `fetch` the provider\'s documented\nendpoints directly. This is the escape hatch for the long tail of\nintegrations we don\'t model yet \u2014 it does **not** apply to a service\nwe *do* support (use `connect()` / `run()` for those, always). Keep\nthe endpoint and token server-side, never in the client bundle.\n\nBuild a `describe()`-driven setup state instead of assuming\nconnections exist \u2014 show the user what\'s missing and where to\nconnect it.\n\n## Scheduling & deferred work \u2014 the managed queue\n\nA deployed app **cannot bind Cloudflare Queues, Durable Objects, or cron\ntriggers** (the platform builds every app with a fixed binding set: `DB` +\n`ASSETS` + `UPLOADS`). To run work later \u2014 a scheduled publish, a reminder, a\nretry, a "do this in 10 minutes" \u2014 use the **Clawnify managed queue service**\nover HTTP. It owns the clock, retries, and at-least-once delivery, then calls an\nendpoint on *your own app* back at the scheduled time.\n\nUse the published `@clawnify/queue` package \u2014 `enqueueJob`, `cancelJob`,\n`verifyDelivery` \u2014 same shape as `@clawnify/db` / `@clawnify/connections`.\nAuth is the build-injected `env.CLAWNIFY_TOKEN`; with no token (local dev)\nit degrades to a no-op.\n\n**Enqueue** a deferred call to your own endpoint:\n\n```ts\n// POST https://services.clawnify.com/queue/enqueue (Bearer CLAWNIFY_TOKEN)\nconst res = await fetch("https://services.clawnify.com/queue/enqueue", {\n method: "POST",\n headers: { Authorization: `Bearer ${env.CLAWNIFY_TOKEN}`, "Content-Type": "application/json" },\n body: JSON.stringify({\n target_url: `${origin}/api/internal/publish`, // an endpoint on THIS app\n payload: { post_id: id }, // echoed back to you on fire\n run_at: new Date(whenMs).toISOString(),\n idempotency_key: `post:${id}:${whenMs}`, // same key dedupes; new time = new job\n }),\n});\nconst { job_id } = await res.json(); // store it to cancel/reschedule\n```\n\nPersist `job_id` on the row (e.g. `posts.queue_job_id`). **Cancel / reschedule**:\n`DELETE https://services.clawnify.com/queue/jobs/{job_id}` (Bearer token);\nreschedule = cancel + a fresh enqueue.\n\n**The callback endpoint is a public, signature-verified route.** The queue calls\n`target_url` from outside the perimeter, so the endpoint must be declared in\n`clawnify.json` `public_routes` **and** verify the delivery signature itself \u2014\nthe signature *is* its auth (never trust an unsigned call):\n\n```jsonc\n// clawnify.json\n"api": { "public_routes": [ { "path": "/api/internal/publish", "methods": ["POST"] } ] }\n```\n\nDeliveries are signed with the platform\'s **ECDSA P-256 (ES256)** key,\nStripe-style over `${timestamp}.${rawBody}`, verified against\n`https://services.clawnify.com/.well-known/jwks.json` (public key \u2014 nothing\nbreaks on token rotation). Read the raw body, check the signature + a timestamp\ntolerance (~5 min) before doing anything:\n\n```ts\napp.post("/api/internal/publish", async (c) => {\n const raw = await c.req.text();\n const ok = await verifyDelivery(raw, {\n signature: c.req.header("x-clawnify-signature"),\n timestamp: c.req.header("x-clawnify-timestamp"),\n keyId: c.req.header("x-clawnify-key-id"),\n });\n if (!ok) return c.json({ error: "bad signature" }, 401);\n const { post_id } = JSON.parse(raw);\n // \u2026do the deferred work (short: it\'s one normal Worker invocation)\u2026\n return c.json({ ok: true });\n});\n```\n\nEach fire is a normal Worker request \u2014 size the work to one invocation (publish a\npost, send a digest). For long compute *now* (not deferred), hold the request\nopen and return when done; don\'t fire-and-forget past the response.\n\n## Migrations\n\nThe workflow is:\n\n1. Edit `src/server/schema.ts` for the new shape (types + queries).\n2. Run `pnpm db:generate` \u2014 emits the migration SQL under\n `.clawnify/drizzle/`.\n3. Run `npx clawnify@latest dev` locally, then `npx clawnify@latest deploy`.\n\nOn deploy your schema changes are applied to the app\'s database \u2014 new\ntables and columns are added automatically.\n\nDestructive changes (drop column, rename) are not applied automatically;\ndo them deliberately, and only when the user explicitly asks. Renames\nare risky on production data \u2014 prefer "add new column, backfill, switch\nqueries, drop old column" over a single-step rename.\n\n## What the agent must NOT do\n\n- Author a `/openapi.json` or `/llms.txt` handler by hand. `createApp()`\n mounts both, generated from your `createRoute` definitions.\n- Hand-write a `schema.sql`, edit anything under `.clawnify/`, or add a\n root `drizzle.config.ts`. Schema changes happen in `schema.ts`; the\n CLI generates and applies the SQL.\n- Invent an `api.tools[]` array in the manifest. It isn\'t a valid\n field \u2014 the OpenAPI spec is the tool surface.\n- Use `JSON.stringify` on query params. JSON columns auto-serialize\n via Drizzle. The raw SQL API has `json()` as a helper.\n- Skip the `org_id` filter on a user-facing query. Multi-tenant\n leak is the worst-class bug we can ship.\n- Read auth from `Authorization` / cookies / `Bearer` tokens, or\n hand-parse `X-Clawnify-*` headers. Use `user(c)` / `orgId(c)` /\n `caller(c)` from `@clawnify/app`.\n- Call third-party APIs with raw `fetch` or hardcoded tokens. Go\n through `@clawnify/connections` (`connect` / `secret` / `run`).\n- Install `drizzle-orm` as a separate top-level dependency.\n `@clawnify/db@^0.4.1` pulls it in transitively; only add it if you\n need to pin a specific version (rare).\n\n## What the agent SHOULD do\n\n- Import everything from `@clawnify/db` where possible\n (`getDB`, `eq`, `and`, `desc`, `sql`, `sqliteTable`, `text`,\n `integer`, `index`, etc. are all re-exported there). Drop to\n `drizzle-orm` directly only for things not re-exported.\n- Give every route a clear `summary`/`description` and Zod-typed\n request/response so the agent can discover and call it via the\n OpenAPI spec.\n- Test locally with `npx clawnify@latest dev` before deploying; deploys go live at\n `https://<slug>.apps.clawnify.com` (the dashboard\'s preview pane shows\n the draft tier).\n- When unsure about a Drizzle pattern, check the `@clawnify/db`\n README for the current API + version notes.\n\n## Schema-as-data exception\n\nApps that let END users define data shapes at runtime (CMS, no-code\ntable editor) can\'t model their schema in `schema.ts` \u2014 the table\ndefinitions live in rows. Those apps fall back to the raw SQL API\nfrom `@clawnify/db` (`query`, `get`, `run`, `json`). Open-cms is\nthe canonical example.\n\nIf you\'re building this kind of app, you still use Drizzle\'s\n`schema.ts` for the **registry** tables (content types, field\ndefinitions). Only the dynamically-spawned per-collection tables\nneed raw SQL. See open-cms\'s `src/server/schema-sync.ts` for the\nruntime DDL pattern.\n'
|
|
1666
1691
|
},
|
|
1667
1692
|
{
|
|
1668
1693
|
name: "build-a-clawnify-website",
|
|
1669
1694
|
description: "Build and ship a Clawnify website \u2014 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.",
|
|
1670
|
-
content: "# Build a Clawnify website\n\nA Clawnify website is an **Astro** project deployed to Cloudflare Workers. One\nsite per organization. You write pages; the platform owns hosting, forms and\nthe publish flow.\n\n```bash\
|
|
1695
|
+
content: "# Build a Clawnify website\n\nA Clawnify website is an **Astro** project deployed to Cloudflare Workers. One\nsite per organization. You write pages; the platform owns hosting, forms and\nthe publish flow.\n\n```bash\nnpx clawnify@latest init --type website --name \"My Site\" website\ncd website && pnpm install && pnpm dev # http://localhost:4321\n```\n\nAlways invoke the CLI as `npx clawnify@latest <command>` \u2014 never a\nglobal or pinned install; stale CLIs miss deploy guards and fixes.\n\n```\nwebsite/\n src/pages/ # one .astro file per route (index.astro \u2192 /)\n src/layouts/ # shared shell: nav, footer, <head>\n src/blocks/ # platform blocks you've adopted (see Forms below)\n public/ # images, favicons \u2014 served as-is from /\n```\n\n## Forms: use the built-in system. Do not build your own.\n\n**This is the single most common mistake.** A site needs a contact or waitlist\nform, and the obvious move is to write a `<form>` and POST it somewhere \u2014 your\nown endpoint, a third-party form service, or the platform's submit URL with the\nwebsite id pasted in. All three are wrong, and the last one looks right enough\nto survive review.\n\nClawnify has a form system. It captures submissions, stores them, can email you,\nand can hand each one to an agent or a flow. You get all of it by using the\n**Forms block** rather than writing a form yourself.\n\n### How it works\n\n- The submit target is **computed at render time** from `WEBSITE_ID` \u2014 a\n variable the platform bakes into your site's Worker \u2014 plus the form's id:\n\n ```astro\n const env = (Astro.locals as { runtime?: { env?: Record<string, string> } })?.runtime?.env;\n const websiteId = env?.WEBSITE_ID ?? \"\";\n const action = websiteId ? `https://provision.clawnify.com/forms/submit/${websiteId}/${formId}` : \"\";\n ```\n\n **Never hardcode the website id.** It is baked per Worker so a site can only\n ever submit to itself \u2014 hardcoding throws that away, and the literal goes\n stale the moment the site is recreated. An empty `action` in local `astro dev`\n is expected: there are no Worker vars locally, so the form simply no-ops.\n\n- The submit script POSTs JSON with `Content-Type: text/plain;charset=UTF-8`.\n That is not a typo \u2014 `text/plain` is CORS-safelisted, so the request needs no\n preflight, which matters because the platform can't know your site's origin in\n advance. The route parses the text body as JSON.\n\n- **Keep the Turnstile widget.** The ingest rejects a submission with no token,\n so a form without the widget fails every time with \"Verification required\".\n The sitekey shipped in the block is public and pairs with the platform's\n secret; the widget will not validate on `localhost`, only on a real hostname.\n\n### Getting the block\n\nSites are seeded with the platform's block library at creation. If yours has\n`src/blocks/Forms/Contact.astro`, import it and go. If it doesn't \u2014 an older\nsite, or one scaffolded bare by the CLI \u2014 copy it in from the website template\nand adapt it.\n\n**The design is yours; the plumbing is not.** Restyle the markup, labels and\nclasses freely. Preserve, exactly:\n\n- the computed `action` (never a prop, never a literal),\n- the Turnstile widget,\n- the `data-clawnify-form` attribute and its submit script,\n- `export const schema`,\n- destructuring only known props \u2014 never splat leftover props onto `<form>`,\n or an injected `action` becomes a way to point your form at someone else.\n\n### Fields\n\nThe stock block collects **name, email and message**. Two ways to go beyond\nthat, and the right one depends on whether your form is registered:\n\n- **Registered forms** (a tree node named `Forms/Contact`) are schema-locked:\n the ingest 422s any field it doesn't expect. Give extra inputs **no `name`\n attribute** and have the submit script fold them into `message`.\n- **Unregistered forms** \u2014 hand-built pages like this one \u2014 are not locked, so\n extra fields post as themselves and are stored verbatim in the payload. Better\n data, but if the site later moves onto the tree renderer, registration will\n start rejecting them. Leave a comment saying so.\n\n### PDF attachments\n\nThe Contact block can collect one PDF per submission (job applications, RFQs).\nOff by default \u2014 enable it with the block's `attachment` prop (and optionally\n`attachmentLabel`), then **publish**: the file field is registered at publish\ntime, and the ingest rejects files on forms that haven't registered one. Rules\nthe platform enforces server-side (don't fight them client-side): PDF only,\nverified by content not by extension, max 10 MB. The submission's payload\ncarries the filename and a download link that only the site's own organization\ncan open \u2014 the file is never on a public URL. When a file is attached the\nsubmit script posts `multipart/form-data` instead of JSON; both are\npreflight-free, and the block already handles the switch.\n\n### Where submissions go\n\nEvery submission is stored and visible in the dashboard. From there it can\nnotify an email address, or fan out to an agent or a flow \u2014 which is how a\nsignup becomes a CRM record or a WhatsApp message without you writing a backend.\nSet the notification address in the dashboard, not in the site.\n\n## Images and assets\n\nPut them in `public/` and reference them with an absolute path (`/img/hero.jpg`).\nThey're served as static files. Pull in real assets at real resolution rather\nthan linking someone else's CDN from your markup.\n\n## Deploying: draft first, then publish\n\n```bash\nnpx clawnify@latest deploy # \u2192 the DRAFT site, visible only to your org\n```\n\nDeploying **never** changes the live site. Going live is a separate, explicit\nstep: review the draft, then **Publish to live** in the dashboard. Tell the user\nthis \u2014 a deploy that \"worked\" but didn't appear on the live site is almost\nalways someone expecting deploy to publish.\n\n## Pinning the org\n\nEvery command resolves which organization it targets, folder-first. In a linked\nfolder you get it for free; otherwise pass `--org`. If you work across several\norganizations, pass `--org` explicitly on anything that writes \u2014 the global\nactive org is shared machine-wide and another session can change it under you.\n"
|
|
1671
1696
|
},
|
|
1672
1697
|
{
|
|
1673
1698
|
name: "use-the-clawnify-cli",
|
|
1674
1699
|
description: "Use the Clawnify CLI end-to-end \u2014 authenticate, scaffold, run locally, deploy apps and websites, link projects, manage orgs, and inspect deployed apps. Use when deploying to Clawnify from a terminal or wiring the CLI into scripts and coding agents.",
|
|
1675
|
-
content: "# Use the Clawnify CLI\n\nCanonical skill: how to drive the `clawnify` CLI. Same content for\nhumans and for AI coding agents operating a terminal.\n\nFor **authoring app code** (stack, schema, tRPC patterns), use the\n`build-a-clawnify-app` skill \u2014 this one covers the tooling around it.\n\n## TL;DR\n\n```bash\nnpm i -g clawnify # or: npx clawnify@latest <command>\nclawnify login # browser sign-in, paste-code fallback\nclawnify init my-app # scaffold an app or website\ncd my-app && clawnify dev\nclawnify deploy # \u2192 https://<slug>.apps.clawnify.com\n```\n\n- **Auth once, org lazily.** `login` only signs you in; the first\n command that needs an organization asks once and remembers it.\n- **A directory links to one app.** `deploy` from a linked directory\n updates that app; `clawnify link <id-or-slug>` adopts an existing one.\n- **Non-interactive flags exist for every prompt** \u2014 use them in\n scripts and CI (`-y`, `--update-existing`, `--create-new`, `--org`).\n\n## Authenticate\n\n```bash\nclawnify login # opens the browser; also prints the sign-in URL\nclawnify whoami # current user, active org (if linked)\n```\n\n`login` works from any browser: if the browser runs on the same\nmachine, sign-in completes automatically; otherwise the page shows a\ncode to paste back at the `Paste code here if prompted >` prompt\n(useful over SSH \u2014 no port forwarding needed).\n\n**Headless / CI / agents \u2014 skip `login` entirely.** Set `CLAWNIFY_TOKEN` (a\nSupabase access token) and it wins over any stored session, reading/writing no\nfiles; `CLAWNIFY_ORG_ID` (or a per-command `--org`) pins the org. This is how a\ncoding agent runs the CLI without a browser.\n\n### Organizations\n\nYou belong to one or more orgs; apps live inside an org.\n\n```bash\nclawnify org list # orgs you belong to (* marks active)\nclawnify org use <slug-or-id> # switch the active org\n```\n\nNo need to pick one up front \u2014 the first org-scoped command prompts\nonce and persists the choice. Any single command can override with\n`--org <slug-or-id>`.\n\n## Create and run locally\n\n```bash\nclawnify init [dir] # interactive: app or website\nclawnify init my-app -y # non-interactive defaults (blank app)\nclawnify init --type app --template crud --name my-app\nclawnify init --type website --name my-site\nclawnify dev [dir] [--port 8787] # local dev server\n```\n\n`init` also installs AI files (rules + skills + MCP config) for any\ncoding agents detected in the project; skip with `--no-ai-files`.\n\n## Deploy\n\n```bash\nclawnify deploy # deploy the current directory\nclawnify deploy path/to/app\nclawnify deploy --from owner/repo # deploy straight from GitHub\nclawnify deploy --from owner/repo --path apps/web # monorepo subdir\nclawnify deploy --dry-run # list files that would upload\n```\n\nFirst deploy creates the app and links the directory (writes a local\nproject file); later deploys update the same app. On a slug conflict\nyou'll be asked \u2014 or decide up front:\n\n```bash\nclawnify deploy -y # reuse/update the existing app\nclawnify deploy --update-existing # same, explicit\nclawnify deploy --create-new # take the suggested new slug\n```\n\nLink an existing deployed app to the current directory instead of\ncreating a new one:\n\n```bash\nclawnify link <app-id-or-slug>\n```\n\n## Inspect and manage deployed apps\n\n```bash\nclawnify ls # list deployed apps in the active org\nclawnify logs <app-id> # build logs\nclawnify open <slug> # open the live app in the browser\nclawnify rm <app-id> # delete an app\nclawnify pull schema --from <app-id-or-slug> # fetch live schema.sql\nclawnify docs [slug] # usage README for an app (org index if omitted)\n```\n\n`pull schema` refuses to clobber local uncommitted changes unless you\npass `--force`.\n\n## Manage agents (the FDE surface)\n\nDrive an org's AI agents from the terminal \u2014 observe them and fix them. See the\n`fix-a-clawnify-agent` skill for the workflow; this is the command list. All\norg-scoped and **repo-independent** (reads live agent state, never a GitHub\nrepo).\n\n**The model \u2014 two levels, and only two.** An org has one or more **agents** (the\nAI employees, e.g. \"Ash\"). Each agent can have **sub-agents**: narrower helpers\nit delegates to. `clawnify agents list` prints both, sub-agents indented under\nthe agent that owns them:\n\n```\nAsh (ready, nbg1)\n id: 7c2f\u2026\n sub-agents:\n \u2514\u2500 research (Research) 4 sessions\n```\n\nAn org normally has exactly one agent, so nothing needs to be selected. When it\nhas several, pass `--agent-id <id>` (the `id:` line above).\n\n```bash\nclawnify agents list # the org's agents, each with its sub-agents\nclawnify agents skills [agent] # what an agent can ACTUALLY run (not just its workspace)\nclawnify sessions --agent <slug> --json # stored sessions + token counters (contextTokens = bloat)\nclawnify sessions history <key> --json # one session's transcript \u2014 where it veered\nclawnify agents pull [dir] --agent <slug> # fetch AGENTS.md + skills/ to edit (flows/ come with main only \u2014 flows belong to the main agent)\nclawnify agents push [dir] # push edits back (additive; next session, no restart)\nclawnify agents grant-skill <s> --to <a> # share a main-authored skill (or --all for every agent)\nclawnify agents create <slug> --yes # new SUB-AGENT (RESTARTS the gateway)\nclawnify env set <KEY> <VALUE> # org custom env \u2014 NON-SECRET only (restarts gateway)\nclawnify connections connect <id> # how to connect an integration (dashboard OAuth; you can't)\nclawnify flows list # the main agent's flows + latest published version\nclawnify flows read <name> # print a flow's draft\nclawnify flows create <name> --file f.json # new draft (validated on save)\nclawnify flows edit <name> # edit the draft ($EDITOR, or --file to replace)\nclawnify flows publish <name> # cut the next numbered live version\n```\n\n**Flows:** runs and triggers use the latest **published** version, so editing a\ndraft doesn't change what's live \u2014 until a flow's first publish, though, the\ndraft *is* what runs. `create`/`edit`/`publish` validate automatically and\nreport per-node errors; fix and re-save. Prefer these verbs over pushing raw\n`flows/*.json` edits (which skip validation and versioning).\n\n**Boundary:** everything above is autonomous *except* the human-auth actions \u2014\nconnecting an integration (OAuth) and handing over a secret/API key. For those,\nexplain the dashboard steps; never fake them. `agents create` / `env set`\nrestart the gateway, so confirm before running them on a busy agent.\n\n**`agents create` makes a NEW sub-agent \u2014 it is never the way to \"find\" an\nexisting one.** If you were looking for an agent and `agents list` didn't show\nit, the answer is that the org doesn't have it, or you're in the wrong org\n(`clawnify org list`). Creating one restarts the gateway and leaves a duplicate\nbehind.\n\n## Connections & env names\n\n```bash\nclawnify connections list # the org's naming catalog (\u25CF connected / \u25CB not)\nclawnify connections connect <id> # how to connect one \u2014 dashboard OAuth; the CLI/agent can't do it for you\n```\n\nLists the active org's integrations (canonical ids + connected state),\nprovider API keys (fixed names + set state), and custom env vars. Read\nit before declaring `credentials` or env names in `clawnify.json` and\nreuse the exact identifiers it shows \u2014 a misspelled id or key name\ndoesn't fail the build, it silently resolves to nothing at runtime.\n\n## Workspaces (one repo, one org's apps)\n\n```bash\nclawnify workspace init [dir] [--org <slug-or-id>]\n```\n\nScaffolds a monorepo bound to an org; apps scaffolded inside land\nunder `apps/` and inherit the org on deploy.\n\n## Wire up coding agents\n\n```bash\nclawnify ai-files install # rules + skills + MCP server in one step\nclawnify skills list # bundled skills\nclawnify skills add <name> # install one into detected agents\nclawnify mcp # stdio MCP bridge (Claude Desktop, etc.)\n```\n\n`ai-files install` detects agent config dirs in the project (Claude\nCode, Cursor, OpenClaw, Codex, Aider) and writes the always-on rules\nblock, installs bundled skills, and adds the Clawnify MCP server to\n`.mcp.json`. Target one agent with `--agent <name>`; undo with\n`clawnify ai-files uninstall`.\n\n## The raw escape hatch\n\n```bash\nclawnify api /agents # any GET\nclawnify api /apps -X POST -d '{\u2026}' # any method + JSON body\n```\n\n`clawnify api <path>` makes an authenticated request to any Clawnify API path \u2014\nsame auth and org scoping as every other command (it can only do what you can).\nUse it for anything the porcelain doesn't wrap; the curated commands stay small\nbecause this is always there.\n\n## Tips\n\n- `npx clawnify@latest <command>` always runs the newest release.\n- Every org-scoped command accepts `--org` \u2014 prefer it in scripts over\n relying on the saved active org.\n- If sign-in ever fails mid-flow, just run `clawnify login` again; it\n is safe to repeat.\n"
|
|
1700
|
+
content: "# Use the Clawnify CLI\n\nCanonical skill: how to drive the `clawnify` CLI. Same content for\nhumans and for AI coding agents operating a terminal.\n\nFor **authoring app code** (stack, schema, route patterns), use the\n`build-a-clawnify-app` skill \u2014 this one covers the tooling around it.\n\n## TL;DR\n\n```bash\nnpx clawnify@latest login # browser sign-in, paste-code fallback\nnpx clawnify@latest init my-app # scaffold an app or website\ncd my-app && npx clawnify@latest dev\nnpx clawnify@latest deploy # \u2192 https://<slug>.apps.clawnify.com\n```\n\n- **Always invoke as `npx clawnify@latest <command>`.** Never install\n globally or pin a version \u2014 the CLI ships guards and self-heals\n continuously, and a stale copy misses them. Reference blocks below\n show bare `clawnify <cmd>` for brevity; run them with the full\n `npx clawnify@latest` form. (Scaffolded apps' package scripts \u2014\n `pnpm dev`, `pnpm deploy` \u2014 already delegate correctly.)\n\n- **Auth once, org lazily.** `login` only signs you in; the first\n command that needs an organization asks once and remembers it.\n- **A directory links to one app.** `deploy` from a linked directory\n updates that app; `clawnify link <id-or-slug>` adopts an existing one.\n- **Non-interactive flags exist for every prompt** \u2014 use them in\n scripts and CI (`-y`, `--update-existing`, `--create-new`, `--org`).\n\n## Authenticate\n\n```bash\nclawnify login # opens the browser; also prints the sign-in URL\nclawnify whoami # current user, active org (if linked)\n```\n\n`login` works from any browser: if the browser runs on the same\nmachine, sign-in completes automatically; otherwise the page shows a\ncode to paste back at the `Paste code here if prompted >` prompt\n(useful over SSH \u2014 no port forwarding needed).\n\n**Headless / CI / agents \u2014 skip `login` entirely.** Set `CLAWNIFY_TOKEN` (a\nSupabase access token) and it wins over any stored session, reading/writing no\nfiles; `CLAWNIFY_ORG_ID` (or a per-command `--org`) pins the org. This is how a\ncoding agent runs the CLI without a browser.\n\n### Organizations\n\nYou belong to one or more orgs; apps live inside an org.\n\n```bash\nclawnify org list # orgs you belong to (* marks active)\nclawnify org use <slug-or-id> # switch the active org\n```\n\nNo need to pick one up front \u2014 the first org-scoped command prompts\nonce and persists the choice. Any single command can override with\n`--org <slug-or-id>`.\n\n## Create and run locally\n\n```bash\nclawnify init [dir] # interactive: app or website\nclawnify init my-app -y # non-interactive defaults (blank app)\nclawnify init --type app --template crud --name my-app\nclawnify init --type website --name my-site\nclawnify dev [dir] [--port 8787] # local dev server\n```\n\n`init` also installs AI files (rules + skills + MCP config) for any\ncoding agents detected in the project; skip with `--no-ai-files`.\n\n## Deploy\n\n```bash\nclawnify deploy # deploy the current directory\nclawnify deploy path/to/app\nclawnify deploy --from owner/repo # deploy straight from GitHub\nclawnify deploy --from owner/repo --path apps/web # monorepo subdir\nclawnify deploy --dry-run # list files that would upload\n```\n\nFirst deploy creates the app and links the directory (writes a local\nproject file); later deploys update the same app. On a slug conflict\nyou'll be asked \u2014 or decide up front:\n\n```bash\nclawnify deploy -y # reuse/update the existing app\nclawnify deploy --update-existing # same, explicit\nclawnify deploy --create-new # take the suggested new slug\n```\n\nLink an existing deployed app to the current directory instead of\ncreating a new one:\n\n```bash\nclawnify link <app-id-or-slug>\n```\n\n## Inspect and manage deployed apps\n\n```bash\nclawnify ls # list deployed apps in the active org\nclawnify logs <app-id> # build logs\nclawnify open <slug> # open the live app in the browser\nclawnify rm <app-id> # delete an app\nclawnify db generate # refresh .clawnify/drizzle/*.sql from schema.ts\nclawnify pull schema --from <app-id-or-slug> # snapshot the DEPLOYED schema to schema.sql (generated; read-only reference)\nclawnify docs [slug] # usage README for an app (org index if omitted)\n```\n\n`pull schema` refuses to clobber local uncommitted changes unless you\npass `--force`.\n\n## Manage agents (the FDE surface)\n\nDrive an org's AI agents from the terminal \u2014 observe them and fix them. See the\n`fix-a-clawnify-agent` skill for the workflow; this is the command list. All\norg-scoped and **repo-independent** (reads live agent state, never a GitHub\nrepo).\n\n**The model \u2014 two levels, and only two.** An org has one or more **agents** (the\nAI employees, e.g. \"Ash\"). Each agent can have **sub-agents**: narrower helpers\nit delegates to. `clawnify agents list` prints both, sub-agents indented under\nthe agent that owns them:\n\n```\nAsh (ready, nbg1)\n id: 7c2f\u2026\n sub-agents:\n \u2514\u2500 research (Research) 4 sessions\n```\n\nAn org normally has exactly one agent, so nothing needs to be selected. When it\nhas several, pass `--agent-id <id>` (the `id:` line above).\n\n```bash\nclawnify agents list # the org's agents, each with its sub-agents\nclawnify agents skills [agent] # what an agent can ACTUALLY run (not just its workspace)\nclawnify sessions --agent <slug> --json # stored sessions + token counters (contextTokens = bloat)\nclawnify sessions history <key> --json # one session's transcript \u2014 where it veered\nclawnify agents pull [dir] --agent <slug> # fetch AGENTS.md + skills/ to edit (flows/ come with main only \u2014 flows belong to the main agent)\nclawnify agents push [dir] # push edits back (additive; next session, no restart)\nclawnify agents grant-skill <s> --to <a> # share a main-authored skill (or --all for every agent)\nclawnify agents create <slug> --yes # new SUB-AGENT (RESTARTS the gateway)\nclawnify env set <KEY> <VALUE> # org custom env \u2014 NON-SECRET only (restarts gateway)\nclawnify connections connect <id> # how to connect an integration (dashboard OAuth; you can't)\nclawnify flows list # the main agent's flows + latest published version\nclawnify flows read <name> # print a flow's draft\nclawnify flows create <name> --file f.json # new draft (validated on save)\nclawnify flows edit <name> # edit the draft ($EDITOR, or --file to replace)\nclawnify flows publish <name> # cut the next numbered live version\n```\n\n**Flows:** runs and triggers use the latest **published** version, so editing a\ndraft doesn't change what's live \u2014 until a flow's first publish, though, the\ndraft *is* what runs. `create`/`edit`/`publish` validate automatically and\nreport per-node errors; fix and re-save. Prefer these verbs over pushing raw\n`flows/*.json` edits (which skip validation and versioning).\n\n**Boundary:** everything above is autonomous *except* the human-auth actions \u2014\nconnecting an integration (OAuth) and handing over a secret/API key. For those,\nexplain the dashboard steps; never fake them. `agents create` / `env set`\nrestart the gateway, so confirm before running them on a busy agent.\n\n**`agents create` makes a NEW sub-agent \u2014 it is never the way to \"find\" an\nexisting one.** If you were looking for an agent and `agents list` didn't show\nit, the answer is that the org doesn't have it, or you're in the wrong org\n(`clawnify org list`). Creating one restarts the gateway and leaves a duplicate\nbehind.\n\n## Connections & env names\n\n```bash\nclawnify connections list # the org's naming catalog (\u25CF connected / \u25CB not)\nclawnify connections connect <id> # how to connect one \u2014 dashboard OAuth; the CLI/agent can't do it for you\n```\n\nLists the active org's integrations (canonical ids + connected state),\nprovider API keys (fixed names + set state), and custom env vars. Read\nit before declaring `credentials` or env names in `clawnify.json` and\nreuse the exact identifiers it shows \u2014 a misspelled id or key name\ndoesn't fail the build, it silently resolves to nothing at runtime.\n\n## Workspaces (one repo, one org's apps)\n\n```bash\nclawnify workspace init [dir] [--org <slug-or-id>]\n```\n\nScaffolds a monorepo bound to an org; apps scaffolded inside land\nunder `apps/` and inherit the org on deploy.\n\n## Wire up coding agents\n\n```bash\nclawnify ai-files install # rules + skills + MCP server in one step\nclawnify skills list # bundled skills\nclawnify skills add <name> # install one into detected agents\nclawnify mcp # stdio MCP bridge (Claude Desktop, etc.)\n```\n\n`ai-files install` detects agent config dirs in the project (Claude\nCode, Cursor, OpenClaw, Codex, Aider) and writes the always-on rules\nblock, installs bundled skills, and adds the Clawnify MCP server to\n`.mcp.json`. Target one agent with `--agent <name>`; undo with\n`clawnify ai-files uninstall`.\n\n## The raw escape hatch\n\n```bash\nclawnify api /agents # any GET\nclawnify api /apps -X POST -d '{\u2026}' # any method + JSON body\n```\n\n`clawnify api <path>` makes an authenticated request to any Clawnify API path \u2014\nsame auth and org scoping as every other command (it can only do what you can).\nUse it for anything the porcelain doesn't wrap; the curated commands stay small\nbecause this is always there.\n\n## Tips\n\n- `npx clawnify@latest <command>` always runs the newest release.\n- Every org-scoped command accepts `--org` \u2014 prefer it in scripts over\n relying on the saved active org.\n- If sign-in ever fails mid-flow, just run `clawnify login` again; it\n is safe to repeat.\n"
|
|
1676
1701
|
},
|
|
1677
1702
|
{
|
|
1678
1703
|
name: "fix-a-clawnify-agent",
|
|
1679
1704
|
description: `Diagnose and fix a Clawnify AI agent that veers off its instructions, ignores specific rules, forgets things, repeats the same mistake, or burns a lot of API credits. Use when someone says their agent (e.g. "Ash") won't follow instructions, keeps going off-path, or is expensive \u2014 read the agent's own sessions, find the real cause, and fix the instructions / sessions / flow instead of patching blind.`,
|
|
1680
|
-
content: "# Fix a misbehaving Clawnify agent\n\nYou are the planner and thinker. The Clawnify agent \u2014 the customer's\nWhatsApp / Telegram / Slack / email \"AI employee\" \u2014 is the executor. When it\nmisbehaves your job is to **read what it actually did, find the real cause, and\nchange the durable inputs.** Not to patch instructions blind, and not to burn\nthe agent's own (expensive) model tokens on trial-and-error.\n\n**Know what you're looking at.** An org has one or more **agents** (the\nemployees). Each may have **sub-agents** \u2014 narrower helpers it delegates to.\n`clawnify agents list` shows both, sub-agents indented under their agent. That\nis the whole hierarchy; there is no other tier to go looking for.\n\nThe person you're helping is often **not** an AI specialist. So: diagnose\nfirst, then **explain the cause in plain language and correct the\nmisconception** before you change anything.\n\n## The one rule: don't debug blind\n\n\"Veers off / ignores instructions\" has **three different causes with three\ndifferent fixes.** You can only tell which one by reading the agent's actual\nsession. Patching instructions without looking is exactly why it \"isn't\nheading in the right direction\" \u2014 and every blind test run costs model tokens.\n\n| Cause | What you'll see in the session | Fix |\n|---|---|---|\n| **1. Session bloat** | Was fine early, degrades over a long-running chat; forgets/repeats; high `contextTokens`; compaction/truncation in the transcript; the rule is simply *absent* from recent context | Scope a **fresh session per task**; reset/retire the bloated one |\n| **2. Instruction patchwork** | The rule *was* in context but a **contradicting or older** rule won, or it's buried in a wall of text | **Restructure** `AGENTS.md` (don't add another patch) |\n| **3. Wrong structure** | A repeatable multi-step task the agent improvises differently each time | Move it to a **flow** (deterministic rails) |\n\nBloat and patchwork also explain most **surprise API costs**: a bloated\nsession re-sends a huge context on *every* turn, and the patch-and-rerun loop\nitself burns tokens. Measure it \u2014 don't guess (Step 1).\n\n## Step 1 \u2014 Observe (read what actually happened)\n\n```bash\nclawnify agents list # the org's agents + their sub-agents \u2014 START HERE\nclawnify sessions # every agent's sessions, newest first\nclawnify sessions --agent ash --json # ash only, with token counters (contextTokens = bloat signal)\nclawnify sessions history <key> --json # the transcript of one run \u2014 where it actually veered\nclawnify agents skills ash # what ash can ACTUALLY run (workspace + shared skills)\n```\n\nLook for, in order:\n- **Which failure mode** (table above): was the instruction *present and\n ignored* (\u2192 patchwork/structure) or *compacted away / absent* (\u2192 bloat)?\n- **`contextTokens`** on the session \u2014 large and growing = bloat.\n- **A missing skill** \u2014 if the instruction says \"use skill X\" but `agents\n skills` doesn't list it, the agent literally can't. The fix is to grant it\n (`clawnify agents grant-skill X --to ash`, or `--all` for every agent) if it's\n already authored in main, else author it first (`agents pull main` \u2192 add\n `skills/X/SKILL.md` \u2192 `agents push`) \u2014 not to reword the instruction. (Note:\n what's in the agent's *workspace* is only part of it \u2014 `agents skills` shows\n the effective set incl. shared managed-root skills.)\n- **Where the tokens go** \u2014 one giant session, or repeated retries after a\n veer? That's your cost answer, from data, not a hypothesis.\n\n> If `clawnify sessions` isn't available yet in this org, fall back: ask the\n> person to describe (or paste) one failing run, and read the current\n> `AGENTS.md` from the org's synced repo. You still diagnose before you fix.\n\n## Step 2 \u2014 Explain, then fix\n\nTell the person, plainly, which of the three it is and why. Then:\n\n**Bloat \u2192** don't reuse one ever-growing chat for the same task. Start a fresh\nsession per task/topic (or `/reset` the runaway one). This fixes the veer\n*and* the cost.\n\n**Patchwork \u2192** rewrite `AGENTS.md`, don't append to it. Structure it: **role\n\u2192 a short list of hard rules up front \u2192 the steps \u2192 one example of right vs\nwrong.** Delete contradictions. A tight, prioritized instruction set is\nfollowed far better than a long patched one.\n\n**Structure \u2192** author a **flow** for the repeatable task: deterministic steps,\neach with a narrow instruction, and the heavy/deterministic parts (fetch data,\nfill a template, render the deck) run *without* the model \u2014 less veer, less cost.\n\nWhere instructions live and how edits land:\n- Edit **`AGENTS.md`** (and `skills/`). Push via the org's **GitHub\n sync repo** (auto-deploys to the agent) or `clawnify deploy`. See the\n `use-the-clawnify-cli` skill for the commands.\n- Edit **flows** with `clawnify flows edit <name>` then `clawnify flows\n publish <name>` \u2014 validated on save; once a flow has a published version,\n runs and triggers keep using it until you publish again (before the first\n publish, the draft is what runs). Raw `flows/*.json` edits via the repo also\n land, but skip validation and versioning.\n- **No gateway restart needed** \u2014 the agent picks up new `AGENTS.md` / skills /\n flows on its **next session**.\n- **Never edit any `CLAWNIFY-*.md`** file (`CLAWNIFY-SOUL/AGENTS/TOOLS.md`) \u2014\n those are platform-owned and Clawnify overwrites them on every sync. Your\n edits there vanish.\n\n## How Clawnify agents actually work (what people get wrong)\n\nPreempt these \u2014 they cause \"I set it up but the agent ignores it\":\n\n- **Adding a document to Knowledge does NOT mean the agent reads it.**\n (1) A doc must be **published by a human** \u2014 an agent \"proposing\" it only\n creates a draft. (2) Once published, the agent only *automatically* sees its\n **title + one-line description** (a capped, ~30-item index); the **actual\n content is fetched only when the agent chooses to search** it\n (`company_knowledge_search`). So if the agent ignores a doc, check: is it\n published? not hidden? still in the index? does its `AGENTS.md` tell it to\n search? \u2014 **re-uploading won't help.** Depth: the `organize-company-knowledge` skill.\n- **Memory** is written by the agent via a tool (`memory_write`) and surfaced\n as an index + per-turn recall \u2014 it is **not** a file/folder you drop notes\n into.\n- **The dashboard \"recurring skill\" cards are manual-click only** \u2014 the\n cron/every/at schedule shown is **not wired to a scheduler.** For real\n scheduled or event-driven work use a **cron job or a flow/webhook**, not a\n recurring-skill card.\n- **Native channels** (WhatsApp/Telegram/Slack) receive messages \"for free\"\n via the allowlist \u2014 there is **no trigger/webhook to set up** for incoming\n messages. (Only Clawnify *integrations* have dashboard triggers.)\n\n## Answering \"would a different agent / a flow help?\"\n\n- **Same agent for the same task \u2192 confusion?** The agent identity isn't the\n problem; a reused, ever-growing **session** is (bloat, above). A second agent\n doesn't fix the mechanism and doubles what you manage. Fresh sessions do.\n- **Would a flow be better?** Yes *if* the task is repeatable and structured \u2014\n it constrains the agent and moves deterministic work off-model (less veer,\n less cost). No if the underlying step instructions are vague \u2014 a flow\n structures, it doesn't clarify.\n\n## Guardrails\n\n- **Diagnose before you change anything.** One transcript read beats five blind\n patches.\n- **Never** edit `CLAWNIFY-*.md` (overwritten) \u2014 edit `AGENTS.md`.\n- **Confirm with the human before anything irreversible or outward-facing:**\n sending messages on the agent's live channels, deleting an agent or app,\n billing/plan changes, rotating credentials. Self-service is not unattended\n autonomy.\n- **Connecting an integration is a hard stop, not a confirm.** If a fix needs a\n Clawnify integration that `clawnify connections list` shows as not connected\n (\u25CB), you *cannot* connect it \u2014 that needs the user's OAuth sign-in in a\n browser. Run `clawnify connections connect <id>` and relay the steps to the\n user; never attempt it yourself or ask for their password.\n- **Never put a secret through `clawnify env set`** \u2014 it exposes the value in\n the command and your context. Secrets and API keys go in the dashboard\n (Settings \u2192 Environment Variables / API Keys); guide the user there. Use\n `env set` only for non-secret config. And remember `agents create` / `env set`\n **restart the gateway** \u2014 confirm with the user before you run them on a live,\n busy agent.\n- **Never run `agents create` to \"find\" an agent.** It creates a *new sub-agent*\n and restarts the gateway. If the agent you expected isn't in `clawnify agents\n list`, you are in the wrong org (`clawnify org list`) or it genuinely doesn't\n exist \u2014 ask. Creating one leaves a duplicate the customer then has to live\n with, and interrupts the real agent while it does.\n- Prefer the **smallest durable fix** (a session habit, a tightened `AGENTS.md`,\n one flow) over more instructions.\n"
|
|
1705
|
+
content: "# Fix a misbehaving Clawnify agent\n\nYou are the planner and thinker. The Clawnify agent \u2014 the customer's\nWhatsApp / Telegram / Slack / email \"AI employee\" \u2014 is the executor. When it\nmisbehaves your job is to **read what it actually did, find the real cause, and\nchange the durable inputs.** Not to patch instructions blind, and not to burn\nthe agent's own (expensive) model tokens on trial-and-error.\n\n**Know what you're looking at.** An org has one or more **agents** (the\nemployees). Each may have **sub-agents** \u2014 narrower helpers it delegates to.\n`clawnify agents list` shows both, sub-agents indented under their agent. That\nis the whole hierarchy; there is no other tier to go looking for.\n\nThe person you're helping is often **not** an AI specialist. So: diagnose\nfirst, then **explain the cause in plain language and correct the\nmisconception** before you change anything.\n\n## The one rule: don't debug blind\n\n\"Veers off / ignores instructions\" has **three different causes with three\ndifferent fixes.** You can only tell which one by reading the agent's actual\nsession. Patching instructions without looking is exactly why it \"isn't\nheading in the right direction\" \u2014 and every blind test run costs model tokens.\n\n| Cause | What you'll see in the session | Fix |\n|---|---|---|\n| **1. Session bloat** | Was fine early, degrades over a long-running chat; forgets/repeats; high `contextTokens`; compaction/truncation in the transcript; the rule is simply *absent* from recent context | Scope a **fresh session per task**; reset/retire the bloated one |\n| **2. Instruction patchwork** | The rule *was* in context but a **contradicting or older** rule won, or it's buried in a wall of text | **Restructure** `AGENTS.md` (don't add another patch) |\n| **3. Wrong structure** | A repeatable multi-step task the agent improvises differently each time | Move it to a **flow** (deterministic rails) |\n\nBloat and patchwork also explain most **surprise API costs**: a bloated\nsession re-sends a huge context on *every* turn, and the patch-and-rerun loop\nitself burns tokens. Measure it \u2014 don't guess (Step 1).\n\n## Step 1 \u2014 Observe (read what actually happened)\n\n```bash\nclawnify agents list # the org's agents + their sub-agents \u2014 START HERE\nclawnify sessions # every agent's sessions, newest first\nclawnify sessions --agent ash --json # ash only, with token counters (contextTokens = bloat signal)\nclawnify sessions history <key> --json # the transcript of one run \u2014 where it actually veered\nclawnify agents skills ash # what ash can ACTUALLY run (workspace + shared skills)\n```\n\nLook for, in order:\n- **Which failure mode** (table above): was the instruction *present and\n ignored* (\u2192 patchwork/structure) or *compacted away / absent* (\u2192 bloat)?\n- **`contextTokens`** on the session \u2014 large and growing = bloat.\n- **A missing skill** \u2014 if the instruction says \"use skill X\" but `agents\n skills` doesn't list it, the agent literally can't. The fix is to grant it\n (`clawnify agents grant-skill X --to ash`, or `--all` for every agent) if it's\n already authored in main, else author it first (`agents pull main` \u2192 add\n `skills/X/SKILL.md` \u2192 `agents push`) \u2014 not to reword the instruction. (Note:\n what's in the agent's *workspace* is only part of it \u2014 `agents skills` shows\n the effective set incl. shared managed-root skills.)\n- **Where the tokens go** \u2014 one giant session, or repeated retries after a\n veer? That's your cost answer, from data, not a hypothesis.\n\n> If `clawnify sessions` isn't available yet in this org, fall back: ask the\n> person to describe (or paste) one failing run, and read the current\n> `AGENTS.md` from the org's synced repo. You still diagnose before you fix.\n\n## Step 2 \u2014 Explain, then fix\n\nTell the person, plainly, which of the three it is and why. Then:\n\n**Bloat \u2192** don't reuse one ever-growing chat for the same task. Start a fresh\nsession per task/topic (or `/reset` the runaway one). This fixes the veer\n*and* the cost.\n\n**Patchwork \u2192** rewrite `AGENTS.md`, don't append to it. Structure it: **role\n\u2192 a short list of hard rules up front \u2192 the steps \u2192 one example of right vs\nwrong.** Delete contradictions. A tight, prioritized instruction set is\nfollowed far better than a long patched one.\n\n**Structure \u2192** author a **flow** for the repeatable task: deterministic steps,\neach with a narrow instruction, and the heavy/deterministic parts (fetch data,\nfill a template, render the deck) run *without* the model \u2014 less veer, less cost.\n\nWhere instructions live and how edits land:\n- Edit **`AGENTS.md`** (and `skills/`). Push via the org's **GitHub\n sync repo** (auto-deploys to the agent) or `npx clawnify@latest deploy`. See the\n `use-the-clawnify-cli` skill for the commands.\n- Edit **flows** with `clawnify flows edit <name>` then `clawnify flows\n publish <name>` \u2014 validated on save; once a flow has a published version,\n runs and triggers keep using it until you publish again (before the first\n publish, the draft is what runs). Raw `flows/*.json` edits via the repo also\n land, but skip validation and versioning.\n- **No gateway restart needed** \u2014 the agent picks up new `AGENTS.md` / skills /\n flows on its **next session**.\n- **Never edit any `CLAWNIFY-*.md`** file (`CLAWNIFY-SOUL/AGENTS/TOOLS.md`) \u2014\n those are platform-owned and Clawnify overwrites them on every sync. Your\n edits there vanish.\n\n## How Clawnify agents actually work (what people get wrong)\n\nPreempt these \u2014 they cause \"I set it up but the agent ignores it\":\n\n- **Adding a document to Knowledge does NOT mean the agent reads it.**\n (1) A doc must be **published by a human** \u2014 an agent \"proposing\" it only\n creates a draft. (2) Once published, the agent only *automatically* sees its\n **title + one-line description** (a capped, ~30-item index); the **actual\n content is fetched only when the agent chooses to search** it\n (`company_knowledge_search`). So if the agent ignores a doc, check: is it\n published? not hidden? still in the index? does its `AGENTS.md` tell it to\n search? \u2014 **re-uploading won't help.** Depth: the `organize-company-knowledge` skill.\n- **Memory** is written by the agent via a tool (`memory_write`) and surfaced\n as an index + per-turn recall \u2014 it is **not** a file/folder you drop notes\n into.\n- **The dashboard \"recurring skill\" cards are manual-click only** \u2014 the\n cron/every/at schedule shown is **not wired to a scheduler.** For real\n scheduled or event-driven work use a **cron job or a flow/webhook**, not a\n recurring-skill card.\n- **Native channels** (WhatsApp/Telegram/Slack) receive messages \"for free\"\n via the allowlist \u2014 there is **no trigger/webhook to set up** for incoming\n messages. (Only Clawnify *integrations* have dashboard triggers.)\n\n## Answering \"would a different agent / a flow help?\"\n\n- **Same agent for the same task \u2192 confusion?** The agent identity isn't the\n problem; a reused, ever-growing **session** is (bloat, above). A second agent\n doesn't fix the mechanism and doubles what you manage. Fresh sessions do.\n- **Would a flow be better?** Yes *if* the task is repeatable and structured \u2014\n it constrains the agent and moves deterministic work off-model (less veer,\n less cost). No if the underlying step instructions are vague \u2014 a flow\n structures, it doesn't clarify.\n\n## Guardrails\n\n- **Diagnose before you change anything.** One transcript read beats five blind\n patches.\n- **Never** edit `CLAWNIFY-*.md` (overwritten) \u2014 edit `AGENTS.md`.\n- **Confirm with the human before anything irreversible or outward-facing:**\n sending messages on the agent's live channels, deleting an agent or app,\n billing/plan changes, rotating credentials. Self-service is not unattended\n autonomy.\n- **Connecting an integration is a hard stop, not a confirm.** If a fix needs a\n Clawnify integration that `clawnify connections list` shows as not connected\n (\u25CB), you *cannot* connect it \u2014 that needs the user's OAuth sign-in in a\n browser. Run `clawnify connections connect <id>` and relay the steps to the\n user; never attempt it yourself or ask for their password.\n- **Never put a secret through `clawnify env set`** \u2014 it exposes the value in\n the command and your context. Secrets and API keys go in the dashboard\n (Settings \u2192 Environment Variables / API Keys); guide the user there. Use\n `env set` only for non-secret config. And remember `agents create` / `env set`\n **restart the gateway** \u2014 confirm with the user before you run them on a live,\n busy agent.\n- **Never run `agents create` to \"find\" an agent.** It creates a *new sub-agent*\n and restarts the gateway. If the agent you expected isn't in `clawnify agents\n list`, you are in the wrong org (`clawnify org list`) or it genuinely doesn't\n exist \u2014 ask. Creating one leaves a duplicate the customer then has to live\n with, and interrupts the real agent while it does.\n- Prefer the **smallest durable fix** (a session habit, a tightened `AGENTS.md`,\n one flow) over more instructions.\n"
|
|
1681
1706
|
}
|
|
1682
1707
|
];
|
|
1683
1708
|
var RULES_BY_KIND = {
|
|
1684
|
-
"app": "You are working inside a **Clawnify app** \u2014 a full-stack project that deploys to\nCloudflare through the Clawnify platform. Follow these rules.\n\n## Stack (fixed \u2014 do not swap)\n\n- **Frontend:** React 19 + Tailwind v4, built with Vite.\n- **API:** Hono (`@hono/zod-openapi`) running on Cloudflare Workers.\n- **Database:** D1 (SQLite at the edge) via `@clawnify/db` (Drizzle).\n\nOne app = one `clawnify.json` manifest at the repo root. Don't introduce other\nframeworks, ORMs, or hosting targets.\n\n## The schema lives in `src/server/schema.ts`\n\n- Define tables with the Drizzle DSL there \u2014 it is the single source of truth.\n- **Never** hand-write SQL migrations or edit a `schema.sql` by hand. `clawnify\n dev` and `clawnify deploy` run `drizzle-kit generate` for you.\n- Every user-facing table needs an `org_id` column, and every query must filter\n by the `
|
|
1709
|
+
"app": "You are working inside a **Clawnify app** \u2014 a full-stack project that deploys to\nCloudflare through the Clawnify platform. Follow these rules.\n\n## Stack (fixed \u2014 do not swap)\n\n- **Frontend:** React 19 + Tailwind v4, built with Vite.\n- **API:** Hono (`@hono/zod-openapi`) running on Cloudflare Workers.\n- **Database:** D1 (SQLite at the edge) via `@clawnify/db` (Drizzle).\n\nOne app = one `clawnify.json` manifest at the repo root. Don't introduce other\nframeworks, ORMs, or hosting targets.\n\n## The schema lives in `src/server/schema.ts`\n\n- Define tables with the Drizzle DSL there \u2014 it is the single source of truth.\n- **Never** hand-write SQL migrations or edit a `schema.sql` by hand. `clawnify\n dev` and `clawnify deploy` run `drizzle-kit generate` for you.\n- Every user-facing table needs an `org_id` column, and every query must filter\n by the org \u2014 read it with `orgId(c)` from `@clawnify/app`. This is how\n multi-tenancy works \u2014 there are no exceptions.\n\n## Identity comes from request headers, never the client\n\nThe platform injects identity the client cannot forge. Read it with\n`user(c)` / `orgId(c)` / `caller(c)` from `@clawnify/app` \u2014 never parse\n`X-Clawnify-*` headers by hand, and never trust a client-supplied user or\norg id.\n\n## Integrations: use `@clawnify/connections`\n\nDon't store per-service API keys or OAuth secrets in the app. Declare what the\napp needs under `app.credentials` in `clawnify.json`, then call\n`connect(service, env)` and `secret(name, env)` from the SDK. Off-platform\n(local dev, scripts), put a `clw_` org service token in `.dev.vars` as\n`CLAWNIFY_TOKEN` \u2014 the SDK then resolves your **real** org connections over HTTP\nwith no per-service secrets.\n\n## Commands\n\n- `clawnify dev` \u2014 local dev server. D1 runs as local SQLite, identical to\n production. Leave it running in a separate terminal so generated types stay\n fresh.\n- `clawnify deploy` \u2014 ships the app live at `https://<slug>.apps.clawnify.com`.\n- Don't invoke raw `wrangler` or `drizzle-kit` \u2014 the CLI wraps them. Editing\n `schema.ts` and running `clawnify dev`/`deploy` is the whole workflow.\n\n## Going deeper\n\nFor the full gold-standard structure \u2014 routing, OpenAPI route definitions,\nclient data-fetching patterns, file uploads \u2014 read the **build-a-clawnify-app**\nskill installed alongside these rules.\n",
|
|
1685
1710
|
"website": "You are working inside a **Clawnify website** \u2014 an Astro site that deploys to\nCloudflare through the Clawnify platform. Follow these rules.\n\n## Stack (fixed \u2014 do not swap)\n\n- **Framework:** Astro 5, `output: \"server\"` with the `@astrojs/cloudflare`\n adapter. Pages render on a Worker, so `Astro.request` and runtime env are\n available; there is no static export step to fight.\n- **Styling:** Tailwind v4 via `@tailwindcss/vite`, entry `src/styles/global.css`.\n\nOne website = one `clawnify.json` manifest at the repo root, with\n`website: { framework: \"astro\" }`. Don't introduce another framework, another\nCSS system, or another hosting target.\n\n## This is a normal Astro project \u2014 author it as one\n\n- Pages are files: `src/pages/index.astro` is `/`, `src/pages/about.astro` is\n `/about`. Dynamic routes use `[slug].astro` the usual way.\n- Shared chrome belongs in `src/layouts/`; reusable markup in\n `src/components/`.\n- A route that fetches per request needs `export const prerender = false`.\n Without it Astro prerenders at build time and your data is frozen at deploy.\n\nThere is no page-tree JSON, no block registry, and no theme token file in this\nproject. Those belong to Clawnify's dashboard-managed website product, which is\na different thing with a different authoring model \u2014 don't go looking for them\nhere, and don't invent them.\n\n## Fetching data on the server\n\nFetch in the frontmatter (it runs on the Worker), not in a client script, unless\nthe data is genuinely user-interactive. Anything you can resolve server-side\nrenders in the first byte and costs the visitor nothing.\n\nGive any response you cache-control a real TTL: `public, max-age=<n>`. Clawnify\nedge-caches declared-public GETs, but only when the response says how long it is\ngood for.\n\n## Commands\n\n- `clawnify dev` \u2014 local dev server, same adapter as production.\n- `clawnify deploy` \u2014 publishes the site and prints its live URL.\n- Don't invoke raw `astro` or `wrangler` \u2014 the CLI wraps them, and it is what\n binds the deploy to your org and site.\n\n## Going deeper\n\nAstro's own docs are the reference for routing, layouts, and content\ncollections \u2014 this is a standard Astro project and nothing about it is\nClawnify-specific except the manifest and the deploy step. For CLI mechanics\n(workspaces, orgs, linking, custom domains) read the **use-the-clawnify-cli**\nskill installed alongside these rules.\n",
|
|
1686
1711
|
"agent": 'You are working inside a **Clawnify agent** project \u2014 the configuration for an\nAI employee that runs on the Clawnify platform. Follow these rules.\n\n## What this project is\n\nOne agent = one `clawnify.json` manifest at the repo root, with\n`agent: { harness: "openclaw" }`. The manifest picks the runtime; everything\nelse here is prose and JSON that shapes behaviour. There is no application\nstack to choose \u2014 no framework, no database, no build.\n\n## The pieces\n\n- **`AGENT.md`** \u2014 the agent\'s primary instructions, its role, tone and\n boundaries, written as prose. This is the file that actually changes how the\n agent behaves; most requests to "change what the agent does" are edits here.\n- **`skills/<name>/`** \u2014 reusable procedures. A `SKILL.md` the agent reads when\n triggered, plus a `skill.json` describing when it runs. Reach for a skill when\n a task recurs with the same shape; don\'t encode one-offs.\n- **`flows/<name>.json`** \u2014 ClawFlow definitions for automations that run on a\n schedule or a trigger rather than in conversation.\n\n## Write instructions, not code\n\nThe most common mistake here is reaching for a script when the answer is a\nclearer sentence in `AGENT.md` or a skill. Prefer changing the instructions.\nAdd a flow only when something must run without a human in the loop.\n\n## Commands\n\n- `clawnify deploy` \u2014 pushes this configuration to the agent.\n- The push is additive on the agent\'s machine: it never deletes files the agent\n authored for itself.\n\n## Going deeper\n\nFor diagnosing an agent that is misbehaving \u2014 instructions not taking effect,\na channel not responding, a skill not firing \u2014 read the **fix-a-clawnify-agent**\nskill installed alongside these rules.\n'
|
|
1687
1712
|
};
|
|
@@ -1702,10 +1727,10 @@ var VERSION_HEADER_RE = /<!--\s*clawnify-skill:\s*([\w-]+)\s+v([\d.]+)\s*-->/;
|
|
|
1702
1727
|
function versionHeader(name) {
|
|
1703
1728
|
return `<!-- clawnify-skill: ${name} v${CLI_VERSION} -->`;
|
|
1704
1729
|
}
|
|
1705
|
-
function readExistingVersion(
|
|
1706
|
-
if (!existsSync2(
|
|
1730
|
+
function readExistingVersion(path12) {
|
|
1731
|
+
if (!existsSync2(path12)) return null;
|
|
1707
1732
|
try {
|
|
1708
|
-
const head = readFileSync(
|
|
1733
|
+
const head = readFileSync(path12, "utf8").slice(0, 500);
|
|
1709
1734
|
const match = head.match(VERSION_HEADER_RE);
|
|
1710
1735
|
return match ? match[2] : null;
|
|
1711
1736
|
} catch {
|
|
@@ -2139,15 +2164,15 @@ async function initCommand(dir, opts) {
|
|
|
2139
2164
|
}
|
|
2140
2165
|
async function initApp(dir, opts) {
|
|
2141
2166
|
const yes = !!opts?.yes;
|
|
2142
|
-
const dirArgName = dir ?
|
|
2167
|
+
const dirArgName = dir ? path5.basename(path5.resolve(dir)) : void 0;
|
|
2143
2168
|
const name = opts?.name || (yes ? dirArgName ?? "my-app" : await ask2("App name: ") || "my-app");
|
|
2144
2169
|
const slug = slugify(name);
|
|
2145
2170
|
let targetDir;
|
|
2146
2171
|
if (dir) {
|
|
2147
|
-
targetDir =
|
|
2172
|
+
targetDir = path5.resolve(dir);
|
|
2148
2173
|
} else {
|
|
2149
2174
|
const ws = findWorkspaceRoot(process.cwd());
|
|
2150
|
-
targetDir = ws ?
|
|
2175
|
+
targetDir = ws ? path5.join(ws.dir, "apps", slug) : path5.resolve(slug);
|
|
2151
2176
|
}
|
|
2152
2177
|
let template;
|
|
2153
2178
|
if (opts?.template) {
|
|
@@ -2163,12 +2188,12 @@ async function initApp(dir, opts) {
|
|
|
2163
2188
|
const templateChoice = await ask2("Template [1]: ") || "1";
|
|
2164
2189
|
template = templateChoice === "2" ? "crud" : "blank";
|
|
2165
2190
|
}
|
|
2166
|
-
if (
|
|
2191
|
+
if (fs5.existsSync(targetDir) && fs5.readdirSync(targetDir).length > 0) {
|
|
2167
2192
|
console.error(`Directory ${targetDir} is not empty.`);
|
|
2168
2193
|
process.exit(1);
|
|
2169
2194
|
}
|
|
2170
|
-
|
|
2171
|
-
|
|
2195
|
+
fs5.mkdirSync(path5.join(targetDir, "src/server"), { recursive: true });
|
|
2196
|
+
fs5.mkdirSync(path5.join(targetDir, "src/client"), { recursive: true });
|
|
2172
2197
|
let storage;
|
|
2173
2198
|
if (opts?.storage !== void 0) {
|
|
2174
2199
|
storage = opts.storage;
|
|
@@ -2193,7 +2218,10 @@ async function initApp(dir, opts) {
|
|
|
2193
2218
|
"@types/react": "^19.0.0",
|
|
2194
2219
|
"@types/react-dom": "^19.0.0",
|
|
2195
2220
|
"@vitejs/plugin-react": "^4.0.0",
|
|
2196
|
-
|
|
2221
|
+
// Floor must be a PUBLISHED version at scaffold time — an unpublished
|
|
2222
|
+
// pin fails the whole install (and with it drizzle-kit, vite, …).
|
|
2223
|
+
// Caret picks up newer releases automatically.
|
|
2224
|
+
clawnify: "^0.16.1",
|
|
2197
2225
|
"drizzle-kit": "^0.31.0",
|
|
2198
2226
|
tailwindcss: "^4.0.0",
|
|
2199
2227
|
// `vite build` only transpiles — it never typechecks — so without this the
|
|
@@ -2212,7 +2240,9 @@ async function initApp(dir, opts) {
|
|
|
2212
2240
|
// Referenced by the generated schema.ts comment and the starter UI, and
|
|
2213
2241
|
// run implicitly by `clawnify deploy`. It must exist as a script or
|
|
2214
2242
|
// following the app's own instructions fails with "Missing script".
|
|
2215
|
-
|
|
2243
|
+
// Delegates to the CLI, which materializes the managed drizzle config
|
|
2244
|
+
// in .clawnify/ before invoking drizzle-kit (lib/drizzle.ts).
|
|
2245
|
+
"db:generate": "clawnify db generate",
|
|
2216
2246
|
typecheck: "tsc --noEmit",
|
|
2217
2247
|
deploy: "clawnify deploy"
|
|
2218
2248
|
},
|
|
@@ -2306,14 +2336,6 @@ export const items = sqliteTable("items", {
|
|
|
2306
2336
|
name: text("name").notNull(),
|
|
2307
2337
|
createdAt: text("created_at").notNull().$default(() => new Date().toISOString()),
|
|
2308
2338
|
});
|
|
2309
|
-
`);
|
|
2310
|
-
write(targetDir, "drizzle.config.ts", `import { defineConfig } from "drizzle-kit";
|
|
2311
|
-
|
|
2312
|
-
export default defineConfig({
|
|
2313
|
-
schema: "./src/server/schema.ts",
|
|
2314
|
-
out: "./.clawnify/drizzle",
|
|
2315
|
-
dialect: "sqlite",
|
|
2316
|
-
});
|
|
2317
2339
|
`);
|
|
2318
2340
|
if (storage) {
|
|
2319
2341
|
write(targetDir, "src/server/index.ts", `import { createApp } from "@clawnify/app";
|
|
@@ -2469,10 +2491,10 @@ createRoot(document.getElementById("app")!).render(
|
|
|
2469
2491
|
}
|
|
2470
2492
|
const pm = detectPackageManager();
|
|
2471
2493
|
console.log();
|
|
2472
|
-
console.log(` Created ${name} in ${
|
|
2494
|
+
console.log(` Created ${name} in ${path5.relative(process.cwd(), targetDir)}/`);
|
|
2473
2495
|
console.log();
|
|
2474
2496
|
console.log(" Get started:");
|
|
2475
|
-
console.log(` cd ${
|
|
2497
|
+
console.log(` cd ${path5.relative(process.cwd(), targetDir)}`);
|
|
2476
2498
|
console.log(` ${pm} install`);
|
|
2477
2499
|
console.log(` ${pm} ${pm === "npm" ? "run " : ""}dev # local dev at http://localhost:5173`);
|
|
2478
2500
|
console.log(` ${pm} ${pm === "npm" ? "run " : ""}deploy # deploy to production`);
|
|
@@ -2483,21 +2505,21 @@ async function initWebsite(dir, opts) {
|
|
|
2483
2505
|
const slug = slugify(name);
|
|
2484
2506
|
let targetDir;
|
|
2485
2507
|
if (dir) {
|
|
2486
|
-
targetDir =
|
|
2508
|
+
targetDir = path5.resolve(dir);
|
|
2487
2509
|
} else {
|
|
2488
2510
|
const ws = findWorkspaceRoot(process.cwd());
|
|
2489
|
-
targetDir = ws ?
|
|
2511
|
+
targetDir = ws ? path5.join(ws.dir, "website") : path5.resolve(slug);
|
|
2490
2512
|
}
|
|
2491
|
-
if (
|
|
2492
|
-
const entries =
|
|
2513
|
+
if (fs5.existsSync(targetDir)) {
|
|
2514
|
+
const entries = fs5.readdirSync(targetDir);
|
|
2493
2515
|
const onlyGitkeep = entries.length === 1 && entries[0] === ".gitkeep";
|
|
2494
2516
|
if (entries.length > 0 && !onlyGitkeep) {
|
|
2495
2517
|
console.error(`Directory ${targetDir} is not empty.`);
|
|
2496
2518
|
process.exit(1);
|
|
2497
2519
|
}
|
|
2498
|
-
if (onlyGitkeep)
|
|
2520
|
+
if (onlyGitkeep) fs5.rmSync(path5.join(targetDir, ".gitkeep"));
|
|
2499
2521
|
}
|
|
2500
|
-
|
|
2522
|
+
fs5.mkdirSync(targetDir, { recursive: true });
|
|
2501
2523
|
write(targetDir, "clawnify.json", JSON.stringify({
|
|
2502
2524
|
$schema: "https://app.clawnify.com/schema/v1/clawnify.json",
|
|
2503
2525
|
version: 1,
|
|
@@ -2607,10 +2629,10 @@ import BaseLayout from "../layouts/BaseLayout.astro";
|
|
|
2607
2629
|
</BaseLayout>
|
|
2608
2630
|
`);
|
|
2609
2631
|
console.log();
|
|
2610
|
-
console.log(` Created ${name} in ${
|
|
2632
|
+
console.log(` Created ${name} in ${path5.relative(process.cwd(), targetDir)}/`);
|
|
2611
2633
|
console.log();
|
|
2612
2634
|
console.log(" Get started:");
|
|
2613
|
-
console.log(` cd ${
|
|
2635
|
+
console.log(` cd ${path5.relative(process.cwd(), targetDir)}`);
|
|
2614
2636
|
console.log(" pnpm install");
|
|
2615
2637
|
console.log(" pnpm dev # local dev at http://localhost:4321");
|
|
2616
2638
|
console.log(" pnpm deploy # deploy as your org's website");
|
|
@@ -2618,17 +2640,17 @@ import BaseLayout from "../layouts/BaseLayout.astro";
|
|
|
2618
2640
|
}
|
|
2619
2641
|
async function initAgent(dir, opts) {
|
|
2620
2642
|
const yes = !!opts?.yes;
|
|
2621
|
-
const dirArgName = dir ?
|
|
2643
|
+
const dirArgName = dir ? path5.basename(path5.resolve(dir)) : void 0;
|
|
2622
2644
|
const name = opts?.name || (yes ? dirArgName ?? "my-agent" : await ask2("Agent name: ") || "my-agent");
|
|
2623
2645
|
const slug = slugify(name);
|
|
2624
2646
|
let targetDir;
|
|
2625
2647
|
if (dir) {
|
|
2626
|
-
targetDir =
|
|
2648
|
+
targetDir = path5.resolve(dir);
|
|
2627
2649
|
} else {
|
|
2628
2650
|
const ws = findWorkspaceRoot(process.cwd());
|
|
2629
|
-
targetDir = ws ?
|
|
2651
|
+
targetDir = ws ? path5.join(ws.dir, "agents", slug) : path5.resolve(slug);
|
|
2630
2652
|
}
|
|
2631
|
-
if (
|
|
2653
|
+
if (fs5.existsSync(targetDir) && fs5.readdirSync(targetDir).length > 0) {
|
|
2632
2654
|
console.error(`Directory ${targetDir} is not empty.`);
|
|
2633
2655
|
process.exit(1);
|
|
2634
2656
|
}
|
|
@@ -2668,7 +2690,7 @@ memories/
|
|
|
2668
2690
|
sessions/
|
|
2669
2691
|
logs/
|
|
2670
2692
|
`);
|
|
2671
|
-
const rel =
|
|
2693
|
+
const rel = path5.relative(process.cwd(), targetDir) || ".";
|
|
2672
2694
|
console.log();
|
|
2673
2695
|
console.log(` Created agent ${name} in ${rel}/`);
|
|
2674
2696
|
console.log();
|
|
@@ -2980,14 +3002,14 @@ export function App() {
|
|
|
2980
3002
|
`);
|
|
2981
3003
|
}
|
|
2982
3004
|
function write(dir, file, content) {
|
|
2983
|
-
const fullPath =
|
|
2984
|
-
|
|
2985
|
-
|
|
3005
|
+
const fullPath = path5.join(dir, file);
|
|
3006
|
+
fs5.mkdirSync(path5.dirname(fullPath), { recursive: true });
|
|
3007
|
+
fs5.writeFileSync(fullPath, content);
|
|
2986
3008
|
}
|
|
2987
3009
|
|
|
2988
3010
|
// src/commands/dev.ts
|
|
2989
|
-
import
|
|
2990
|
-
import
|
|
3011
|
+
import fs6 from "fs";
|
|
3012
|
+
import path6 from "path";
|
|
2991
3013
|
import { spawn as spawn2 } from "child_process";
|
|
2992
3014
|
function slugify2(name) {
|
|
2993
3015
|
return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 30);
|
|
@@ -3032,7 +3054,7 @@ function assertNodeVersion2() {
|
|
|
3032
3054
|
}
|
|
3033
3055
|
async function devCommand(dir, options) {
|
|
3034
3056
|
assertNodeVersion2();
|
|
3035
|
-
const resolvedDir = dir ?
|
|
3057
|
+
const resolvedDir = dir ? path6.resolve(dir) : process.cwd();
|
|
3036
3058
|
const manifest = readManifest(resolvedDir);
|
|
3037
3059
|
if (!manifest) {
|
|
3038
3060
|
console.error("No clawnify.json found. Run `clawnify init` first.");
|
|
@@ -3048,21 +3070,20 @@ async function devCommand(dir, options) {
|
|
|
3048
3070
|
const database = manifest.app.database !== false;
|
|
3049
3071
|
const storage = manifest.app.storage === true;
|
|
3050
3072
|
const apiPort = options?.port || "8787";
|
|
3051
|
-
const clawnifyDir =
|
|
3052
|
-
|
|
3053
|
-
const wranglerPath =
|
|
3054
|
-
|
|
3073
|
+
const clawnifyDir = path6.join(resolvedDir, ".clawnify");
|
|
3074
|
+
fs6.mkdirSync(clawnifyDir, { recursive: true });
|
|
3075
|
+
const wranglerPath = path6.join(clawnifyDir, "wrangler.toml");
|
|
3076
|
+
fs6.writeFileSync(wranglerPath, generateWranglerToml(slug, { database, storage }));
|
|
3055
3077
|
if (database) {
|
|
3056
|
-
const
|
|
3057
|
-
|
|
3058
|
-
|
|
3059
|
-
await syncDrizzleToLocalD1(resolvedDir, clawnifyDir, slug, wranglerPath);
|
|
3078
|
+
const drizzleConfigPath = ensureDrizzleConfig(resolvedDir);
|
|
3079
|
+
if (drizzleConfigPath) {
|
|
3080
|
+
await syncDrizzleToLocalD1(resolvedDir, clawnifyDir, slug, wranglerPath, drizzleConfigPath);
|
|
3060
3081
|
} else {
|
|
3061
3082
|
const schemaCandidates = [
|
|
3062
|
-
|
|
3063
|
-
|
|
3083
|
+
path6.join(resolvedDir, "schema.sql"),
|
|
3084
|
+
path6.join(resolvedDir, "src/server/schema.sql")
|
|
3064
3085
|
];
|
|
3065
|
-
const schemaPath = schemaCandidates.find((p) =>
|
|
3086
|
+
const schemaPath = schemaCandidates.find((p) => fs6.existsSync(p));
|
|
3066
3087
|
if (schemaPath) {
|
|
3067
3088
|
await runQuiet(resolvedDir, "npx", [
|
|
3068
3089
|
"wrangler",
|
|
@@ -3164,9 +3185,9 @@ function runQuiet(cwd, cmd, args) {
|
|
|
3164
3185
|
});
|
|
3165
3186
|
});
|
|
3166
3187
|
}
|
|
3167
|
-
async function syncDrizzleToLocalD1(resolvedDir, clawnifyDir, slug, wranglerPath) {
|
|
3188
|
+
async function syncDrizzleToLocalD1(resolvedDir, clawnifyDir, slug, wranglerPath, drizzleConfigPath) {
|
|
3168
3189
|
try {
|
|
3169
|
-
await runQuiet(resolvedDir, "npx", ["drizzle-kit", "generate"]);
|
|
3190
|
+
await runQuiet(resolvedDir, "npx", ["drizzle-kit", "generate", `--config=${drizzleConfigPath}`]);
|
|
3170
3191
|
} catch (err) {
|
|
3171
3192
|
console.error(
|
|
3172
3193
|
` drizzle-kit generate failed. Is \`drizzle-kit\` in devDependencies?
|
|
@@ -3174,15 +3195,15 @@ async function syncDrizzleToLocalD1(resolvedDir, clawnifyDir, slug, wranglerPath
|
|
|
3174
3195
|
);
|
|
3175
3196
|
throw err;
|
|
3176
3197
|
}
|
|
3177
|
-
const drizzleDir =
|
|
3178
|
-
if (!
|
|
3179
|
-
const sqlFiles =
|
|
3198
|
+
const drizzleDir = path6.join(clawnifyDir, "drizzle");
|
|
3199
|
+
if (!fs6.existsSync(drizzleDir)) return;
|
|
3200
|
+
const sqlFiles = fs6.readdirSync(drizzleDir).filter((name) => name.endsWith(".sql")).sort();
|
|
3180
3201
|
if (sqlFiles.length === 0) return;
|
|
3181
|
-
const appliedPath =
|
|
3202
|
+
const appliedPath = path6.join(clawnifyDir, "applied-migrations.json");
|
|
3182
3203
|
let applied = [];
|
|
3183
|
-
if (
|
|
3204
|
+
if (fs6.existsSync(appliedPath)) {
|
|
3184
3205
|
try {
|
|
3185
|
-
applied = JSON.parse(
|
|
3206
|
+
applied = JSON.parse(fs6.readFileSync(appliedPath, "utf8"));
|
|
3186
3207
|
if (!Array.isArray(applied)) applied = [];
|
|
3187
3208
|
} catch {
|
|
3188
3209
|
applied = [];
|
|
@@ -3191,7 +3212,7 @@ async function syncDrizzleToLocalD1(resolvedDir, clawnifyDir, slug, wranglerPath
|
|
|
3191
3212
|
const appliedSet = new Set(applied);
|
|
3192
3213
|
for (const file of sqlFiles) {
|
|
3193
3214
|
if (appliedSet.has(file)) continue;
|
|
3194
|
-
const filePath =
|
|
3215
|
+
const filePath = path6.join(drizzleDir, file);
|
|
3195
3216
|
await runQuiet(resolvedDir, "npx", [
|
|
3196
3217
|
"wrangler",
|
|
3197
3218
|
"d1",
|
|
@@ -3203,11 +3224,39 @@ async function syncDrizzleToLocalD1(resolvedDir, clawnifyDir, slug, wranglerPath
|
|
|
3203
3224
|
]);
|
|
3204
3225
|
applied.push(file);
|
|
3205
3226
|
}
|
|
3206
|
-
|
|
3227
|
+
fs6.writeFileSync(appliedPath, JSON.stringify(applied, null, 2) + "\n");
|
|
3228
|
+
}
|
|
3229
|
+
|
|
3230
|
+
// src/commands/db.ts
|
|
3231
|
+
import path7 from "path";
|
|
3232
|
+
import { spawn as spawn3 } from "child_process";
|
|
3233
|
+
async function dbGenerateCommand(dir) {
|
|
3234
|
+
const resolvedDir = dir ? path7.resolve(dir) : process.cwd();
|
|
3235
|
+
const configPath = ensureDrizzleConfig(resolvedDir);
|
|
3236
|
+
if (!configPath) {
|
|
3237
|
+
console.error(
|
|
3238
|
+
"No src/server/schema.ts here \u2014 nothing to generate.\n Drizzle apps define tables in src/server/schema.ts; apps without a\n database don't need this command."
|
|
3239
|
+
);
|
|
3240
|
+
process.exit(1);
|
|
3241
|
+
}
|
|
3242
|
+
const code = await new Promise((resolve) => {
|
|
3243
|
+
const proc = spawn3("npx", ["drizzle-kit", "generate", `--config=${configPath}`], {
|
|
3244
|
+
cwd: resolvedDir,
|
|
3245
|
+
stdio: "inherit",
|
|
3246
|
+
env: { ...process.env }
|
|
3247
|
+
});
|
|
3248
|
+
proc.on("exit", (c) => resolve(c ?? 1));
|
|
3249
|
+
proc.on("error", (err) => {
|
|
3250
|
+
console.error(`Could not run drizzle-kit: ${String(err).slice(0, 160)}`);
|
|
3251
|
+
resolve(1);
|
|
3252
|
+
});
|
|
3253
|
+
});
|
|
3254
|
+
if (code !== 0) process.exit(code);
|
|
3255
|
+
console.log(" \u2713 Migrations in .clawnify/drizzle/ (applied on the next dev/deploy)");
|
|
3207
3256
|
}
|
|
3208
3257
|
|
|
3209
3258
|
// src/commands/link.ts
|
|
3210
|
-
import
|
|
3259
|
+
import path8 from "path";
|
|
3211
3260
|
var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
3212
3261
|
async function findByAppId(orgs, appId) {
|
|
3213
3262
|
for (const org of orgs) {
|
|
@@ -3246,7 +3295,7 @@ async function findBySlug(orgs, slug) {
|
|
|
3246
3295
|
return null;
|
|
3247
3296
|
}
|
|
3248
3297
|
async function linkCommand(appIdOrSlug, options) {
|
|
3249
|
-
const dir = options?.dir ?
|
|
3298
|
+
const dir = options?.dir ? path8.resolve(options.dir) : process.cwd();
|
|
3250
3299
|
const orgs = await listMyOrgs();
|
|
3251
3300
|
if (orgs.length === 0) {
|
|
3252
3301
|
console.error("No organizations found. Run `clawnify login` first.");
|
|
@@ -3275,14 +3324,14 @@ async function linkCommand(appIdOrSlug, options) {
|
|
|
3275
3324
|
slug: matched.app.slug,
|
|
3276
3325
|
app_token: matched.app.app_token
|
|
3277
3326
|
});
|
|
3278
|
-
const rel =
|
|
3327
|
+
const rel = path8.relative(process.cwd(), dir) || ".";
|
|
3279
3328
|
console.log(` Linked ${matched.app.name} (${matched.app.slug}) in ${matched.org.name}`);
|
|
3280
3329
|
console.log(` Wrote ${rel}/.clawnify/project.json`);
|
|
3281
3330
|
console.log(` Run \`clawnify deploy\` to push the current source to this app.`);
|
|
3282
3331
|
}
|
|
3283
3332
|
|
|
3284
3333
|
// src/commands/pull.ts
|
|
3285
|
-
import
|
|
3334
|
+
import path9 from "path";
|
|
3286
3335
|
async function pullSchemaCommand(options) {
|
|
3287
3336
|
if (!options.from) {
|
|
3288
3337
|
console.error("Usage: clawnify pull schema --from <app-id-or-slug>");
|
|
@@ -3300,9 +3349,9 @@ async function pullSchemaCommand(options) {
|
|
|
3300
3349
|
console.error(`Failed to fetch schema: ${err.message}`);
|
|
3301
3350
|
process.exit(1);
|
|
3302
3351
|
}
|
|
3303
|
-
const targetPath =
|
|
3352
|
+
const targetPath = path9.resolve(options.out ?? "schema.sql");
|
|
3304
3353
|
const result = await writeSchema(targetPath, schema, { force: options.force });
|
|
3305
|
-
const rel =
|
|
3354
|
+
const rel = path9.relative(process.cwd(), result.path) || result.path;
|
|
3306
3355
|
switch (result.status) {
|
|
3307
3356
|
case "no-schema":
|
|
3308
3357
|
console.log(` ${ref.slug}: no schema.sql in R2 (pre-backfill app, or no database)`);
|
|
@@ -3464,8 +3513,8 @@ async function connectionsConnectCommand(id, opts) {
|
|
|
3464
3513
|
}
|
|
3465
3514
|
|
|
3466
3515
|
// src/commands/workspace.ts
|
|
3467
|
-
import
|
|
3468
|
-
import
|
|
3516
|
+
import fs7 from "fs";
|
|
3517
|
+
import path10 from "path";
|
|
3469
3518
|
function slugify3(name) {
|
|
3470
3519
|
return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 30);
|
|
3471
3520
|
}
|
|
@@ -3496,15 +3545,15 @@ async function resolveOrg(opts) {
|
|
|
3496
3545
|
process.exit(1);
|
|
3497
3546
|
}
|
|
3498
3547
|
function write2(dir, file, content) {
|
|
3499
|
-
const fullPath =
|
|
3500
|
-
|
|
3501
|
-
|
|
3548
|
+
const fullPath = path10.join(dir, file);
|
|
3549
|
+
fs7.mkdirSync(path10.dirname(fullPath), { recursive: true });
|
|
3550
|
+
fs7.writeFileSync(fullPath, content);
|
|
3502
3551
|
}
|
|
3503
3552
|
async function workspaceInitCommand(dir, opts) {
|
|
3504
3553
|
const org = await resolveOrg(opts);
|
|
3505
3554
|
const name = opts?.name || org.name;
|
|
3506
|
-
const targetDir = dir ?
|
|
3507
|
-
if (
|
|
3555
|
+
const targetDir = dir ? path10.resolve(dir) : path10.resolve(slugify3(org.slug));
|
|
3556
|
+
if (fs7.existsSync(targetDir) && fs7.readdirSync(targetDir).length > 0) {
|
|
3508
3557
|
console.error(`Directory ${targetDir} is not empty.`);
|
|
3509
3558
|
process.exit(1);
|
|
3510
3559
|
}
|
|
@@ -3575,7 +3624,7 @@ back under the same subdirs. See \`docs/internal/adr-company-monorepo.md\` \xA7
|
|
|
3575
3624
|
write2(targetDir, "apps/.gitkeep", "");
|
|
3576
3625
|
write2(targetDir, "agents/.gitkeep", "");
|
|
3577
3626
|
write2(targetDir, "website/.gitkeep", "");
|
|
3578
|
-
const rel =
|
|
3627
|
+
const rel = path10.relative(process.cwd(), targetDir) || ".";
|
|
3579
3628
|
console.log();
|
|
3580
3629
|
console.log(` Created workspace for ${org.name} (${org.slug}) in ${rel}/`);
|
|
3581
3630
|
console.log();
|
|
@@ -3770,7 +3819,7 @@ async function workspaceConnectCommand(opts) {
|
|
|
3770
3819
|
}
|
|
3771
3820
|
|
|
3772
3821
|
// src/commands/execute.ts
|
|
3773
|
-
import
|
|
3822
|
+
import fs8 from "fs";
|
|
3774
3823
|
|
|
3775
3824
|
// src/lib/mcp-client.ts
|
|
3776
3825
|
var MCP_URL = "https://mcp.clawnify.com/mcp";
|
|
@@ -3820,7 +3869,7 @@ async function executeCommand(file, options) {
|
|
|
3820
3869
|
code = options.code;
|
|
3821
3870
|
} else if (file) {
|
|
3822
3871
|
try {
|
|
3823
|
-
code =
|
|
3872
|
+
code = fs8.readFileSync(file, "utf-8");
|
|
3824
3873
|
} catch (err) {
|
|
3825
3874
|
process.stderr.write(`Failed to read ${file}: ${String(err)}
|
|
3826
3875
|
`);
|
|
@@ -3875,8 +3924,8 @@ async function docsCommand(slug, options) {
|
|
|
3875
3924
|
process.exit(1);
|
|
3876
3925
|
}
|
|
3877
3926
|
const caller = options.caller ?? "external";
|
|
3878
|
-
const
|
|
3879
|
-
const res = await fetch(DOCS_URL +
|
|
3927
|
+
const path12 = slug ? `/docs/${orgId}/${slug}.md?caller=${caller}` : `/docs/${orgId}/index.md`;
|
|
3928
|
+
const res = await fetch(DOCS_URL + path12, {
|
|
3880
3929
|
headers: {
|
|
3881
3930
|
authorization: "Bearer " + token
|
|
3882
3931
|
}
|
|
@@ -4070,17 +4119,17 @@ Valid: ${ALL_AGENTS.join(", ")}`
|
|
|
4070
4119
|
|
|
4071
4120
|
// src/commands/flows.ts
|
|
4072
4121
|
import { spawnSync } from "child_process";
|
|
4073
|
-
import
|
|
4122
|
+
import fs9 from "fs";
|
|
4074
4123
|
import os from "os";
|
|
4075
|
-
import
|
|
4124
|
+
import path11 from "path";
|
|
4076
4125
|
function flowFileName(name) {
|
|
4077
4126
|
return name.endsWith(".json") ? name : `${name}.json`;
|
|
4078
4127
|
}
|
|
4079
4128
|
function parseFlowFile(file) {
|
|
4080
|
-
const abs =
|
|
4129
|
+
const abs = path11.resolve(file);
|
|
4081
4130
|
let raw;
|
|
4082
4131
|
try {
|
|
4083
|
-
raw =
|
|
4132
|
+
raw = fs9.readFileSync(abs, "utf8");
|
|
4084
4133
|
} catch {
|
|
4085
4134
|
console.error(`Cannot read ${abs}.`);
|
|
4086
4135
|
process.exit(1);
|
|
@@ -4187,18 +4236,18 @@ async function flowsEditCommand(name, opts) {
|
|
|
4187
4236
|
} else {
|
|
4188
4237
|
const res = await api.get(`/servers/${serverId}/flows?name=${encodeURIComponent(flowFileName(name))}`);
|
|
4189
4238
|
const { flow: current } = await res.json();
|
|
4190
|
-
tmpDir =
|
|
4191
|
-
tmpFile =
|
|
4192
|
-
|
|
4239
|
+
tmpDir = fs9.mkdtempSync(path11.join(os.tmpdir(), "clawnify-flow-"));
|
|
4240
|
+
tmpFile = path11.join(tmpDir, flowFileName(name));
|
|
4241
|
+
fs9.writeFileSync(tmpFile, JSON.stringify(current, null, 2) + "\n");
|
|
4193
4242
|
const editor = process.env.VISUAL || process.env.EDITOR || "vi";
|
|
4194
4243
|
const result = spawnSync(`${editor} "${tmpFile}"`, { shell: true, stdio: "inherit" });
|
|
4195
4244
|
if (result.status !== 0) {
|
|
4196
4245
|
console.error(`Editor exited without saving \u2014 draft unchanged (kept at ${tmpFile}).`);
|
|
4197
4246
|
process.exit(1);
|
|
4198
4247
|
}
|
|
4199
|
-
const edited =
|
|
4248
|
+
const edited = fs9.readFileSync(tmpFile, "utf8");
|
|
4200
4249
|
if (edited === JSON.stringify(current, null, 2) + "\n") {
|
|
4201
|
-
|
|
4250
|
+
fs9.rmSync(tmpDir, { recursive: true, force: true });
|
|
4202
4251
|
console.log("No changes.");
|
|
4203
4252
|
return;
|
|
4204
4253
|
}
|
|
@@ -4215,7 +4264,7 @@ async function flowsEditCommand(name, opts) {
|
|
|
4215
4264
|
flow,
|
|
4216
4265
|
tmpFile ? `Draft unchanged \u2014 your edits are kept at ${tmpFile}; fix and re-save with: clawnify flows edit ${name} --file "${tmpFile}"` : void 0
|
|
4217
4266
|
);
|
|
4218
|
-
if (tmpDir)
|
|
4267
|
+
if (tmpDir) fs9.rmSync(tmpDir, { recursive: true, force: true });
|
|
4219
4268
|
console.log(
|
|
4220
4269
|
existing.published != null ? `Saved draft "${name}". Runs and triggers keep using v${existing.published} \u2014 publish to make this live: clawnify flows publish ${name}` : `Saved draft "${name}". This flow has no published version, so runs and triggers execute the draft as-is \u2014 cut v1 with: clawnify flows publish ${name}`
|
|
4221
4270
|
);
|
|
@@ -4258,6 +4307,8 @@ async function runCli() {
|
|
|
4258
4307
|
});
|
|
4259
4308
|
program.command("init [dir]").description("Scaffold a new Clawnify project (app, website, or agent)").option("--type <type>", "Project type: app, website, or agent (skips prompt)").option("--name <name>", "Project name (skips prompt)").option("--template <template>", "App template: blank or crud (apps only)").option("--storage", "Enable file uploads (R2) \u2014 apps only").option("-y, --yes", "Non-interactive: use all defaults (app, blank, no storage)").option("--no-ai-files", "Skip installing AI files (rules + skills + MCP) after scaffolding").action(initCommand);
|
|
4260
4309
|
program.command("dev [dir]").description("Start local dev server").option("--port <port>", "API server port (default: 8787)").action(devCommand);
|
|
4310
|
+
const db = program.command("db").description("Database schema tooling");
|
|
4311
|
+
db.command("generate [dir]").description("Generate migration SQL from src/server/schema.ts (dev/deploy run this automatically)").action(dbGenerateCommand);
|
|
4261
4312
|
program.command("login").description("Authenticate with Clawnify").action(loginCommand);
|
|
4262
4313
|
program.command("deploy [dir]").description("Deploy an app, website, or agent to Clawnify").option("--from <repo>", "Deploy from a GitHub repo (owner/repo)").addOption(
|
|
4263
4314
|
new Option(
|
|
@@ -4330,4 +4381,4 @@ async function runCli() {
|
|
|
4330
4381
|
export {
|
|
4331
4382
|
runCli
|
|
4332
4383
|
};
|
|
4333
|
-
//# sourceMappingURL=cli-
|
|
4384
|
+
//# sourceMappingURL=cli-6BGQXGSP.js.map
|