@flisk-sh/flisk 1.4.6 → 1.4.7

package/cli/dist-bundle/{cold-preflight-KUWOL2Q2.js → cold-preflight-DQVJUGBB.js}

@@ -1,2 +1,2 @@
 import{createRequire as __fliskRequire}from'node:module';const require=__fliskRequire(import.meta.url);
-import{L as a,M as b,N as c,O as d,P as e,Q as f,R as g,S as h,T as i,U as j,V as k,W as l}from"./chunk-GT76VMUL.js";import"./chunk-MUDE4DZD.js";import"./chunk-IDNES5PE.js";import"./chunk-GPUJ55MI.js";import"./chunk-3J6XI3NX.js";import"./chunk-BIVAAWBX.js";import"./chunk-WCGBVETR.js";import"./chunk-CAEMWNPF.js";import"./chunk-ETXZ5LUG.js";import"./chunk-C4UFBXRD.js";import"./chunk-KJZUBHLO.js";export{d as MACHINE_CHECK_IDS,a as NATIVE_CHECK_IDS,b as RUNTIME_CHECK_IDS,c as SCAFFOLD_CHECK_IDS,j as assertMachineReadyOrExit,k as detectRuntimePrerequisites,i as formatColdPreflight,l as formatRuntimeNextSteps,e as nodeTooOld,f as requireVerifiedDockerVersions,h as runColdPreflight,g as usesPrisma};
+import{N as a,O as b,P as c,Q as d,R as e,S as f,T as g,U as h,V as i,W as j,X as k,Y as l}from"./chunk-MFY7RZ76.js";import"./chunk-MYAYJF4Q.js";import"./chunk-T44DEEL6.js";import"./chunk-GPUJ55MI.js";import"./chunk-3J6XI3NX.js";import"./chunk-VYPB7MY5.js";import"./chunk-XHENT4KO.js";import"./chunk-YTBTCAWY.js";import"./chunk-L6O7TT3K.js";import"./chunk-TIPSERWO.js";import"./chunk-KJZUBHLO.js";export{d as MACHINE_CHECK_IDS,a as NATIVE_CHECK_IDS,b as RUNTIME_CHECK_IDS,c as SCAFFOLD_CHECK_IDS,j as assertMachineReadyOrExit,k as detectRuntimePrerequisites,i as formatColdPreflight,l as formatRuntimeNextSteps,e as nodeTooOld,f as requireVerifiedDockerVersions,h as runColdPreflight,g as usesPrisma};

package/cli/dist-bundle/{demo-stage-QCC4IWXR.js → demo-stage-F4YA7UL2.js}

@@ -1,5 +1,5 @@
 import{createRequire as __fliskRequire}from'node:module';const require=__fliskRequire(import.meta.url);
