@nanobpm/urban 0.52.0 → 0.54.0

package/dist/runtime/core/extensions.d.ts

@@ -0,0 +1,131 @@
+import type { AppApi, Mounted } from "./context.ts";
+import type { Logger } from "./logger.ts";
+import { EventBus, type Disposer, type DispatchMode, type EmitChannel, type ParallelChannel, type SerialChannel, type WaterfallChannel } from "./events.ts";
+export declare const URBAN_EVENT_MODES: {
+    /** Boot / start / stop notifications — observers never change the outcome. */
+    readonly lifecycle: "emit";
+    /** The ordered extension-registration checkpoint (this module's first consumer). */
+    readonly "extension/register": "serial";
+    /** Request / action dispatch — around-middleware for transform / short-circuit. */
+    readonly "request/dispatch": "waterfall";
+    /** Security / permission gate — a listener may short-circuit with a deny. */
+    readonly "security/gate": "waterfall";
+    /** Instance-tracking reconcile — fan-out where every listener gets its chance. */
+    readonly reconcile: "parallel";
+};
+export type UrbanEventName = keyof typeof URBAN_EVENT_MODES;
+/** A boot/start/stop lifecycle notification (the `lifecycle` emit seam). */
+export interface LifecycleEvent {
+    readonly app: string;
+    readonly phase: "starting" | "started" | "stopping" | "stopped";
+}
+/** The payload handed to each extension as it registers (the `extension/register`
+ *  serial seam): the just-registered extension plus its setup context. */
+export interface ExtensionRegistered {
+    readonly extension: string;
+    readonly context: ExtensionSetupContext;
+}
+/** A request/action flowing through the `request/dispatch` waterfall seam. An
+ *  extension middleware may transform it, short-circuit with a response, or
+ *  recover a downstream throw. Kept transport-agnostic on purpose. */
+export interface DispatchRequest {
+    readonly kind: string;
+    readonly payload: unknown;
+}
+export interface DispatchResponse {
+    readonly handled: boolean;
+    readonly payload: unknown;
+}
+/** A permission check flowing through the `security/gate` waterfall seam. A
+ *  listener that denies short-circuits (never calls `next`). */
+export interface GateRequest {
+    readonly subject: string;
+    readonly action: string;
+    readonly resource: string;
+}
+export interface GateDecision {
+    readonly allow: boolean;
+    readonly reason?: string;
+}
+/** A reconcile tick fanned out on the `reconcile` parallel seam. */
+export interface ReconcileEvent {
+    readonly source: string;
+    readonly at: number;
+}
+/** The typed Urban extension-event taxonomy: one channel per seam, each already
+ *  bound to its declared dispatch mode. Modules and extensions adopt seams by
+ *  registering on these channels; the dispatch semantics come from the channel,
+ *  not the call site. */
+export interface UrbanEvents {
+    /** **emit** — lifecycle notifications. */
+    readonly lifecycle: EmitChannel<LifecycleEvent>;
+    /** **serial** — the ordered extension-registration checkpoint. */
+    readonly extensionRegister: SerialChannel<ExtensionRegistered>;
+    /** **waterfall** — request/action dispatch middleware. */
+    readonly requestDispatch: WaterfallChannel<DispatchRequest, DispatchResponse>;
+    /** **waterfall** — security/permission gate (short-circuit deny). */
+    readonly securityGate: WaterfallChannel<GateRequest, GateDecision>;
+    /** **parallel** — instance-tracking reconcile fan-out. */
+    readonly reconcile: ParallelChannel<ReconcileEvent>;
+}
+/** Declare the whole Urban taxonomy on a bus — each seam exactly once, with the
+ *  mode `URBAN_EVENT_MODES` records for it. */
+export declare function createUrbanEvents(bus: EventBus): UrbanEvents;
+/** Assert (at construction) that the typed taxonomy and the documented mode table
+ *  agree — a guard against the two drifting apart. */
+export declare function urbanEventMode(name: UrbanEventName): DispatchMode;
+/** What an extension's `setup()` gets: the app API, the typed taxonomy to hook
+ *  onto, a structured logger, and `effect()` to hang any other disposable resource
+ *  (a timer, a subscription) on the dispose ladder. */
+export interface ExtensionSetupContext {
+    readonly app: AppApi;
+    readonly events: UrbanEvents;
+    readonly log: Logger;
+    /** Register a disposable effect (a timer, listener, subscription). It joins the
+     *  dispose ladder, so `stop()` / HMR tears it down with everything else. Returns
+     *  the idempotent disposer so an extension can clean up early — which also detaches
+     *  the effect from the ladder, so `stop()` won't run it a second time. */
+    effect(dispose: Disposer): Disposer;
+}
+/** A pluggable Urban extension — the uniform shape an agentic family or a
+ *  connector pack presents to the runtime. `setup()` wires the extension onto the
+ *  taxonomy; anything it registers is an effect on the dispose ladder. */
+export interface UrbanExtension {
+    readonly name: string;
+    /** Explicit ordering for the `extension/register` serial checkpoint; lower runs
+     *  first. Extensions with equal (or absent) order keep registration order. */
+    readonly order?: number;
+    setup(context: ExtensionSetupContext): void | Promise<void>;
+}
+export interface ExtensionHost extends Mounted {
+    /** The typed taxonomy this host mounted the extensions onto. */
+    readonly events: UrbanEvents;
+    /** Live registration count on the bus — proxies `EventBus.listenerCount`, so it
+     *  counts every channel listener AND every `effect()` on the dispose ladder, not
+     *  only channel listeners. 0 after a `stop()` that owns its bus. Use it for leak
+     *  assertions. */
+    readonly listenerCount: number;
+}
+export interface MountExtensionsOptions {
+    /** Reports a contained extension throw (defaults to the app logger's `warn`).
+     *  Only honoured when `mountExtensions` creates its *own* private bus (i.e. `bus`
+     *  and `events` are omitted). When a shared `bus` is passed, that bus already owns
+     *  its error sink and this option is ignored — set the sink on the shared bus. */
+    onError?: (err: unknown, info: {
+        event: string;
+        mode: DispatchMode;
+    }) => void;
+    /** A pre-built taxonomy/bus to mount onto (the runtime shares one app-wide). When
+     *  omitted a private bus is created — handy for isolated tests. */
+    bus?: EventBus;
+    events?: UrbanEvents;
+}
+/** Run `extensions` through the taxonomy: deterministically order them, `setup()`
+ *  each directly (a throwing extension is contained and never strands the others
+ *  or app boot), then notify the `extension/register` serial checkpoint so
+ *  observers react in a deterministic order, and return a `Mounted` whose `stop()`
+ *  disposes the bus — unwinding the whole dispose ladder LIFO — only when
+ *  `mountExtensions` created that bus; onto a shared app-wide bus, disposal is the
+ *  caller's responsibility. So a start→stop→start cycle (or HMR reload) over an
+ *  owned bus leaks no listeners. */
+export declare function mountExtensions(api: AppApi, extensions: readonly UrbanExtension[], options?: MountExtensionsOptions): Promise<ExtensionHost>;

