create-fungi-app 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# create-fungi-app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+create-fungi-app creates a small App with Caps UI and one typed Agar backend
+method, running in a local standalone Oyster. Most people want
+[Oyster](https://docs.fungi.computer/oyster/) to run Apps or
+[Shiitake](https://docs.fungi.computer/shiitake/) to run Agents.
+
+## Quick start
+
+Build and test an App locally without Docker, a Fungi Computer, or a Cloudflare
+account.
+
+Use Node 24.20.0, npm 11.19.0 and Git for Oyster's pinned build toolchain.
+
+```sh
+npm create fungi-app@latest my-app
+cd my-app
+npm run dev
+```
+
+Use `-- --no-install` to generate files without installing dependencies. In a
+terminal, running `npm create fungi-app@latest` with no directory asks for the
+project name and whether to install; without a terminal, pass the directory
+argument. Existing directories are refused.
+
+Open the loopback URL printed by the development command. Click **Say hello** to
+call the backend. Save an edit in `src/` to rebuild the App and reload its page.
+
+You can also test the typed backend over HTTP while development is running:
+
+```sh
+curl --fail-with-body http://127.0.0.1:61343/apps/app/methods/greet \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Oyster"}'
+# {"message":"Hello, Oyster!"}
+```
+
+Stop development with Ctrl+C. To build a Release without starting a server:
+
+```sh
+npm run build
+```
+
+This writes `dist/release.json` and `dist/artifacts/`; it does not deploy or
+publish anything.
+
+### What runs locally
+
+- `npm run dev` uses the existing Oyster builder, then runs
+  `wrangler dev --local` on loopback. Workerd executes the host Worker and the
+  App's Durable Object backend through Worker Loader. Local R2 serves the built
+  UI and assets; Wrangler keeps local state under `.wrangler/`.
+- `npm run build` runs Node/npm and the App compiler on your machine against an
+  isolated snapshot of saved files. It does not allocate a build Computer.
+- The template is React/Caps UI, one typed Agar `greet` method, a Durable Object
+  facet, and a minimal Oyster Worker/config. It declares no Computer or
+  container.
+
+Wrangler configurations that include a container-backed Computer need Docker to
+build and run that Computer locally. That is separate from compiling and running
+this App.
+
+Without an attached Computer, Computer files, shell commands, processes and port
+previews are unavailable. Hosted repository build jobs also need their
+configured execution backend. The starter does not emulate Team sign-in/grants
+or funded provider services, and does not map your laptop's files into a
+Computer. Development admits local requests as its owner; use it for trusted
+source, not as a production authentication or isolation proof.
+
+### Measured startup
+
+In a Linux trial on October 28, 2026, the locally packed candidate took **53.8
+seconds** from starting the scaffold command to the first working browser
+greeting, under the conditions below:
+
+| Step                                   | Elapsed |
+| -------------------------------------- | ------- |
+| Scaffold and install                   | 42.3 s  |
+| Scaffold → first working App greeting  | 53.8 s  |
+| Saved UI/backend edit → changed result | 11.0 s  |
+| Separate `npm run build`               | 10.6 s  |
+
+The cold run used a fresh HOME and empty npm cache on Linux, with Docker blocked
+and no inherited Fungi or Cloudflare credentials. Node/npm/Git were already
+installed. The packed-release proof served Fungi packages from local tarballs
+and downloaded other dependencies from npm. Packing and toolchain/browser
+installation were outside the clock. The saved-edit measurement reused the
+running App. These are observed times, not a two-minute guarantee on another
+machine or network.
+
+## Examples
+
+To create the App without installing dependencies:
+
+```sh
+npm create fungi-app@latest my-app -- --no-install
+cd my-app
+npm install
+npm run dev
+```
+
+To build a Release from your saved files, run this inside the generated App:
+
+```sh
+npm run build
+```
+
+The build writes `dist/release.json` and `dist/artifacts/`. The generated
+`README.md` shows `oyster install ./dist` (or `./dist/release.json`) using
+`OYSTER_URL` and `OYSTER_OWNER_KEY`. The CLI delegates to the existing
+`@fungi.computer/oyster/pack` uploader; it does not deploy an Oyster.
+
+To use committed source instead, push the generated App to a Bonsai repository
+and choose **Make this an App** in repository Settings. The root
+`package.json#fungi.build` supplies the recipe. Registration does not build or
+install. Subsequent accepted main pushes build the new commit on a hosted
+backend and install only after success and within existing approval. New
+permissions require owner consent and leave the previous Release unchanged.
+
+## Core concepts
+
+The template declares its backend definition, declaration, and build recipe in
+`package.json`. `fungi.build` owns the UI entry, backend entry, asset bounds,
+and recipe kind. Paths are relative to the App directory. Build and dev read
+that metadata from your saved files; there is no second recipe inside the
+command. `src/backend/methods.ts` owns the input, output and implementation of
+`greet`; the UI calls that method through Agar's host-admitted capability.
+
+`npm run dev` uses Oyster's builder and a standalone Worker on Wrangler. Its
+development host admits local requests as its owner. The generated
+`oyster/worker.ts` uses key authentication for a deployed host.
+
+`npm run build` captures saved files, including uncommitted edits, in an
+isolated Git snapshot. It leaves your repository history alone and records that
+snapshot in the Release's provenance. Dependency installation uses
+`package-lock.json`. Building creates the Release locally. Installing it into an
+Oyster and publishing packages are separate operations.
+
+## License
+
+MIT licensed. See [LICENSE](LICENSE).

package/dist/app-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/app-cli.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+import { starterIds } from "./ids.js";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { watch } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { createInterface } from "node:readline";
+import { setTimeout as delay } from "node:timers/promises";
+import { parseArgs } from "node:util";
+import { Cli } from "@fungi.computer/lantern";
+import { readBuildManifest, appBuildRecipe, createAppPublisher, createLocalArtifactWriter, createLocalBuildExecutor, createLocalDirectorySourceCapture, } from "@fungi.computer/oyster/build";
+import { InstallationObservationError, installRelease, } from "@fungi.computer/oyster/pack";
+import { parseReleaseId } from "@fungi.computer/puffball";
+import { releaseSchema } from "@fungi.computer/puffball/effect";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { z } from "zod";
+const cli = new Cli({ brand: "fungi" });
+const root = process.cwd();
+const lifecycle = new AbortController();
+const shutdown = { interrupted: false };
+process.once("SIGINT", () => {
+    shutdown.interrupted = true;
+    lifecycle.abort();
+});
+process.once("SIGTERM", () => {
+    shutdown.interrupted = true;
+    lifecycle.abort();
+});
+async function build(out) {
+    const manifest = readBuildManifest(await readFile(join(root, "package.json"), "utf8"));
+    const appId = manifest.fungi.appId;
+    if (appId === undefined)
+        throw new Error("App manifest requires fungi.appId");
+    const recipe = appBuildRecipe(manifest, "");
+    const publisher = createAppPublisher({
+        config: { appId, recipe },
+        sourceCapture: createLocalDirectorySourceCapture(root),
+        buildExecutor: createLocalBuildExecutor(),
+        artifactWriter: createLocalArtifactWriter(join(out, "artifacts"), recipe.assets),
+        releaseCatalog: { createRelease: (release) => Promise.resolve(release) },
+    });
+    const release = await Effect.runPromise(Effect.scoped(publisher.createCandidate(parseReleaseId(starterIds.release.generate()))), { signal: lifecycle.signal });
+    await mkdir(out, { recursive: true });
+    const encoded = Schema.encodeUnknownSync(Schema.fromJsonString(releaseSchema))(release);
+    await writeFile(join(out, "release.json"), `${encoded}\n`);
+    return encoded;
+}
+async function dev(port) {
+    const directory = join(root, ".botanical/dev");
+    const out = join(directory, "release");
+    const key = randomBytes(24).toString("hex");
+    const origin = `http://127.0.0.1:${String(port)}`;
+    await mkdir(directory, { recursive: true });
+    await writeFile(join(directory, ".dev.vars"), `OYSTER_OWNER_KEY=${key}\nOYSTER_ORIGIN=${origin}\n`, {
+        mode: 0o600,
+    });
+    const config = z
+        .record(z.string(), z.unknown())
+        .parse(JSON.parse(await readFile(join(root, "oyster/wrangler.json"), "utf8")));
+    await writeFile(join(directory, "wrangler.json"), JSON.stringify({ ...config, main: "dev-worker.ts" }));
+    // Wrangler injects its reload script into the local host page. The ordinary
+    // standalone Worker retains Oyster's production CSP.
+    const developmentCsp = `default-src 'none'; script-src 'self' 'unsafe-inline'; style-src 'unsafe-inline'; frame-src 'self'; connect-src 'self' ws://127.0.0.1:${String(port)}; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`;
+    const worker = (release) => `import worker from "../../oyster/worker.ts";
+export { OysterBinding, OysterRegistry, OysterInstance, OysterMcp, OysterInstallationExecutor } from "../../oyster/worker.ts";
+export default { async fetch(request, env, context) {
+  const headers = new Headers(request.headers);
+  headers.set("Authorization", "Bearer " + env.OYSTER_OWNER_KEY);
+  const response = await worker.fetch(new Request(request, { headers }), env, context);
+  const result = new Response(response.body, response);
+  if (new URL(request.url).pathname === "/apps/app/") result.headers.set("Content-Security-Policy", ${JSON.stringify(developmentCsp)});
+  result.headers.set("X-Fungi-App-Release", ${JSON.stringify(z.object({ releaseId: z.string() }).parse(JSON.parse(release)).releaseId)});
+  return result;
+} };
+`;
+    let release = await cli.task("Building App", () => build(out));
+    await writeFile(join(directory, "dev-worker.ts"), worker(release));
+    const child = spawn(join(root, "node_modules/.bin/wrangler"), [
+        "dev",
+        "--local",
+        "--ip",
+        "127.0.0.1",
+        "--port",
+        String(port),
+        "--live-reload",
+        "--config",
+        join(directory, "wrangler.json"),
+        "--persist-to",
+        join(root, ".wrangler"),
+    ], {
+        cwd: root,
+        env: { ...process.env, WRANGLER_SEND_METRICS: "false" },
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: true,
+    });
+    for (const stream of [child.stdout, child.stderr]) {
+        createInterface({ input: stream }).on("line", (line) => {
+            cli.info(line.replaceAll(key, "[redacted]"));
+        });
+    }
+    const stopped = new Promise((done, reject) => {
+        child.once("error", reject);
+        child.once("exit", (code) => {
+            if (lifecycle.signal.aborted || code === 0)
+                done();
+            else
+                reject(new Error("Wrangler stopped before the App was closed."));
+        });
+    });
+    // Attach the rejection handler immediately while startup and compilation run.
+    void stopped.catch((cause) => {
+        lifecycle.abort(cause);
+    });
+    const stop = () => {
+        if (child.exitCode === null &&
+            child.signalCode === null &&
+            child.pid !== undefined)
+            process.kill(-child.pid, "SIGTERM");
+    };
+    lifecycle.signal.addEventListener("abort", stop, { once: true });
+    async function install() {
+        const response = await installRelease({
+            directory: out,
+            url: origin,
+            key,
+            installationId: "app",
+            signal: lifecycle.signal,
+            onAdmitted: ({ installationId, requestId }) => {
+                cli.info(`Installation ${installationId} accepted (request ${requestId}); observing authoritative status.`);
+            },
+        });
+        if (!response.ok)
+            throw new Error(`Oyster refused the App installation (${String(response.status)}).`);
+    }
+    let timer;
+    let rebuilding = false;
+    let pending = false;
+    const rebuild = async () => {
+        pending = true;
+        if (rebuilding)
+            return;
+        rebuilding = true;
+        try {
+            while (pending && !lifecycle.signal.aborted) {
+                pending = false;
+                release = await cli.task("Rebuilding App", () => build(out));
+                await install();
+                await writeFile(join(directory, "dev-worker.ts"), worker(release));
+                cli.info("App rebuilt; Wrangler is reloading the page.");
+            }
+        }
+        catch (cause) {
+            if (!lifecycle.signal.aborted) {
+                Effect.runSync(Effect.logError("App rebuild failed.", Redacted.make(cause)));
+                if (cause instanceof InstallationObservationError)
+                    reportUnconfirmedInstallation(cause);
+                else
+                    cli.info("App rebuild failed. Fix the source and save again.");
+            }
+        }
+        finally {
+            rebuilding = false;
+        }
+    };
+    const schedule = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            void rebuild();
+        }, 150);
+    };
+    try {
+        for (let attempt = 0;; attempt++) {
+            lifecycle.signal.throwIfAborted();
+            const readiness = await Effect.runPromise(Effect.result(Effect.tryPromise({
+                try: () => fetch(`${origin}/login`, { signal: lifecycle.signal }),
+                catch: (cause) => new Error("Wrangler readiness request failed.", { cause }),
+            })));
+            lifecycle.signal.throwIfAborted();
+            if (Result.isSuccess(readiness) && readiness.success.ok)
+                break;
+            if (attempt === 119)
+                throw new Error("Wrangler did not start within one minute.", {
+                    cause: Result.isFailure(readiness)
+                        ? readiness.failure
+                        : new Error(`Wrangler returned HTTP ${String(readiness.success.status)}.`),
+                });
+            await delay(500, undefined, { signal: lifecycle.signal });
+        }
+        await install();
+        watch(join(root, "src"), { recursive: true, signal: lifecycle.signal }, schedule);
+        watch(root, { signal: lifecycle.signal }, (_event, filename) => {
+            if (filename !== null &&
+                ["index.html", "package.json", "package-lock.json"].includes(filename))
+                schedule();
+        });
+        cli.outro(`App ready at ${origin}/apps/app/`);
+        await stopped;
+    }
+    finally {
+        lifecycle.abort();
+        clearTimeout(timer);
+        stop();
+        await stopped;
+    }
+}
+function reportUnconfirmedInstallation(cause) {
+    cli.info(`Installation outcome unconfirmed (request ${cause.requestId}). Oyster may still finish; stopping observation does not cancel it.`);
+}
+try {
+    const { positionals, values } = parseArgs({
+        allowPositionals: true,
+        options: {
+            port: { type: "string", default: "61343" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    if (values.help)
+        cli.info("fungi-app build | fungi-app dev [--port 61343]");
+    else if (positionals.length !== 1)
+        throw new Error("Choose fungi-app build or fungi-app dev.");
+    else if (positionals[0] === "build") {
+        await cli.task("Building Release", () => build(resolve(root, "dist")));
+        cli.outro("Release ready in dist/release.json and dist/artifacts/.");
+    }
+    else if (positionals[0] === "dev")
+        await dev(z.coerce.number().int().min(1).max(65535).parse(values.port));
+    else
+        throw new Error("Choose fungi-app build or fungi-app dev.");
+}
+catch (cause) {
+    if (!shutdown.interrupted) {
+        if (cause instanceof InstallationObservationError)
+            reportUnconfirmedInstallation(cause);
+        Effect.runSync(Effect.logError("App command failed.", Redacted.make(cause)));
+        cli.cancel("App command failed.");
+        process.exitCode = 1;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { basename, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { Cli, isCancel } from "@fungi.computer/lantern";
+import { projectName, scaffoldApp } from "./index.js";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+class InputError extends Error {
+}
+const cli = new Cli({ brand: "fungi" });
+try {
+    const { positionals, values } = parseArgs({
+        allowPositionals: true,
+        options: {
+            "no-install": { type: "boolean" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    if (values.help) {
+        cli.info("npm create fungi-app@latest my-app [-- --no-install]");
+    }
+    else {
+        if (positionals.length > 1)
+            throw new InputError("Provide one project directory, such as my-app.");
+        if (positionals.length === 0 && !cli.interactive)
+            throw new InputError("Provide a project directory when running without a terminal: npm create fungi-app@latest my-app");
+        cli.welcome("Create a Fungi App");
+        const name = positionals[0] ??
+            (await cli.text({
+                message: "Where should we create your App?",
+                placeholder: "my-app",
+                validate: (value) => projectName.safeParse(value === undefined ? undefined : basename(resolve(value))).success
+                    ? undefined
+                    : "Choose a directory with a valid npm package name.",
+            }));
+        if (isCancel(name)) {
+            cli.cancel("App creation cancelled.");
+        }
+        else {
+            const directory = name;
+            if (!projectName.safeParse(basename(resolve(directory))).success)
+                throw new InputError("Choose a directory with a valid npm package name, such as my-app.");
+            await cli.task("Creating your App", async () => scaffoldApp(directory));
+            const install = values["no-install"]
+                ? false
+                : cli.interactive
+                    ? await cli.confirm({
+                        message: "Install dependencies with npm?",
+                        initialValue: true,
+                    })
+                    : true;
+            if (!isCancel(install) && install) {
+                await cli.task("Installing dependencies", () => new Promise((done, reject) => {
+                    const child = spawn("npm", ["install"], {
+                        cwd: resolve(directory),
+                        stdio: "inherit",
+                    });
+                    child.once("error", reject);
+                    child.once("exit", (code) => {
+                        if (code === 0)
+                            done();
+                        else
+                            reject(new Error("Dependency installation failed."));
+                    });
+                }));
+            }
+            cli.outro(`Ready. Run:\n  cd ${directory}\n${install === true ? "" : "  npm install\n"}  npm run dev`);
+        }
+    }
+}
+catch (cause) {
+    const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
+    const message = cause instanceof InputError
+        ? cause.message
+        : code === "ERR_PARSE_ARGS_UNKNOWN_OPTION"
+            ? "Unknown option. Run create-fungi-app --help for usage."
+            : code === "EEXIST"
+                ? "That directory already exists. Choose a new directory."
+                : "App creation failed.";
+    Effect.runSync(Effect.logError("App creation failed.", Redacted.make(cause)));
+    cli.cancel(message);
+    process.exitCode = 1;
+}

package/dist/ids.d.ts

@@ -0,0 +1,4 @@
+export declare const starterIds: Readonly<{
+    readonly app: import("@fungi.computer/cairn/id").IdCodec<"app-authoring", "app", 1>;
+    readonly release: import("@fungi.computer/cairn/id").IdCodec<"app-authoring", "release", 1>;
+}>;

package/dist/ids.js

@@ -0,0 +1,6 @@
+import { defineIdFamily } from "@fungi.computer/cairn/id";
+export const starterIds = defineIdFamily({
+    family: "app-authoring",
+    version: 1,
+    kinds: { app: { prefix: "app" }, release: { prefix: "rel" } },
+});

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import * as z from "zod";
+/** A project directory name, also used as its npm package name. */
+export declare const projectName: z.ZodString;
+/** Create a starter App in a new directory. Existing destinations are never overwritten. */
+export declare function scaffoldApp(directory: string): Promise<void>;

package/dist/index.js

@@ -0,0 +1,27 @@
+import { starterIds } from "./ids.js";
+import { parseAppId } from "@fungi.computer/puffball";
+import { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as z from "zod";
+import validatePackageName from "validate-npm-package-name";
+/** A project directory name, also used as its npm package name. */
+export const projectName = z
+    .string()
+    .refine((name) => validatePackageName(name).validForNewPackages, {
+    message: "Choose a valid npm package name for your project directory.",
+});
+/** Create a starter App in a new directory. Existing destinations are never overwritten. */
+export async function scaffoldApp(directory) {
+    const target = resolve(directory);
+    const name = projectName.parse(basename(target));
+    const template = fileURLToPath(new URL("../template/", import.meta.url));
+    await mkdir(target);
+    await cp(template, target, { recursive: true });
+    await rename(resolve(target, "gitignore"), resolve(target, ".gitignore"));
+    const manifest = z
+        .object({ fungi: z.record(z.string(), z.unknown()) })
+        .loose()
+        .parse(JSON.parse(await readFile(resolve(target, "package.json"), "utf8")));
+    await writeFile(resolve(target, "package.json"), `${JSON.stringify({ ...manifest, name, fungi: { ...manifest.fungi, appId: parseAppId(starterIds.app.generate()) } }, null, 2)}\n`);
+}

package/docs/api/README.md

@@ -0,0 +1,38 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**create-fungi-app**
+
+---
+
+# create-fungi-app
+
+## Variables
+
+### projectName
+
+```ts
+const projectName: ZodString;
+```
+
+A project directory name, also used as its npm package name.
+
+## Functions
+
+### scaffoldApp()
+
+```ts
+function scaffoldApp(directory): Promise<void>;
+```
+
+Create a starter App in a new directory. Existing destinations are never
+overwritten.
+
+#### Parameters
+
+| Parameter   | Type     |
+| ----------- | -------- |
+| `directory` | `string` |
+
+#### Returns
+
+`Promise`\<`void`\>

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "create-fungi-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "description": "Create a Caps and Agar App that runs on a standalone Oyster",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.20.0"
+  },
+  "bin": {
+    "create-fungi-app": "dist/cli.js",
+    "fungi-app": "dist/app-cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "template",
+    "docs/api",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@fungi.computer/lantern": "0.4.2",
+    "zod": "4.4.3",
+    "@fungi.computer/oyster": "0.15.0",
+    "@fungi.computer/puffball": "0.5.4",
+    "effect": "4.0.2",
+    "validate-npm-package-name": "7.0.2",
+    "@fungi.computer/cairn": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/create-fungi-app.git"
+  }
 }

package/template/README.md

@@ -0,0 +1,99 @@
+# My App
+
+This App has Caps UI and one typed backend method. Oyster hosts both surfaces;
+the UI calls `greet` through Agar's `app.methods` capability.
+
+Use Node 24.20.0, npm 11.19.0 and Git, then:
+
+```sh
+npm install
+npm run dev
+```
+
+No Docker, Fungi Computer, or Cloudflare account is needed. Open the printed
+loopback URL and click **Say hello**, or test the same backend directly:
+
+```sh
+curl --fail-with-body http://127.0.0.1:61343/apps/app/methods/greet \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Oyster"}'
+# {"message":"Hello, Oyster!"}
+```
+
+Development runs a standalone Oyster on loopback with Wrangler. Save an edit in
+`src/` to rebuild the App and reload its page. The development host admits local
+requests as its owner; use the ordinary key-authenticated `oyster/worker.ts` for
+a deployed host, with `OYSTER_OWNER_KEY` as a secret and `OYSTER_ORIGIN` set to
+its public origin. Each App Instance records that origin when it is installed.
+The host serves `/mcp` (send `Authorization: Bearer $OYSTER_OWNER_KEY`) only for
+requests whose host matches `OYSTER_ORIGIN`; any other host gets a plain 404.
+
+The host Worker, Durable Objects, Worker Loader and Release assets run locally;
+state stays under `.wrangler/`. No Computer or container is configured. Computer
+files, shell commands, processes and port previews need an attached Computer.
+Team sign-in/grants and funded provider services are not emulated. See the
+[create-fungi-app quickstart](https://docs.fungi.computer/create-fungi-app/quickstart/)
+for the measured cold-start time and the local/hosted boundary.
+
+`src/backend/methods.ts` declares the method's input and output schemas and its
+handler. `src/backend/index.ts` exports the Durable Object facet. The
+`fungi.backendDefinition` manifest entry tells Oyster's builder where the
+definition lives; the builder derives the App's API and declaration from it and
+the manifest's `fungi.app`.
+
+```sh
+npm run build
+```
+
+This writes `dist/release.json` and `dist/artifacts/`. Build captures the
+current saved files into an isolated Git snapshot, including uncommitted edits;
+it does not modify your repository or create a customer commit. The Release's
+provenance names that exact snapshot. Dependency installation uses
+`package-lock.json`.
+
+To install the Release into an existing Oyster, set its URL and owner key, then
+use the ordinary Oyster CLI:
+
+```sh
+export OYSTER_URL=https://your-oyster.example
+export OYSTER_OWNER_KEY='<your owner key>'
+npx oyster install ./dist --installation-id my-app
+# The manifest path is also accepted:
+npx oyster install ./dist/release.json --installation-id my-app
+```
+
+Both forms use `installRelease` from `@fungi.computer/oyster/pack`: artifacts
+upload before the installation request. A failed upload or installation exits
+nonzero; the command does not provision or deploy an Oyster.
+
+For repository-driven authoring, commit the App's root `package.json` and its
+`fungi.build` recipe on main, push to a repository in Bonsai, then open its
+Settings and choose **Make this an App**. Registration reads committed metadata,
+not dirty working files, and does not build or install. Later accepted main
+pushes build that exact commit on an attached hosted backend. Successful builds
+may reuse existing approval; new permissions produce `needs_consent` and leave
+any previous Release running. Local-only Computers return `no_backend`.
+
+The same Release format is used by Fungi. Building creates the Release locally;
+it does not install or publish it.
+
+## Models and mascots
+
+When adding Quaternius art, add `@fungi.computer/art-library` and `three` as
+dependencies. Discover models through `@fungi.computer/art-library/models`: use
+`models` and `searchModels(models, query)` to find candidates, then
+`requireModel(models, id)` to pin a catalog ID rather than guessing filenames.
+
+Load the selected asset with `modelLoader()` from
+`@fungi.computer/art-library/three` and its `loadAsync(modelUrl)` method. This
+loader wires the Meshopt decoder needed by compressed models; a bare
+`GLTFLoader` does not.
+
+Include the chosen model (and any referenced buffers/textures) in the Release's
+built assets and use the emitted asset URL; the catalog row's `file` is not a
+public Oyster URL. Keep `fungi.build.assetBase` as `"./"` and URLs
+release-scoped under `/ui/<installation>/<release>/`. Resolve emitted relative
+paths against the App document base, for example
+`new URL("./assets/mascot.glb", document.baseURI).href` if that is the emitted
+path. Never hard-code `/models/...`: its leading slash escapes the Release
+prefix and requests an asset from the host root.

package/template/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.botanical/
+.wrangler/
+dist/
+.dev.vars

package/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en" data-theme="latte">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>My App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/oyster/worker.ts

@@ -0,0 +1,10 @@
+import { createOysterWorker } from "@fungi.computer/oyster/workers";
+// Every invocation frame mints its binding stubs from this one entrypoint.
+export {
+  OysterBinding,
+  OysterInstance,
+  OysterMcp,
+  OysterRegistry,
+  OysterInstallationExecutor,
+} from "@fungi.computer/oyster/workers";
+export default createOysterWorker();

package/template/oyster/wrangler.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "../node_modules/wrangler/config-schema.json",
+  "name": "my-app-oyster",
+  "main": "worker.ts",
+  "compatibility_date": "2026-09-04",
+  "compatibility_flags": ["nodejs_compat"],
+  "worker_loaders": [
+    {
+      "binding": "LOADER"
+    }
+  ],
+  "r2_buckets": [
+    {
+      "binding": "RELEASES",
+      "bucket_name": "app-releases"
+    }
+  ],
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "MCP",
+        "class_name": "OysterMcp"
+      },
+      {
+        "name": "REGISTRY",
+        "class_name": "OysterRegistry"
+      },
+      {
+        "name": "INSTANCES",
+        "class_name": "OysterInstance"
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["OysterRegistry", "OysterInstance", "OysterMcp"]
+    }
+  ]
+}

package/template/package.json

@@ -0,0 +1,58 @@
+{
+  "dependencies": {
+    "@fungi.computer/agar": "0.8.0",
+    "@fungi.computer/caps": "0.8.0",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "create-fungi-app": "0.0.2",
+    "@fungi.computer/oyster": "0.15.0",
+    "typescript": "5.9.3",
+    "@types/react": "18.3.3",
+    "@types/react-dom": "18.3.0",
+    "@cloudflare/workers-types": "5.20260828.1",
+    "wrangler": "4.127.1",
+    "vite": "8.2.2",
+    "@vitejs/plugin-react": "6.1.1"
+  },
+  "name": "my-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "fungi-app dev",
+    "build": "fungi-app build"
+  },
+  "fungi": {
+    "app": {
+      "displayName": "My App",
+      "capabilities": [],
+      "handlers": [],
+      "roles": []
+    },
+    "backendDefinition": "src/backend/methods.ts",
+    "build": {
+      "kind": "source-html",
+      "entry": "index.html",
+      "assetBase": "./",
+      "assets": {
+        "maxManifestBytes": 1048576,
+        "maxObjects": 1024,
+        "maxObjectBytes": 16777216,
+        "maxTotalBytes": 67108864
+      },
+      "maxOutputBytes": 67108864,
+      "backend": {
+        "entry": "src/backend/index.ts",
+        "exportName": "MyApp",
+        "compatibilityDate": "2026-09-04",
+        "runtime": {
+          "kind": "durable-facet",
+          "stateSchema": 1
+        }
+      }
+    }
+  }
+}

package/template/src/App.tsx

@@ -0,0 +1,49 @@
+import { useState } from "react";
+import type { AppRoot } from "@fungi.computer/agar";
+import { appMethods } from "@fungi.computer/agar/backend";
+import { Button } from "@fungi.computer/caps/components/button";
+import {
+  CardContent,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+  CenteredCard,
+} from "@fungi.computer/caps/components/card";
+import { greetingInput, greetingOutput } from "./backend/methods.js";
+
+export function App({ session }: { session: AppRoot }) {
+  const [message, setMessage] = useState("Your App is running inside Oyster.");
+  const [busy, setBusy] = useState(false);
+  const [failure, setFailure] = useState<Error | null>(null);
+  async function greet() {
+    setBusy(true);
+    setFailure(null);
+    try {
+      const result = await session.capabilities
+        .require(appMethods)
+        .call("greet", JSON.stringify(greetingInput.parse({ name: "friend" })));
+      setMessage(greetingOutput.parse(result).message);
+    } catch (cause) {
+      setFailure(
+        new Error("Could not reach the backend. Try again.", { cause }),
+      );
+    } finally {
+      setBusy(false);
+    }
+  }
+  return (
+    <CenteredCard>
+      <CardHeader>
+        <CardTitle level={2}>My App</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <p role="status">{failure?.message ?? message}</p>
+      </CardContent>
+      <CardFooter>
+        <Button loading={busy} disabled={busy} onClick={() => void greet()}>
+          Say hello
+        </Button>
+      </CardFooter>
+    </CenteredCard>
+  );
+}

package/template/src/backend/index.ts

@@ -0,0 +1,4 @@
+import { DurableObject } from "cloudflare:workers";
+import { appBackend } from "./methods.js";
+
+export const MyApp = appBackend.implement(class extends DurableObject {});

package/template/src/backend/methods.ts

@@ -0,0 +1,21 @@
+import * as z from "zod";
+import {
+  defineAppBackend,
+  defineAppMethod,
+} from "@fungi.computer/agar/backend-definition";
+
+export const greetingInput = z.object({ name: z.string().trim().min(1) });
+export const greetingOutput = z.object({ message: z.string() });
+
+export const appBackend = defineAppBackend({
+  methods: {
+    greet: defineAppMethod({
+      description: "Say hello",
+      effect: "read",
+      requires: [],
+      input: greetingInput,
+      output: greetingOutput,
+      handler: ({ name }) => ({ message: `Hello, ${name}!` }),
+    }),
+  },
+});

package/template/src/main.tsx

@@ -0,0 +1,13 @@
+import { connectApp } from "@fungi.computer/agar";
+import { createRoot } from "react-dom/client";
+import { App } from "./App.js";
+import "@fungi.computer/caps/styles.css";
+import "@fungi.computer/caps/fonts.css";
+
+const root = document.getElementById("app");
+if (root === null) throw new Error("App mount is missing.");
+const session = await connectApp({
+  host: "parent",
+});
+window.addEventListener("pagehide", () => session.dispose(), { once: true });
+createRoot(root).render(<App session={session} />);

package/template/tsconfig.backend.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src/backend", "oyster"]
+}

package/template/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "ESNext.Disposable"],
+    "types": [],
+    "strict": true,
+    "jsx": "react-jsx",
+    "noEmit": true
+  },
+  "include": ["src/App.tsx", "src/main.tsx", "src/backend/methods.ts"]
+}