-import{b as R}from"./chunk-DPQK5TIS.js";import{b as c}from"./chunk-C4UFBXRD.js";import"./chunk-KJZUBHLO.js";var v=12,_=24,F={plain:e=>e,bold:c.bold,dim:c.gray,ok:c.green,warn:c.yellow,err:c.red},S={pending:"\u25CB",active:"\u25D0",done:"\u2714",failed:"\u2716"},j={pending:"dim",active:"warn",done:"ok",failed:"err"};function o(e){return R(String(e)).replace(/[\n\r\t]/g," ")}function g(e){if(!Number.isFinite(e)||e<0)return"0.0s";if(e<1e4)return`${(e/1e3).toFixed(1)}s`;if(e<6e4)return`${Math.round(e/1e3)}s`;let n=Math.floor(e/6e4),i=Math.round(e%6e4/1e3);return`${n}m ${i}s`}function $(e){return e.reduce((n,i)=>n+i.text.length,0)}function k(e,n){if(n<=0)return[];let i=[],l=0;for(let s of e){if(l>=n)break;let t=n-l;if(s.text.length<=t){i.push(s),l+=s.text.length;continue}i.push({...s,text:`${s.text.slice(0,Math.max(0,t-1))}\u2026`}),l=n}return i}function w(e,n){let i=k(e,n),l=n-$(i);return l<=0?i:[...i,{text:" ".repeat(l),style:"plain"}]}function M(e,n,i){let l=$(n),s=i-l-1;if(s<4)return w(k([...e,...n],i),i);let t=k(e,s),r=i-$(t)-l;return[...t,{text:" ".repeat(Math.max(1,r)),style:"plain"},...n]}function b(e){return[{text:` ${"\u2500".repeat(Math.max(0,e-2))}`,style:"dim"}]}function P(e,n){return M([{text:" ",style:"plain"},{text:S[e.status],style:j[e.status]},{text:"  ",style:"plain"},{text:o(e.label),style:e.status==="pending"?"dim":"plain"}],e.elapsedMs===void 0?[]:[{text:g(e.elapsedMs),style:"dim"}],n)}function Y(e){let n=Math.max(0,e.servicesTotal);if(n===0)return"no services found";let l=[`${Math.min(Math.max(0,e.servicesReady),n)} of ${n} services ready`];return e.servicesBuilding>0&&l.push(`${e.servicesBuilding} building`),l.join(" \xB7 ")}function E(e,n=80){let i=Number.isFinite(n)&&n>0?n:80,l=Math.max(_,Math.min(i-1,78)),s=[],t=a=>s.push(w(a,l)),r=()=>t([]);if(e.done){t(M([{text:" ",style:"plain"},{text:"\u2714",style:"ok"},{text:"  Your stack is running",style:"ok"}],[{text:g(e.elapsedMs),style:"dim"}],l)),t([{text:" ",style:"plain"},{text:o(e.subtitle),style:"dim"}]),r();for(let a of e.done.urls.slice(0,2))t([{text:"     ",style:"plain"},{text:o(a),style:"plain"}]);r(),t(b(l)),t([{text:" ",style:"plain"},{text:o(e.done.summary),style:"plain"}]),t([{text:" ",style:"plain"},{text:o(e.done.hint),style:"dim"}]),r(),t([{text:" ",style:"plain"},{text:`flisk ${o(e.done.version)}`,style:"dim"}])}else if(e.failure){let a=e.phases.find(p=>p.status==="failed");t(M([{text:" ",style:"plain"},{text:"\u2716",style:"err"},{text:"  ",style:"plain"},{text:o(a?.label??"The demo stopped"),style:"err"}],[{text:g(e.elapsedMs),style:"dim"}],l)),r(),t([{text:" ",style:"plain"},{text:o(e.failure.message),style:"plain"}]),e.failure.fix&&t([{text:" ",style:"plain"},{text:o(e.failure.fix),style:"dim"}]),r(),t(b(l)),e.detail&&t([{text:" ",style:"plain"},{text:o(e.detail),style:"dim"}]),e.failure.logPath&&t([{text:" ",style:"plain"},{text:`log: ${o(e.failure.logPath)}`,style:"dim"}])}else{t([{text:" ",style:"plain"},{text:o(e.title),style:"bold"}]),t([{text:" ",style:"plain"},{text:o(e.subtitle),style:"dim"}]),r();let a=e.phases.slice(0,4);for(let p of a)t(P(p,l));for(let p=a.length;p<4;p+=1)r();r(),t(b(l)),t([{text:" ",style:"plain"},{text:o(e.detail??""),style:"dim"}]),t(M([{text:" ",style:"plain"},{text:Y(e),style:"plain"}],[{text:g(e.elapsedMs),style:"dim"}],l))}for(;s.length<v;)s.push(w([],l));return s.slice(0,v)}function A(e){return e.map(n=>n.map(i=>i.text).join(""))}function D(e){return e.map(n=>F[n.style](n.text)).join("")}function H(e,n=process.stderr,i=Date.now){let l=n.isTTY===!0,s=i(),t={...e},r=!1,a="",p="",f,T=()=>{let u=!!(t.done||t.failure);return{...t,elapsedMs:u?t.elapsedMs:i()-s}},x=()=>{let u=T(),m=E(u,n.columns??80),y=A(m);if(!l){let h=y.join(`
+import{b as R}from"./chunk-P7GZ6NGM.js";import{b as c}from"./chunk-TIPSERWO.js";import"./chunk-KJZUBHLO.js";var v=12,_=24,F={plain:e=>e,bold:c.bold,dim:c.gray,ok:c.green,warn:c.yellow,err:c.red},S={pending:"\u25CB",active:"\u25D0",done:"\u2714",failed:"\u2716"},j={pending:"dim",active:"warn",done:"ok",failed:"err"};function o(e){return R(String(e)).replace(/[\n\r\t]/g," ")}function g(e){if(!Number.isFinite(e)||e<0)return"0.0s";if(e<1e4)return`${(e/1e3).toFixed(1)}s`;if(e<6e4)return`${Math.round(e/1e3)}s`;let n=Math.floor(e/6e4),i=Math.round(e%6e4/1e3);return`${n}m ${i}s`}function $(e){return e.reduce((n,i)=>n+i.text.length,0)}function k(e,n){if(n<=0)return[];let i=[],l=0;for(let s of e){if(l>=n)break;let t=n-l;if(s.text.length<=t){i.push(s),l+=s.text.length;continue}i.push({...s,text:`${s.text.slice(0,Math.max(0,t-1))}\u2026`}),l=n}return i}function w(e,n){let i=k(e,n),l=n-$(i);return l<=0?i:[...i,{text:" ".repeat(l),style:"plain"}]}function M(e,n,i){let l=$(n),s=i-l-1;if(s<4)return w(k([...e,...n],i),i);let t=k(e,s),r=i-$(t)-l;return[...t,{text:" ".repeat(Math.max(1,r)),style:"plain"},...n]}function b(e){return[{text:` ${"\u2500".repeat(Math.max(0,e-2))}`,style:"dim"}]}function P(e,n){return M([{text:" ",style:"plain"},{text:S[e.status],style:j[e.status]},{text:"  ",style:"plain"},{text:o(e.label),style:e.status==="pending"?"dim":"plain"}],e.elapsedMs===void 0?[]:[{text:g(e.elapsedMs),style:"dim"}],n)}function Y(e){let n=Math.max(0,e.servicesTotal);if(n===0)return"no services found";let l=[`${Math.min(Math.max(0,e.servicesReady),n)} of ${n} services ready`];return e.servicesBuilding>0&&l.push(`${e.servicesBuilding} building`),l.join(" \xB7 ")}function E(e,n=80){let i=Number.isFinite(n)&&n>0?n:80,l=Math.max(_,Math.min(i-1,78)),s=[],t=a=>s.push(w(a,l)),r=()=>t([]);if(e.done){t(M([{text:" ",style:"plain"},{text:"\u2714",style:"ok"},{text:"  Your stack is running",style:"ok"}],[{text:g(e.elapsedMs),style:"dim"}],l)),t([{text:" ",style:"plain"},{text:o(e.subtitle),style:"dim"}]),r();for(let a of e.done.urls.slice(0,2))t([{text:"     ",style:"plain"},{text:o(a),style:"plain"}]);r(),t(b(l)),t([{text:" ",style:"plain"},{text:o(e.done.summary),style:"plain"}]),t([{text:" ",style:"plain"},{text:o(e.done.hint),style:"dim"}]),r(),t([{text:" ",style:"plain"},{text:`flisk ${o(e.done.version)}`,style:"dim"}])}else if(e.failure){let a=e.phases.find(p=>p.status==="failed");t(M([{text:" ",style:"plain"},{text:"\u2716",style:"err"},{text:"  ",style:"plain"},{text:o(a?.label??"The demo stopped"),style:"err"}],[{text:g(e.elapsedMs),style:"dim"}],l)),r(),t([{text:" ",style:"plain"},{text:o(e.failure.message),style:"plain"}]),e.failure.fix&&t([{text:" ",style:"plain"},{text:o(e.failure.fix),style:"dim"}]),r(),t(b(l)),e.detail&&t([{text:" ",style:"plain"},{text:o(e.detail),style:"dim"}]),e.failure.logPath&&t([{text:" ",style:"plain"},{text:`log: ${o(e.failure.logPath)}`,style:"dim"}])}else{t([{text:" ",style:"plain"},{text:o(e.title),style:"bold"}]),t([{text:" ",style:"plain"},{text:o(e.subtitle),style:"dim"}]),r();let a=e.phases.slice(0,4);for(let p of a)t(P(p,l));for(let p=a.length;p<4;p+=1)r();r(),t(b(l)),t([{text:" ",style:"plain"},{text:o(e.detail??""),style:"dim"}]),t(M([{text:" ",style:"plain"},{text:Y(e),style:"plain"}],[{text:g(e.elapsedMs),style:"dim"}],l))}for(;s.length<v;)s.push(w([],l));return s.slice(0,v)}function A(e){return e.map(n=>n.map(i=>i.text).join(""))}function D(e){return e.map(n=>F[n.style](n.text)).join("")}function H(e,n=process.stderr,i=Date.now){let l=n.isTTY===!0,s=i(),t={...e},r=!1,a="",p="",f,T=()=>{let u=!!(t.done||t.failure);return{...t,elapsedMs:u?t.elapsedMs:i()-s}},x=()=>{let u=T(),m=E(u,n.columns??80),y=A(m);if(!l){let h=y.join(`
 `);if(h===p)return;p=h,n.write(`${y.filter(L=>L.trim()!=="").join(`
 `)}
 `);return}let d=y.join(`

package/cli/dist-bundle/{open-AZNX4AC5.js → open-ZUSSVPD3.js}

@@ -1,2 +1,2 @@
 import{createRequire as __fliskRequire}from'node:module';const require=__fliskRequire(import.meta.url);
-import{d as a,e as b,f as c,g as d,h as e,i as f}from"./chunk-U5FCQF42.js";import"./chunk-MINZ25AC.js";import"./chunk-BIVAAWBX.js";import"./chunk-WCGBVETR.js";import"./chunk-CAEMWNPF.js";import"./chunk-ETXZ5LUG.js";import"./chunk-C4UFBXRD.js";import"./chunk-KJZUBHLO.js";export{d as findReadyFrontend,b as isFrontendReady,a as listFrontendTargets,f as openCommand,e as openFirstFrontend,c as pickReadyFrontend};
+import{d as a,e as b,f as c,g as d,h as e,i as f}from"./chunk-6OW2GVQV.js";import"./chunk-MINZ25AC.js";import"./chunk-VYPB7MY5.js";import"./chunk-XHENT4KO.js";import"./chunk-YTBTCAWY.js";import"./chunk-L6O7TT3K.js";import"./chunk-TIPSERWO.js";import"./chunk-KJZUBHLO.js";export{d as findReadyFrontend,b as isFrontendReady,a as listFrontendTargets,f as openCommand,e as openFirstFrontend,c as pickReadyFrontend};

package/cli/dist-bundle/project-JFCTPRP5.js

@@ -0,0 +1,2 @@
+import{createRequire as __fliskRequire}from'node:module';const require=__fliskRequire(import.meta.url);
+import{g as a,h as b,i as c,j as d,k as e}from"./chunk-B2JOM3HN.js";import"./chunk-QEBN6ZVQ.js";import"./chunk-MYAYJF4Q.js";import"./chunk-GPUJ55MI.js";import"./chunk-YTBTCAWY.js";import"./chunk-L6O7TT3K.js";import"./chunk-TIPSERWO.js";import"./chunk-KJZUBHLO.js";export{c as cloneProjectTemplate,a as enableDiscoveredStacks,e as projectCommand,b as templateTargetDir,d as writeDefaultProjectConfig};

package/cli/dist-bundle/{services-EY5WKPHQ.js → services-DOHDHOCT.js}

@@ -1,2 +1,2 @@
 import{createRequire as __fliskRequire}from'node:module';const require=__fliskRequire(import.meta.url);
-import{ia as a,ja as b,ka as c,la as d,ma as e,na as f,oa as g,pa as h,qa as i,ra as j,sa as k,ta as l,ua as m,va as n,wa as o}from"./chunk-ETXZ5LUG.js";import"./chunk-C4UFBXRD.js";import"./chunk-KJZUBHLO.js";export{m as clearMetadataCache,f as discoverResources,e as discoverResourcesFromRoot,g as discoverResourcesStrict,c as discoverResourcesWithProblems,a as discoverServiceManifestPaths,h as discoverStackNames,j as discoverStacks,i as getAllStacks,n as getResourceMetadata,k as getResourcesForStack,o as getStackMetadata,b as resetPrintedServiceWarnings,l as stackExists,d as warnAboutSkippedFiles};
+import{ia as a,ja as b,ka as c,la as d,ma as e,na as f,oa as g,pa as h,qa as i,ra as j,sa as k,ta as l,ua as m,va as n,wa as o}from"./chunk-L6O7TT3K.js";import"./chunk-TIPSERWO.js";import"./chunk-KJZUBHLO.js";export{m as clearMetadataCache,f as discoverResources,e as discoverResourcesFromRoot,g as discoverResourcesStrict,c as discoverResourcesWithProblems,a as discoverServiceManifestPaths,h as discoverStackNames,j as discoverStacks,i as getAllStacks,n as getResourceMetadata,k as getResourcesForStack,o as getStackMetadata,b as resetPrintedServiceWarnings,l as stackExists,d as warnAboutSkippedFiles};

package/cli/dist-bundle/{tilt-port-owner-UBU6JWOA.js → tilt-port-owner-XODQHXHX.js}

@@ -1,2 +1,2 @@
 import{createRequire as __fliskRequire}from'node:module';const require=__fliskRequire(import.meta.url);
-import{a,b,c}from"./chunk-R7DWXISM.js";import"./chunk-IDNES5PE.js";import"./chunk-WCGBVETR.js";import"./chunk-CAEMWNPF.js";import"./chunk-ETXZ5LUG.js";import"./chunk-C4UFBXRD.js";import"./chunk-KJZUBHLO.js";export{c as classifyTiltPorts,a as findTiltPortOwner,b as isForeignTilt};
+import{a,b,c}from"./chunk-F2DLIM75.js";import"./chunk-T44DEEL6.js";import"./chunk-XHENT4KO.js";import"./chunk-YTBTCAWY.js";import"./chunk-L6O7TT3K.js";import"./chunk-TIPSERWO.js";import"./chunk-KJZUBHLO.js";export{c as classifyTiltPorts,a as findTiltPortOwner,b as isForeignTilt};

package/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flisk-cli-internal",
   "private": true,
-  "version": "1.4.6",
+  "version": "1.4.7",
   "description": "Flisk CLI — start services on your machine.",
   "keywords": [
     "flisk",

package/cli/templates/agent-skills/flisk-agent-ops/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: flisk-agent-ops
+description: Directs AI coding agents (Claude Code, Cursor, Codex) to operate and scaffold services using Flisk CLI and MCP tools instead of hand-writing Dockerfiles or Compose manifests.
+license: MIT
+compatibility: Requires the flisk CLI, Docker, and Tilt.
+metadata:
+  author: flisk-sh
+  version: "1.0"
+---
+
+# Flisk Agent Operations Guide
+
+When building, adding, or modifying services in this workspace, **do not hand-write Dockerfiles, Docker Compose files, or container manifests**. Flisk automatically manages containerization, networking (Traefik), dependencies, and hot reload.
+
+## Core Rules for AI Coding Agents
+
+1. **Always use Flisk to scaffold new services:**
+   - Scaffold an AI agent: `flisk resource <name> --type agent [--durability files|postgres]`
+   - Scaffold an MCP tool server: `flisk resource <name> --type mcp`
+   - Scaffold a backend API: `flisk resource <name> --type backend [--framework hono|express|fastify]`
+   - Scaffold a worker: `flisk resource <name> --type worker`
+   - Scaffold a frontend: `flisk resource <name> --type frontend [--framework vite|next]`
+
+2. **The `agent` Process Contract:**
+   - `/health`: Liveness only. Responds 200 when the process is alive.
+   - `/ready`: Readiness check. Responds 200 when the checkpoint store (named volume or Postgres) is reachable.
+   - `/turn` (POST): Accepts turns with header `x-session-id: <session-id>`.
+   - `/session` (GET): Returns checkpointed messages and turns for the session specified in `x-session-id`.
+   - Checkpoints persist across container restarts and `flisk down`/`flisk up`.
+
+3. **Operate via MCP or CLI:**
+   - Preflight & diagnostics: `flisk doctor --json` (or tool `doctor`)
+   - Start the stack: `flisk up --json` (or tool `up`)
+   - Inspect status: `flisk status --json` (or tool `status`)
+   - Check logs: `flisk logs --tail 200 --json` (or tool `logs`)
+   - Restart a service: `flisk restart <resource> --json` (or tool `restart_resource`)
+   - List agents: `flisk resources --type agent --json` (or tool `list_agents`)
+   - Inspect agent sessions: `flisk agent sessions <resource> --session-id <id> --json` (or tool `get_agent_sessions` with `resource` and `sessionId`; the id is required, otherwise `SESSION_ID_REQUIRED`)
+   - Stop services: `flisk down --json` (or tool `down`)

package/cli/templates/agent-skills/flisk-build/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: flisk-build
+description: Turn a plain request such as "build me a small online shop", "a SaaS with login and billing", "an AI agent with MCP tools and a database" or "a blog with an admin API" into Flisk steps (`flisk project`, `flisk resource ... --type ... --stack ...`, `flisk up`), check that every URL is healthy, and tell the user where the app is. Use when the user asks you to build, scaffold or run a new app on their laptop with Flisk.
+license: MIT
+compatibility: Requires the flisk CLI and the app's runtime (Node.js, Python, Go, Bun). Docker and Tilt only for the Docker + Tilt path (databases, one gateway URL, container parity). Does not deploy.
+metadata:
+  author: flisk-sh
+  version: "1.0"
+---
+
+# Build an app with Flisk
+
+The user describes an app. Map each part of it to a Flisk resource, let Flisk write the containers, routing and database wiring, write only the app code, and finish with the working URLs.
+
+## First: does this app need Docker?
+
+Pick the path before anything else.
+
+- **No Docker (prefer it for a simple app):** every part can be started with one command and none needs a database, one gateway URL, or the container it deploys. Examples: an API and a website, a static site and a webhook receiver, an agent that calls an external model API. Follow "Simple app without Docker" below and skip the Workflow.
+- **Docker + Tilt:** the app stores data in Postgres, needs Redis or another image, or the user asks for the same container they deploy. Follow the Workflow.
+
+Do not mix the two in one project: `flisk up` refuses with `MIXED_RUNTIME`.
+
+## Simple app without Docker
+
+1. Write each part as a folder with its own code and a `service.json` that names the command that starts it:
+   `{ "schemaVersion": 1, "appName": "api", "appType": "backend", "command": "node server.js", "port": 4000, "healthCheckPath": "/health" }`.
+   The command runs from that folder with `PORT` set. Add `"dependsOn": ["api"]` to a part that calls another, and pass URLs through `"env": { "API_URL": "http://localhost:4000" }`. Use the runtime's own watch mode for reload (`node --watch server.js`, `uvicorn main:app --reload --port $PORT`).
+2. Run `flisk doctor`. It checks only that each command's program is installed and the ports and `dependsOn` are valid.
+3. Run `flisk up --json` in the background (`&`) and wait for its one JSON line: `"ok":true`, `"runtime":"native"` and `urls` with each service's `http://localhost:<port>`. No `flisk project` or `flisk resource` step is needed; the first `flisk up` writes `.flisk/project.json`.
+4. Request every URL (`curl -fsS <url>`); each must answer. On a failure read `flisk logs --service <name> --tail 100`, fix the code, and run `flisk up --json` again (it restarts a crashed service on its own).
+5. Tell the user what was built, one line per part with its URL, and that `flisk down` stops it. Guide: docs/run-without-docker.md.
+
+## Workflow
+
+1. **Check the machine.** Run `flisk doctor`. If it reports an error, fix what it names (or tell the user what to start, for example Docker) and run it again. Do not continue past an unresolved error.
+2. **Plan the parts.** Split the request into resources and pick one stack name for all of them (short, kebab-case, from the app: `shop`, `saas`, `ai`, `blog`). Use the table below. Tell the user the plan in one or two lines.
+3. **Create the project** in an empty folder: `flisk project --yes`. If the request matches a starter app (restaurant, SaaS, store, agent stack, user management), clone that instead: see the flisk-recipe-starters skill. In a folder that already has `.flisk/project.json`, skip this step.
+4. **Add each part** with `flisk resource <name> --type <type> --stack <stack> --yes`. Add `--feature drizzle` (or `--feature prisma`) to a backend that stores data. Add `--framework <id>` or `--language <id>` only when the user names one.
+5. **Write the app code** inside each resource's `src/`. Keep the generated `/health` route. Do not write Dockerfiles, Compose files, Tiltfiles or proxy config, and do not edit `.autogenerated/`: change `service.json` instead and Flisk regenerates.
+6. **Preview, then start:** `flisk up <stack> --dry-run` shows the services and URLs. Then run `flisk up <stack> --json` in the background (`&`) and wait for its one JSON line: `"ok":true` means the stack is ready. A cold first build can take a few minutes.
+7. **Check every URL.** Get them with `flisk networks --stack <stack> --raw` (or `--json`) and request each health URL (`curl -fsS <url>`). Every one must answer 200. For a backend with a database, also request `<base>/health/db`.
+8. **When something fails**, run `flisk doctor`, then `flisk logs -s <resource> --tail 100` for the failing resource. Fix the source (app code or `service.json`), and the running stack reloads. If a build failed, run `flisk up <stack> --json` again. Follow the flisk-troubleshoot skill for messages you do not recognise. Stop after three failed attempts at the same error and tell the user what you saw. If Docker says `all predefined address pools have been fully subnetted`, old projects still hold their networks: run `flisk doctor --fix` here and `flisk down --prune-networks` in projects the user no longer runs (ask first), then start again.
+9. **Tell the user, in plain words:** what was built, one line per part with its URL, how to try it (an example `curl` or "open this in your browser"), and that `flisk down` stops everything.
+
+## From request to resources
+
+| The user asks for | Resource | Command |
+| --- | --- | --- |
+| A website, storefront, dashboard, admin page | `frontend` | `flisk resource web --type frontend --stack <stack> --yes` |
+| An API (orders, posts, users, billing) | `backend` | `flisk resource orders-api --type backend --stack <stack> --yes` |
+| Something that stores data, "a database" | `backend` with a database feature | `flisk resource notes-api --type backend --stack <stack> --feature drizzle --yes` |
+| Background jobs, emails, imports | `worker` | `flisk resource jobs --type worker --stack <stack> --yes` |
+| An AI agent, chatbot, assistant | `agent` | `flisk resource assistant --type agent --stack <stack> --yes` |
+| Tools for an agent, an MCP server | `mcp` | `flisk resource tools-mcp --type mcp --stack <stack> --yes` |
+| An admin panel or back office next to the main site | a second `frontend` | `flisk resource admin --type frontend --stack <stack> --yes` |
+| Several APIs ("3 APIs") | one `backend` each | `flisk resource catalog-api ...`, `flisk resource orders-api ...` (keep it to three or fewer) |
+| A cache, Redis | `bring-your-own` | `flisk resource cache --type bring-your-own --image redis:7 --no-proxy --stack <stack> --yes` |
+| Chat, live updates, websockets | `backend` | an ordinary backend; write the websocket route in its code |
+| An existing image (Mailpit, a vendor's server) | `bring-your-own` | `flisk resource mail --type bring-your-own --image <image> --stack <stack> --yes` |
+| A third-party API (payments, a shop platform) | `backend` that holds the key | list the key's name under `secrets.required` in its `service.json`, put the value in the project `.env`, and call the vendor only from that backend |
+| Python or Go | `backend` with a language | `flisk resource api --type backend --language python --stack <stack> --yes` (or `go`) |
+| A frontend framework by name (Vue, Svelte, Solid...) | `frontend` with a framework | `flisk resource web --type frontend --framework vue --stack <stack> --yes` (list them: `flisk resource --type frontend --frameworks`) |
+
+Web3 apps (a local chain node and contracts) are not covered: no Flisk recipe has run a chain node end to end. Say so instead of improvising one.
+
+Every stack gets the shared Postgres database: you do not add one. A backend created with `--feature prisma` gets a `DATABASE_URL`, a Prisma schema, and a `<name>-migrator` resource that applies migrations before the API starts. A backend created with `--feature drizzle` gets a `DATABASE_URL`, a Drizzle client in `src/db.ts` and a `/health/db` check, but no migrator.
+
+Name APIs `<thing>-api`. Flisk drops the `-api` suffix in the route, so `orders-api` is served at `/api/orders`. Backends are served on `api.<project>.localhost` and frontends on `app.<project>.localhost`, where `<project>` is the project name (by default the folder name) and the port is the one `flisk up` picked. Read the real URLs from `flisk networks`; do not build them by hand.
+
+## Tables
+
+The Flisk convention is a separate migrator that creates and changes tables before the APIs start. `--feature prisma` scaffolds one for you (`<name>-migrator`); for other tools see [one-shot jobs](../../../docs/byo.md#one-shot-jobs-migrations-seeders). For a quick prototype, creating tables with `CREATE TABLE IF NOT EXISTS` when the API starts also works; say which one you used.
+
+## Recipes
+
+Ready-made plans for common requests: flisk-recipe-starters (clone a working starter app), flisk-recipe-shop, flisk-recipe-saas, flisk-recipe-ai-agent and flisk-recipe-blog. More prompts by category (spreadsheets, recruiting, product management, internal tools) are in [docs/recipes/build-with-your-agent.md](../../../docs/recipes/build-with-your-agent.md).
+
+## Guardrails
+
+- Use only the flags in `flisk <command> --help`. Do not guess flags.
+- Report a URL as working only after it answered 200. If one never did, say so and say what the logs showed.
+- Ask before running `flisk up -f`: it stops a Tilt process that is already running.
+- Ask before adding services the user did not ask for. One frontend and one API is enough for "a small" app.
+- Flisk runs the app on this machine. It does not deploy it.

package/cli/templates/agent-skills/flisk-doctor/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: flisk-doctor
+description: Check or repair the local Flisk development environment and project configuration using `flisk doctor`. Use when setting up a Flisk project, before running `flisk up`, or when Docker, Tilt, Bun, ports, generated files or service manifests may be misconfigured.
+license: MIT
+compatibility: Requires the flisk CLI, Docker and Tilt on the local machine. Does not deploy.
+metadata:
+  author: flisk-sh
+  version: "1.0"
+---
+
+# Flisk doctor
+
+Use the CLI's environment and project checks as the starting point for Flisk setup and diagnosis.
+
+## Workflow
+
+1. Run `flisk doctor` from the Flisk project root.
+2. Read the full output and distinguish host prerequisites from project configuration findings.
+3. Fix the source configuration or environment item named by the diagnostic. Do not hand-edit generated `.autogenerated/` output.
+4. Run `flisk doctor` again to confirm the finding is resolved.
+5. Before starting services, use `flisk networks` to inspect the routed URLs; start only the needed stack with `flisk up <stack>` when appropriate.
+
+## Guardrails
+
+- Do not claim the project is ready when `flisk doctor` reports unresolved errors.
+- Ask before starting a large landscape or a task likely to build or launch many containers; it can take several minutes and use substantial resources.
+- Avoid stopping containers by broad name patterns. Identify the target project and stack first.
+- Treat diagnostic output as evidence. If it does not identify a cause, report what was observed and gather the next relevant check instead of guessing.

package/cli/templates/agent-skills/flisk-recipe-ai-agent/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: flisk-recipe-ai-agent
+description: Recipe for "build me an AI agent with MCP tools and a database" with Flisk - an agent service with sessions, an MCP tools server and a backend with a database in one stack, started with `flisk up`. Use with the flisk-build skill when the user asks for an AI agent, chatbot, assistant, MCP server or tools for an agent.
+license: MIT
+compatibility: Requires the flisk CLI, Docker and Tilt on the local machine. Does not deploy.
+metadata:
+  author: flisk-sh
+  version: "1.0"
+---
+
+# Recipe: an AI agent with MCP tools and a database
+
+**Parts:** an agent that keeps a conversation per session, an MCP server with the agent's tools, and a backend that stores the data the tools read and write.
+
+## Steps
+
+```bash
+flisk doctor
+flisk project --yes
+flisk resource assistant --type agent --stack ai --yes
+flisk resource tools-mcp --type mcp --stack ai --yes
+flisk resource notes-api --type backend --stack ai --feature drizzle --yes
+flisk up ai --dry-run
+flisk up ai --json &          # wait for {"ok":true}
+flisk networks --stack ai --raw
+```
+
+Keep the agent on the default session storage (a named volume). In Flisk 1.4.2 an agent created with `--durability postgres` fails its image build (`TS7016: Could not find a declaration file for module 'pg'`); use the `notes-api` backend for the database instead.
+
+## App code
+
+- `notes-api`: a `notes` table (`src/schema.ts`) and `GET /notes`, `POST /notes`. Keep `/health` and `/health/db`.
+- `tools-mcp`: tools such as `list_notes` and `add_note` that call `notes-api`.
+- `assistant`: the agent contract is already in place: `/health`, `/ready`, `POST /turn` and `GET /session` with an `x-session-id` header. Put the agent's logic in the turn handler. If the user gives a model API key, list its name under `secrets.required` in `service.json` and put the value in the project `.env`.
+
+## Done when
+
+Each answers 200 on `api.<project>.localhost:<port>`: `/api/assistant/health`, `/api/assistant/ready`, `/api/tools-mcp/health`, `/api/notes/health`, `/api/notes/health/db`. Then send one turn:
+
+```bash
+curl -s -X POST -H 'x-session-id: demo' -H 'content-type: application/json' \
+  -d '{"input":"hello"}' http://api.<project>.localhost:<port>/api/assistant/turn
+```
+
+Tell the user the three URLs, how to talk to the agent (the `curl` above), and that `flisk agent sessions assistant --session-id demo` shows the saved conversation.

package/cli/templates/agent-skills/flisk-recipe-blog/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: flisk-recipe-blog
+description: Recipe for "build me a blog with an admin API" with Flisk - a public blog site and a posts API with a database and token-protected admin routes, in one stack started with `flisk up`. Use with the flisk-build skill when the user asks for a blog, a CMS, a news site or any site with an editor.
+license: MIT
+compatibility: Requires the flisk CLI, Docker and Tilt on the local machine. Does not deploy.
+metadata:
+  author: flisk-sh
+  version: "1.0"
+---
+
+# Recipe: a blog with an admin API
+
+**Parts:** a public blog site, and a posts API with public read routes and admin write routes.
+
+## Steps
+
+```bash
+flisk doctor
+flisk project --yes
+flisk resource blog --type frontend --stack blog --yes
+flisk resource posts-api --type backend --stack blog --feature drizzle --yes
+flisk up blog --dry-run
+flisk up blog --json &        # wait for {"ok":true}
+flisk networks --stack blog --raw
+```
+
+## App code
+
+- `posts-api`: a `posts` table (title, slug, body, published). Public: `GET /posts`, `GET /posts/:slug`. Admin: `POST /admin/posts`, `PUT /admin/posts/:id`, `DELETE /admin/posts/:id`, accepted only with `Authorization: Bearer <token>` signed with `JWT_SECRET` from the project `.env`. Seed one welcome post.
+- `blog`: a list page and a post page that read from `posts-api` through the generated client in `.autogenerated/`.
+
+## Done when
+
+Each answers 200: the `blog` health URL, `/api/posts/health` and `/api/posts/health/db` on `api.<project>.localhost:<port>`. An admin `POST` without a token answers 401, and with a token it creates a post.
+
+Tell the user the blog URL, the API URL, how to create a post (the `curl` with a token), and that `flisk down` stops everything.

package/cli/templates/agent-skills/flisk-recipe-saas/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: flisk-recipe-saas
+description: Recipe for "build me a SaaS with login and billing" with Flisk - a web app, an accounts API with a database for sign-up and login, and a billing API, in one stack started with `flisk up`. Use with the flisk-build skill when the user asks for a SaaS, a members area, subscriptions, sign-up or payments.
+license: MIT
+compatibility: Requires the flisk CLI, Docker and Tilt on the local machine. Does not deploy.
+metadata:
+  author: flisk-sh
+  version: "1.0"
+---
+
+# Recipe: a SaaS with login and billing
+
+**Parts:** a web app, an accounts API (sign-up, login, sessions), and a billing API (plans and subscriptions). Both APIs store data in the stack's Postgres.
+
+## Steps
+
+```bash
+flisk doctor
+flisk project --yes
+flisk resource web --type frontend --stack saas --yes
+flisk resource accounts-api --type backend --stack saas --feature drizzle --yes
+flisk resource billing-api --type backend --stack saas --feature drizzle --yes
+flisk up saas --dry-run
+flisk up saas --json &        # wait for {"ok":true}
+flisk networks --stack saas --raw
+```
+
+## App code
+
+- `accounts-api`: `POST /signup`, `POST /login`, `GET /me`. Hash passwords (`Bun.password.hash`). Sign session tokens with `JWT_SECRET`, which Flisk generates into the project `.env` and passes to the container. Do not invent a new secret file.
+- `billing-api`: `GET /plans`, `POST /subscribe`, `GET /subscription`. Verify the caller's token with the same `JWT_SECRET`.
+- Payments: without the user's test keys, record subscriptions in the database and say that no real payment provider is connected. If the user gives a provider's **test** key, list its name under `secrets.required` in `services/saas/billing-api/service.json` and put the value in the project `.env`, never in code.
+- `web`: sign-up and login forms, a plans page, and a "your plan" page.
+
+## Done when
+
+Each answers 200: the `web` health URL, `/api/accounts/health`, `/api/accounts/health/db`, `/api/billing/health` and `/api/billing/health/db` on `api.<project>.localhost:<port>`. Also sign up and log in once with `curl` and show the user it worked.
+
+Then tell the user the web app URL, the two API URLs, that payments are not connected to a real provider (unless they are), and that `flisk down` stops everything.

package/cli/templates/agent-skills/flisk-recipe-shop/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: flisk-recipe-shop
+description: Recipe for "build me a small online shop" with Flisk - a storefront website and an orders API with a database in one stack, started with `flisk up` and checked URL by URL. Use with the flisk-build skill when the user asks for a shop, store, catalogue or anything with products and orders.
+license: MIT
+compatibility: Requires the flisk CLI, Docker and Tilt on the local machine. Does not deploy.
+metadata:
+  author: flisk-sh
+  version: "1.0"
+---
+
+# Recipe: a small online shop
+
+**Parts:** a storefront the user opens in the browser, and an orders API that stores products and orders.
+
+## Steps
+
+```bash
+flisk doctor
+flisk project --yes
+flisk resource storefront --type frontend --stack shop --yes
+flisk resource orders-api --type backend --stack shop --feature drizzle --yes
+flisk up shop --dry-run
+flisk up shop --json &        # wait for {"ok":true}
+flisk networks --stack shop --raw
+```
+
+## App code
+
+- `services/shop/orders-api/src/schema.ts`: a `products` table and an `orders` table. Use `src/db.ts` for queries.
+- `services/shop/orders-api/src/index.ts`: `GET /products`, `POST /orders`, `GET /orders`. Keep `/health` and `/health/db`. Create the tables as the flisk-build skill says under "Tables"; seed three products if the table is empty.
+- `services/shop/storefront/src/`: a page that lists the products from the API and a button that places an order. Call the API through the generated client in `.autogenerated/` (the `api-client` feature), not a hard-coded host.
+
+## Done when
+
+Each of these answers 200 (ports come from `flisk networks`):
+
+- the storefront health URL, for example `http://app.<project>.localhost:<port>/storefront/health`
+- `http://api.<project>.localhost:<port>/api/orders/health`
+- `http://api.<project>.localhost:<port>/api/orders/health/db`
+
+Then tell the user: "Your shop is running. Open the storefront at … . The orders API is at … ; try `curl …/api/orders/products`. Stop it with `flisk down`."

package/cli/templates/agent-skills/flisk-recipe-starters/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: flisk-recipe-starters
+description: Start from a ready-made Flisk starter app instead of an empty project when the request matches one - restaurant (reservations, kitchen, menu, floor), SaaS (dashboard, billing, checkout), online store, AI agent stack (agent, MCP tools, database), user management (admin, portal, audit), or a small orders example. Clones it with `flisk project <template>` and starts it. Use with the flisk-build skill.
+license: MIT
+compatibility: Requires the flisk CLI, git, Docker and Tilt on the local machine. Does not deploy.
+metadata:
+  author: flisk-sh
+  version: "1.0"
+---
+
+# Recipe: start from a starter app
+
+A starter is a working multi-service app in the flisk-sh GitHub organisation. Starting from one is faster than building from an empty folder, and the user can change it afterwards. Use one when the request clearly matches a row below; use only one starter per project.
+
+| The user asks for | Template | Stacks | What it ships |
+| --- | --- | --- | --- |
+| restaurant, reservations, kitchen, menu, bistro, diner | `restaurant` | `guest`, `kitchen`, `operations` | reservation app and API, floor app, kitchen API and worker, menu API (two websites) |
+| SaaS, dashboard, billing, subscription, checkout | `saas` | `app`, `billing` | dashboard app and API, checkout app, billing API, a migrator per API |
+| shop, store, storefront, ecommerce, catalogue | `ecommerce` | `store` | Vue storefront, catalog API and its migrator |
+| AI agent stack, agent with tools and a database | `agent-stack` | `agents` | agent, its migrator, MCP tools server |
+| user management, admin portal, accounts, audit | `user-management` | `admin`, `compliance`, `portal` | admin app and API, portal app and API, audit API and worker |
+| the smallest example, orders | `example` | `shop` | orders app, API and worker |
+
+`erp` also exists: it is a 107-service scale test, not an app. Do not use it for a user's request.
+
+## Steps
+
+```bash
+flisk doctor
+flisk project <template> --path <folder> --yes
+cd <folder>
+flisk project --yes          # see the note below
+flisk up --dry-run           # check the services and URLs
+flisk up <stack> --json &    # or omit <stack> to start every stack
+flisk networks --raw
+```
+
+The starters ship `.flisk/project.json`, so `flisk up` and `flisk stacks` work right after cloning. Running `flisk project --yes` inside the clone is safe but not required.
+
+Then change the starter to what the user asked for: rename things in the app code, add resources with `flisk resource ... --stack <stack>`, and follow the flisk-build skill to check every URL and report them.
+
+## Guardrails
+
+- Cloning needs network access to github.com. If it fails, fall back to the matching recipe (flisk-recipe-shop, flisk-recipe-saas, flisk-recipe-ai-agent) on an empty project.
+- A starter with several stacks can be large on a small machine. Start only the stack the user needs first (`flisk up <stack>`), and ask before starting all of them.
+- Tell the user which starter you used and that it came from github.com/flisk-sh.

package/cli/templates/agent-skills/flisk-resource/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: flisk-resource
+description: Create a new Flisk service with `flisk resource <name> --type agent|backend|worker|mcp`, or register an existing one. Use when the user asks to add a service, agent, MCP tools server, worker, or backend to a Flisk project.
+license: MIT
+compatibility: Requires the flisk CLI. Does not deploy.
+metadata:
+  author: flisk-sh
+  version: "1.0"
+---
+
+# Flisk resource
+
+Create services with the CLI so each one gets a valid `service.json` and the right runtime contract. Do not hand-write container manifests.
+
+## Workflow
+
+1. Choose the type: `agent` (its own `/health`, `/ready`, and `x-session-id` routing), `backend` (HTTP API), `worker` (background jobs), or `mcp` (tools server).
+2. Create it: `flisk resource <name> --type <type> --stack <stack>`. Use `--language <id>` only when the user names a language (`bun` is the default).
+3. For an existing service, use `--register-existing` instead of generating templates.
+4. Check the result with `flisk doctor` and read the new `service.json`.
+5. Start it with `flisk up <stack>` (see the flisk-up skill).
+
+## Guardrails
+
+- Use kebab-case names.
+- A database migration belongs in its own `migrator` resource, not in an API start script.
+- Ask before creating resources in a stack the user did not name.

package/cli/templates/agent-skills/flisk-status/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: flisk-status
+description: Report the state of Flisk stacks and resources with `flisk status --json`, and inspect agent sessions with `flisk agent sessions`. Use when the user asks what is running, which URLs are healthy, or why a service is not responding.
+license: MIT
+compatibility: Requires the flisk CLI. Does not deploy.
+metadata:
+  author: flisk-sh
+  version: "1.0"
+---
+
+# Flisk status
+
+Read the state from the CLI rather than guessing from Docker output.
+
+## Workflow
+
+1. Run `flisk status --json` from the project root. Use `--resources` to list every discovered resource, or `--tilt` for Tilt resource state.
+2. Summarize per stack: running, healthy, unhealthy, or stopped, with each service's URL.
+3. For an agent resource, inspect sessions with `flisk agent sessions <resource> --session-id <id>`.
+4. If a service is unhealthy, run `flisk networks` to confirm its routed URL, then switch to the flisk-troubleshoot skill.
+
+## Guardrails
+
+- Report only what the output shows. Say so when a field is missing.
+- Do not stop containers by name pattern. Identify the stack first.