package/dist/runtime/core/extensions.js

@@ -0,0 +1,137 @@
+// extensions — the typed Urban **extension-event taxonomy** and the extension host
+// that runs the agentic-family / connector-pack surface through it (issue #262).
+//
+// `runtime.ts` used to wire every module directly and let extensions reach for
+// whatever they needed; ordering and failure-isolation were implicit. This module
+// formalizes the extension seams as a small set of **typed channels**, each with a
+// declared dispatch mode (see `events.ts`), and gives extensions a single, uniform
+// way to plug in: a `UrbanExtension` whose `setup()` registers listeners and
+// disposable effects onto the app's dispose ladder.
+//
+// The first concrete consumer is exactly the informal plugin surface Urban already
+// stresses today: nwf's agentic families ("drop a family module under
+// `app/agentic/families/`, never edit `main.ts`") and connector packs. Each becomes
+// a `UrbanExtension`; the runtime runs them through the `extension/register` serial
+// checkpoint in a deterministic order, and everything they register tears down on
+// `stop()` / dev-server HMR because it rode the dispose ladder.
+import { EventBus, } from "./events.js";
+// ---------------------------------------------------------------------------
+// The taxonomy — the documented set of typed Urban extension events.
+//
+// Each seam is a canonical event *name* paired with its deliberate *dispatch
+// mode*. This object is the single source of truth for the modes; the ADR's
+// "feature → mechanism map" and the typed `UrbanEvents` channels below are both
+// checked against it — `createUrbanEvents` enumerates the seams by hand, but a
+// drift-guard test asserts every channel's `.mode` equals `URBAN_EVENT_MODES`
+// for its seam (and that coverage is exact), so the docs and the code cannot
+// silently drift.
+// ---------------------------------------------------------------------------
+export const URBAN_EVENT_MODES = {
+    /** Boot / start / stop notifications — observers never change the outcome. */
+    "lifecycle": "emit",
+    /** The ordered extension-registration checkpoint (this module's first consumer). */
+    "extension/register": "serial",
+    /** Request / action dispatch — around-middleware for transform / short-circuit. */
+    "request/dispatch": "waterfall",
+    /** Security / permission gate — a listener may short-circuit with a deny. */
+    "security/gate": "waterfall",
+    /** Instance-tracking reconcile — fan-out where every listener gets its chance. */
+    "reconcile": "parallel",
+};
+/** Declare the whole Urban taxonomy on a bus — each seam exactly once, with the
+ *  mode `URBAN_EVENT_MODES` records for it. */
+export function createUrbanEvents(bus) {
+    return {
+        lifecycle: bus.emit("lifecycle"),
+        extensionRegister: bus.serial("extension/register"),
+        requestDispatch: bus.waterfall("request/dispatch"),
+        securityGate: bus.waterfall("security/gate"),
+        reconcile: bus.parallel("reconcile"),
+    };
+}
+/** Assert (at construction) that the typed taxonomy and the documented mode table
+ *  agree — a guard against the two drifting apart. */
+export function urbanEventMode(name) {
+    return URBAN_EVENT_MODES[name];
+}
+/** Run `extensions` through the taxonomy: deterministically order them, `setup()`
+ *  each directly (a throwing extension is contained and never strands the others
+ *  or app boot), then notify the `extension/register` serial checkpoint so
+ *  observers react in a deterministic order, and return a `Mounted` whose `stop()`
+ *  disposes the bus — unwinding the whole dispose ladder LIFO — only when
+ *  `mountExtensions` created that bus; onto a shared app-wide bus, disposal is the
+ *  caller's responsibility. So a start→stop→start cycle (or HMR reload) over an
+ *  owned bus leaks no listeners. */
+export async function mountExtensions(api, extensions, options = {}) {
+    const log = api.log.child({ module: "extensions" });
+    // Share a caller-owned bus+taxonomy or build a private pair — never a mismatched
+    // one. With only `events`, listeners would register on its bus while `effect()`
+    // and disposal target a *different* private bus (leaked registrations, and a
+    // reused bus could redeclare channels); with only `bus`, callers lose the typed
+    // taxonomy they meant to share. Require both-or-neither.
+    if ((options.bus === undefined) !== (options.events === undefined)) {
+        throw new Error("mountExtensions: `bus` and `events` must be provided together or both omitted");
+    }
+    // Ownership: a bus we created is ours to dispose; a shared app-wide bus belongs
+    // to the caller (the runtime disposes it in teardown). `stop()` honours this so
+    // it never unwinds registrations it did not make.
+    const ownsBus = options.bus === undefined;
+    const bus = options.bus ??
+        new EventBus({
+            onError: options.onError ??
+                ((err, info) => log.warn("extension listener threw and was contained", { event: info.event, mode: info.mode, error: String(err) })),
+        });
+    const events = options.events ?? createUrbanEvents(bus);
+    // Deterministic order: primary by `order` (default 0), stable within ties by the
+    // order the host handed them to us. A sibling dropping a family module gets a
+    // predictable slot without editing anyone else's registration.
+    const ordered = extensions
+        .map((extension, index) => ({ extension, index }))
+        .sort((a, b) => (a.extension.order ?? 0) - (b.extension.order ?? 0) || a.index - b.index)
+        .map((entry) => entry.extension);
+    const context = {
+        app: api,
+        events,
+        log,
+        effect(dispose) {
+            return bus.effect(dispose);
+        },
+    };
+    for (const extension of ordered) {
+        // `setup()` is the checkpoint's unit of work, made atomic by a per-extension
+        // rollback scope: a throw is contained here so one bad extension never strands
+        // app boot or its siblings, AND its partial registrations are rolled back so a
+        // "failed" extension can't leave live listeners/effects that influence later
+        // dispatches or leak on teardown.
+        const rollback = bus.scope();
+        try {
+            await extension.setup(context);
+        }
+        catch (err) {
+            rollback();
+            log.warn("extension setup threw and was contained", { extension: extension.name, error: String(err) });
+            continue;
+        }
+        // Notify the ordered `extension/register` serial checkpoint so observers react
+        // in a deterministic order (also contained, per `SerialChannel.run`).
+        await events.extensionRegister.run({ extension: extension.name, context });
+        log.info("extension mounted", { extension: extension.name });
+    }
+    return {
+        name: "extensions",
+        events,
+        get listenerCount() {
+            return bus.listenerCount;
+        },
+        async stop() {
+            // Only dispose a bus we own. When the runtime shares its app-wide bus, tearing
+            // it down here would unwind unrelated core registrations — disposal is then the
+            // owner's job (runtime teardown calls `bus.dispose()`).
+            if (ownsBus)
+                bus.dispose();
+        },
+        describe() {
+            return { extensions: ordered.map((e) => e.name), listeners: bus.listenerCount };
+        },
+    };
+}

package/dist/runtime/core/glob.d.ts

@@ -4,11 +4,12 @@ export declare function expandPattern(host: HostContext, root: string, pattern:
 /** Expand many patterns, de-duplicating while preserving first-seen order. */
 export declare function expandPatterns(host: HostContext, root: string, patterns: string[] | undefined): Promise<string[]>;
 /**
- * Discover deployables under a convention directory (`resources/`), **shallow, one level deep**:
- * the files directly under `dir` plus the files one sub-directory down (`dir/<subdir>/*`), but
- * never deeper. The shallow bound is deliberate — deploy dedupes by basename (filename only), so a
- * deep recursive walk would reintroduce cross-directory basename-collision risk. Sub-directory
- * descent needs `host.listSubdirs`; a host that can't enumerate directories yields only the
- * top-level files. Returns root-prefixed paths, sorted for determinism.
+ * Discover deployables under a convention directory (`resources/`), **recursively** — every file
+ * directly under `dir` and under every sub-directory at any depth (issue #231). Recursive descent
+ * is safe because deploy now keys a convention resource by its path *relative to* `resources/`
+ * (POSIX), not its bare basename, so two files sharing a filename in different sub-dirs
+ * (`a/x.md`, `b/x.md`) resolve to distinct `resourceId`s and can never collide. Descent needs
+ * `host.listSubdirs`; a host that can't enumerate directories yields only the top-level files.
+ * Returns root-prefixed paths, sorted for determinism.
  */
 export declare function discoverResources(host: HostContext, root: string, dir: string): Promise<string[]>;

package/dist/runtime/core/glob.js

@@ -50,23 +50,25 @@ export async function expandPatterns(host, root, patterns) {
     return out;
 }
 /**
- * Discover deployables under a convention directory (`resources/`), **shallow, one level deep**:
- * the files directly under `dir` plus the files one sub-directory down (`dir/<subdir>/*`), but
- * never deeper. The shallow bound is deliberate — deploy dedupes by basename (filename only), so a
- * deep recursive walk would reintroduce cross-directory basename-collision risk. Sub-directory
- * descent needs `host.listSubdirs`; a host that can't enumerate directories yields only the
- * top-level files. Returns root-prefixed paths, sorted for determinism.
+ * Discover deployables under a convention directory (`resources/`), **recursively** — every file
+ * directly under `dir` and under every sub-directory at any depth (issue #231). Recursive descent
+ * is safe because deploy now keys a convention resource by its path *relative to* `resources/`
+ * (POSIX), not its bare basename, so two files sharing a filename in different sub-dirs
+ * (`a/x.md`, `b/x.md`) resolve to distinct `resourceId`s and can never collide. Descent needs
+ * `host.listSubdirs`; a host that can't enumerate directories yields only the top-level files.
+ * Returns root-prefixed paths, sorted for determinism.
  */
 export async function discoverResources(host, root, dir) {
     const base = joinPath(root, dir);
     const out = [];
-    for (const name of await host.listDir(base))
-        out.push(joinPath(base, name));
-    const subdirs = host.listSubdirs ? await host.listSubdirs(base) : [];
-    for (const sub of subdirs.slice().sort()) {
-        const subBase = joinPath(base, sub);
-        for (const name of await host.listDir(subBase))
-            out.push(joinPath(subBase, name));
-    }
+    const walk = async (current) => {
+        for (const name of await host.listDir(current))
+            out.push(joinPath(current, name));
+        const subdirs = host.listSubdirs ? await host.listSubdirs(current) : [];
+        for (const sub of subdirs.slice().sort()) {
+            await walk(joinPath(current, sub));
+        }
+    };
+    await walk(base);
     return out.sort();
 }

package/dist/runtime/core/host.d.ts

@@ -233,7 +233,10 @@ export interface FormSchema {
  * it against a live engine; tests implement it in-memory. Core modules depend only on this.
  */
 export interface EngineClient {
-    /** Deploy model resources (BPMN/DMN/forms). Returns the number deployed. */
+    /** Deploy model resources (BPMN/DMN/forms) and generic resources (prompts, scripts, and other
+     *  arbitrary files, content-typed e.g. `text/markdown`/`application/octet-stream`; the engine
+     *  versions each generic resource per its `resourceId` — carried on `name`). Returns the number
+     *  deployed. */
     deployResources(resources: {
         name: string;
         content: string;

package/dist/runtime/core/modules/agent.d.ts

@@ -0,0 +1,17 @@
+import type { RuntimeContext } from "../context.ts";
+import { type Route } from "../router.ts";
+export interface AgentHandle {
+    readonly name: string;
+    routes: Route[];
+    describe(): Record<string, unknown>;
+}
+/**
+ * Mount the `/app/agent` (+ `/app/agent.json`) institutional-memory brief routes. Reads the
+ * `urban gen`-derived artifacts through the host file port, resolving each under `ctx.root` via
+ * the shared `resolveAppPath` (like every other runtime module) so serving never depends on the
+ * host's current working directory. A genuinely absent artifact — checked with `host.exists`
+ * rather than a blanket catch — yields a 404 (gen never ran, or the app has no models); any other
+ * read failure (permissions, transient I/O) is left to surface as a 500 rather than being masked
+ * as "not generated".
+ */
+export declare function mountAgent(ctx: RuntimeContext): AgentHandle;

package/dist/runtime/core/modules/agent.js

@@ -0,0 +1,63 @@
+// agent — the app-scoped institutional-memory brief surface (ADR 0060 §2). The app-level mirror
+// of the node `/agent` brief (ADR 0051): where the node brief describes the whole runtime, this
+// serves ONE app's derived `system-brief.md` / `system-brief.json` so an agent (or human) opening
+// work on the app starts grounded in the app's own system model — its processes, service-task call
+// graph, decisions, and ownership.
+//
+//   GET /app/agent       → nano-generated/system-brief.md   (text/markdown)
+//   GET /app/agent.json  → nano-generated/system-brief.json (application/json)
+//
+// The brief is derived by `urban gen` (systemBriefDeriver, wired in gen.ts) into the app's
+// `nano-generated/` dir, so this route is a thin read-through of that artifact — no re-derivation
+// at request time (the derived file is the single source of truth, kept honest by
+// `urban gen --check`). Mounted unconditionally: the brief is a property of the app's models, not
+// of any opt-in surface, so it is always addressable when a brief has been generated. An app whose
+// models produced no brief (never ran gen) returns 404.
+import { GENERATED_DIR } from "../../../toolkit/artifact.js";
+import { SYSTEM_BRIEF_JSON, SYSTEM_BRIEF_MD } from "../../../toolkit/derivers/system-brief.js";
+import { json } from "../router.js";
+import { resolveAppPath } from "./datasource.js";
+/** The app-relative path of a generated brief artifact. */
+const briefPath = (name) => `${GENERATED_DIR}/${name}`;
+function markdown(body) {
+    return { status: 200, headers: { "content-type": "text/markdown; charset=utf-8" }, body };
+}
+/**
+ * Mount the `/app/agent` (+ `/app/agent.json`) institutional-memory brief routes. Reads the
+ * `urban gen`-derived artifacts through the host file port, resolving each under `ctx.root` via
+ * the shared `resolveAppPath` (like every other runtime module) so serving never depends on the
+ * host's current working directory. A genuinely absent artifact — checked with `host.exists`
+ * rather than a blanket catch — yields a 404 (gen never ran, or the app has no models); any other
+ * read failure (permissions, transient I/O) is left to surface as a 500 rather than being masked
+ * as "not generated".
+ */
+export function mountAgent(ctx) {
+    const artifactPath = (name) => resolveAppPath(ctx.root, briefPath(name));
+    const notGenerated = () => json({ error: "system brief not generated — run `urban gen`" }, 404);
+    const serve = async (name, toResponse) => {
+        const path = artifactPath(name);
+        if (!(await ctx.host.exists(path)))
+            return notGenerated();
+        return toResponse(await ctx.host.readTextFile(path));
+    };
+    const routes = [
+        {
+            method: "GET",
+            path: "/app/agent",
+            source: "surface:agent",
+            handler: () => serve(SYSTEM_BRIEF_MD, markdown),
+        },
+        {
+            method: "GET",
+            path: "/app/agent.json",
+            source: "surface:agent",
+            handler: () => serve(SYSTEM_BRIEF_JSON, (body) => ({
+                status: 200,
+                headers: { "content-type": "application/json" },
+                body,
+            })),
+        },
+    ];
+    ctx.host.log("info", "agent brief surface mounted", { routes: routes.length });
+    return { name: "agent", routes, describe: () => ({ routes: routes.map((r) => r.path) }) };
+}

package/dist/runtime/core/modules/deploy.d.ts

@@ -1,12 +1,15 @@
 import type { RuntimeContext } from "../context.ts";
-/** The convention directory: deploy-only, walked one level deep when no `models` are declared. */
+/** The convention directory: deploy-only, walked recursively when no `models` are declared. */
 export declare const RESOURCES_DIR = "resources";
 /**
- * Deploy the app's processes, decisions and forms.
+ * Deploy the app's resources.
  *
- * With no manifest `models`, deployables are discovered by convention under `resources/` (shallow,
- * one level deep). With `models` globs declared, those are used verbatim. Basename collisions are a
- * hard error in either mode.
+ * With no manifest `models`, deployables are discovered by convention under `resources/`
+ * (recursively — every file at any depth) and each is keyed by its path relative to `resources/`
+ * (POSIX). With `models` globs declared, those are used verbatim and keyed by basename (a basename
+ * collision is a hard error). Content is deployed verbatim (no template substitution); each file is
+ * content-typed by extension so a generic resource (e.g. a prompt `.md`) deploys as a versioned
+ * generic resource the engine resolves via `zeebe:linkedResource bindingType:latest`.
  */
 export declare function deployModels(ctx: RuntimeContext): Promise<{
     deployed: number;

package/dist/runtime/core/modules/deploy.js

@@ -2,18 +2,42 @@
 //
 // Resources are found by ONE of two paths:
 //   1. Convention (the default, ADR 0062): when the manifest declares no `models`, deployables are
-//      discovered by walking `resources/` — shallow, one level deep. `resources/` is deploy-only:
-//      everything under it (and nothing outside it) is deployed. Docs (`docs/`, `AGENTS.md`,
-//      top-level `*.md`) live outside `resources/` and are never swept in.
+//      discovered by walking `resources/` **recursively** — every file under it, at any depth
+//      (issue #231). `resources/` is deploy-only: everything under it (and nothing outside it) is
+//      deployed. Docs (`docs/`, `AGENTS.md`, top-level `*.md`) live outside `resources/` and are
+//      never swept in. A convention resource's deploy key (`resourceId`) is its path **relative to
+//      `resources/`** (POSIX-normalised), e.g. `resources/prompts/plan.md` → `prompts/plan.md`, so
+//      a linked service task references it with `zeebe:linkedResource resourceId="prompts/plan.md"`.
+//      The relative path (not the bare basename) preserves sub-directory structure and lets two
+//      files sharing a filename in different sub-dirs (`a/x.md`, `b/x.md`) deploy as distinct
+//      resources — there is no basename-collision hazard.
 //   2. Explicit override: when the manifest declares `models` globs, those are used exactly (the
-//      convention walk is skipped) — the escape hatch for a non-convention layout.
+//      convention walk is skipped) — the escape hatch for a non-convention layout. Override
+//      resources are keyed by basename (filename only), so a basename collision across the declared
+//      globs is a hard error, detected up front.
 //
-// Either way the deploy dedupe key is the resource's basename (filename only), so a basename
-// collision — two files with the same name in different directories — would silently clobber one
-// resource with another at the engine. We detect that up front and fail loudly instead.
+// Content is deployed **verbatim** — there is no deploy-time `{{token}}` substitution (removed in
+// ADR 0062) — so a generic resource (a prompt `.md`, an RPA/script file) is deployed as-is.
+// The deploy pipeline is **UTF-8 text only**, end-to-end: `host.readTextFile()` yields a `string`
+// and the engine's `deployResources` takes `content: string`, so there is no byte channel and
+// arbitrary binary is out of scope by design. "Verbatim" therefore means the UTF-8 text is passed
+// through unchanged; a non-UTF-8/binary file swept into `resources/` is not a supported input (see
+// `contentTypeFor`'s `application/octet-stream` note).
 import { discoverResources, expandPatterns } from "../glob.js";
-/** The convention directory: deploy-only, walked one level deep when no `models` are declared. */
+/** The convention directory: deploy-only, walked recursively when no `models` are declared. */
 export const RESOURCES_DIR = "resources";
+/**
+ * Classify a file into an engine content type by extension. Models get their real XML/JSON types;
+ * generic resources get a real text content type where the extension is known (`.md`, `.json`,
+ * `.txt`), falling back to `application/octet-stream` for anything unrecognised (so an unknown
+ * extension is never mislabelled as a specific text type). Note the deploy pipeline is UTF-8 text
+ * only (`readTextFile` → engine `content: string`): the `octet-stream` fallback is a conservative
+ * MIME label for an unrecognised *text* resource (e.g. a script with an uncommon extension), not a
+ * promise of binary fidelity — a genuinely binary file cannot be preserved byte-for-byte and is
+ * out of scope. The engine deploys a non-model content type as a generic resource
+ * (versioned per `resourceId`); a service task resolves it via
+ * `zeebe:linkedResource resourceId="<id>" bindingType:latest`.
+ */
 function contentTypeFor(path) {
     if (path.endsWith(".bpmn"))
         return "text/xml";
@@ -21,14 +45,30 @@ function contentTypeFor(path) {
         return "text/xml";
     if (path.endsWith(".form"))
         return "application/json";
+    if (path.endsWith(".md"))
+        return "text/markdown";
+    if (path.endsWith(".json"))
+        return "application/json";
+    if (path.endsWith(".txt"))
+        return "text/plain";
     return "application/octet-stream";
 }
 function baseName(path) {
     const i = path.lastIndexOf("/");
     return i >= 0 ? path.slice(i + 1) : path;
 }
-/** Fail loudly when two resolved files share a basename (the deploy dedupe key), naming the
- *  colliding paths so the author can rename or relocate one. */
+/**
+ * A convention resource's `resourceId`: its path relative to `<root>/resources/` (POSIX). Given a
+ * root-prefixed discovered path (`/app/resources/prompts/plan.md`) it returns `prompts/plan.md`.
+ * Falls back to the basename if — defensively — the path is not under the resources prefix.
+ */
+function relativeResourceId(path, root) {
+    const prefix = `${root.replace(/\/+$/, "")}/${RESOURCES_DIR}/`;
+    return path.startsWith(prefix) ? path.slice(prefix.length) : baseName(path);
+}
+/** Fail loudly when two resolved files share a basename (the override dedupe key), naming the
+ *  colliding paths so the author can rename or relocate one. Only relevant for the `models`
+ *  override path; convention resources are keyed by relative path and cannot collide. */
 function assertNoBasenameCollisions(files) {
     const byName = new Map();
     for (const path of files) {
@@ -49,11 +89,14 @@ function assertNoBasenameCollisions(files) {
         `the same name would clobber each other. Rename or relocate one of:\n${detail}`);
 }
 /**
- * Deploy the app's processes, decisions and forms.
+ * Deploy the app's resources.
  *
- * With no manifest `models`, deployables are discovered by convention under `resources/` (shallow,
- * one level deep). With `models` globs declared, those are used verbatim. Basename collisions are a
- * hard error in either mode.
+ * With no manifest `models`, deployables are discovered by convention under `resources/`
+ * (recursively — every file at any depth) and each is keyed by its path relative to `resources/`
+ * (POSIX). With `models` globs declared, those are used verbatim and keyed by basename (a basename
+ * collision is a hard error). Content is deployed verbatim (no template substitution); each file is
+ * content-typed by extension so a generic resource (e.g. a prompt `.md`) deploys as a versioned
+ * generic resource the engine resolves via `zeebe:linkedResource bindingType:latest`.
  */
 export async function deployModels(ctx) {
     const models = ctx.manifest.models;
@@ -79,9 +122,12 @@ export async function deployModels(ctx) {
         }
         return { deployed: 0, files: [] };
     }
-    assertNoBasenameCollisions(files);
+    // Convention resources are keyed by their (unique) relative path; only the override path, whose
+    // basename key can collide across globs, needs the collision guard.
+    if (!byConvention)
+        assertNoBasenameCollisions(files);
     const resources = await Promise.all(files.map(async (path) => ({
-        name: baseName(path),
+        name: byConvention ? relativeResourceId(path, ctx.root) : baseName(path),
         content: await ctx.host.readTextFile(path),
         contentType: contentTypeFor(path),
     })));