@intentius/chant-lexicon-fountain 0.33.0

package/src/plugin.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { fountainPlugin } from "./plugin";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+
+describe("fountain plugin", () => {
+  it("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(fountainPlugin)).toBe(true);
+  });
+
+  it("has the correct name", () => {
+    expect(fountainPlugin.name).toBe("fountain");
+  });
+
+  it("has a serializer", () => {
+    expect(fountainPlugin.serializer).toBeDefined();
+  });
+
+  it("namespaces its MCP tool so it can load beside other lexicons", () => {
+    const tools = fountainPlugin.mcpTools?.() ?? [];
+    expect(tools.map((t) => t.name)).toEqual(["fountain:diff"]);
+  });
+
+  it("serves the resource catalog over MCP", async () => {
+    const resources = fountainPlugin.mcpResources?.() ?? [];
+    expect(resources.map((r) => r.uri)).toEqual(["fountain:resource-catalog"]);
+
+    const catalog = JSON.parse(await resources[0].handler()) as Array<{
+      className: string;
+      kind: string;
+    }>;
+    const resourceKinds = catalog.filter((e) => e.kind === "resource").map((e) => e.className);
+    expect(resourceKinds.sort()).toEqual(["Agent", "Environment", "Vault"]);
+  });
+
+  it("exposes every post-synth check and lint rule", () => {
+    expect(fountainPlugin.lintRules?.()).toHaveLength(1);
+    expect(fountainPlugin.postSynthChecks?.()).toHaveLength(8);
+  });
+
+  it("carries audit metadata for every rule it ships", () => {
+    const catalog = fountainPlugin.auditCatalog?.() ?? {};
+    const ruleIds = [
+      ...(fountainPlugin.lintRules?.() ?? []).map((r) => r.id),
+      ...(fountainPlugin.postSynthChecks?.() ?? []).map((c) => c.id),
+    ];
+
+    expect(ruleIds.sort()).toEqual(Object.keys(catalog).sort());
+  });
+
+  it("marks its checks entity-based so audit does not claim they fire on YAML", () => {
+    const catalog = fountainPlugin.auditCatalog?.() ?? {};
+    // Every fountain check reads ctx.entities, so none can fire against
+    // standalone fountain YAML. Flipping one to true would misreport it.
+    expect(Object.values(catalog).every((m) => m.yamlBased === false)).toBe(true);
+  });
+
+  it("scaffolds a closed sandbox by default", () => {
+    const def = fountainPlugin.initTemplates?.()?.src["fountain.ts"] ?? "";
+    expect(def).toContain("ConciergeStack");
+
+    const open = fountainPlugin.initTemplates?.("open")?.src["fountain.ts"] ?? "";
+    expect(open).toContain("networking_type");
+    expect(open).not.toContain("ConciergeStack");
+  });
+
+  it("loads all three skills", () => {
+    expect(fountainPlugin.skills?.().map((s) => s.name).sort()).toEqual([
+      "chant-fountain",
+      "chant-fountain-locked-sandboxes",
+      "chant-fountain-secrets",
+    ]);
+  });
+});

package/src/plugin.ts

@@ -0,0 +1,170 @@
+import type { LexiconPlugin, SkillDefinition, IntrinsicDef } from "@intentius/chant/lexicon";
+import type { LintRule } from "@intentius/chant/lint/rule";
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import type { CompletionContext, CompletionItem, HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import type { McpToolContribution, McpResourceContribution } from "@intentius/chant/mcp/types";
+import {
+  createSkillsLoader,
+  createDiffTool,
+  createCatalogResource,
+} from "@intentius/chant/lexicon-plugin-helpers";
+import { fountainSerializer } from "./serializer";
+import { rules } from "./lint/rules";
+import { postSynthChecks } from "./lint/post-synth";
+import { fountainAuditCatalog } from "./lint/audit-catalog";
+import { fountainReferenceCatalog } from "./reference-catalog";
+import { detectFountainTemplate } from "./detect";
+import { fountainInitTemplates } from "./init-templates";
+import { FountainParser } from "./import/parser";
+import { FountainGenerator } from "./import/generator";
+import { completions } from "./lsp/completions";
+import { hover } from "./lsp/hover";
+
+/**
+ * fountain lexicon plugin.
+ *
+ * Implements all required LexiconPlugin lifecycle methods.
+ */
+export const fountainPlugin: LexiconPlugin = {
+  name: "fountain",
+  serializer: fountainSerializer,
+
+  // ── Required lifecycle methods ────────────────────────────────
+
+  async generate(options?: { verbose?: boolean }): Promise<void> {
+    const { generate } = await import("./codegen/generate");
+    await generate(options);
+  },
+
+  async validate(options?: { verbose?: boolean }): Promise<void> {
+    const { validate } = await import("./validate");
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    const result = await validate();
+    printValidationResult(result);
+  },
+
+  async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    const { analyzeFountainCoverage } = await import("./coverage");
+    await analyzeFountainCoverage(options);
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const { spec, stats } = await packageLexicon(options);
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    writeBundleSpec(spec, join(pkgDir, "dist"));
+
+    console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+  },
+
+  // ── Optional extensions ────────────────────────────────────
+
+  lintRules() {
+    return rules;
+  },
+
+  postSynthChecks() {
+    return postSynthChecks;
+  },
+
+  auditCatalog: () => fountainAuditCatalog,
+
+  skills: createSkillsLoader(import.meta.url, [
+    {
+      file: "chant-fountain.md",
+      name: "chant-fountain",
+      description:
+        "Declare, lint, and reconcile fountain Environments, Vaults, and Agents from a chant project",
+      triggers: [
+        { type: "context" as const, value: "fountain" },
+        { type: "context" as const, value: "founta.inevitable.fyi" },
+      ],
+    },
+    {
+      file: "chant-fountain-secrets.md",
+      name: "chant-fountain-secrets",
+      description: "Handle fountain secrets, env vars, and ${VAR} substitution safely from chant",
+      triggers: [
+        { type: "context" as const, value: "fountain secrets" },
+        { type: "context" as const, value: "vault" },
+      ],
+    },
+    {
+      file: "chant-fountain-locked-sandboxes.md",
+      name: "chant-fountain-locked-sandboxes",
+      description:
+        "Declare locked-down fountain environments for untrusted agents and run conversations against them",
+      triggers: [
+        { type: "context" as const, value: "sandbox" },
+        { type: "context" as const, value: "networking_type" },
+      ],
+    },
+  ]),
+
+  mcpTools(): McpToolContribution[] {
+    return [
+      createDiffTool(
+        fountainSerializer,
+        "Compare current fountain build output (fountain manifests + fountain-plan.json) against previous version",
+        "fountain",
+      ),
+    ];
+  },
+
+  mcpResources(): McpResourceContribution[] {
+    return [
+      createCatalogResource(
+        import.meta.url,
+        "Fountain Resource Types",
+        "The three fountain workload kinds declarable from chant: Environment, Vault, Agent (conversations are runs, started by the fountainRun op)",
+        "lexicon-fountain.json",
+        "fountain",
+      ),
+    ];
+  },
+
+  initTemplates(template?: string) {
+    return fountainInitTemplates(template);
+  },
+
+  detectTemplate(data: unknown) {
+    return detectFountainTemplate(data);
+  },
+
+  templateParser() {
+    return new FountainParser();
+  },
+
+  templateGenerator() {
+    return new FountainGenerator();
+  },
+
+  async exportResources(options) {
+    const { exportResources } = await import("./export-resources");
+    return exportResources(options);
+  },
+
+  async describeResources(options) {
+    const { describeResources } = await import("./describe-resources");
+    return describeResources(options);
+  },
+
+  referenceCatalog: fountainReferenceCatalog,
+
+  completionProvider(ctx: CompletionContext) {
+    return completions(ctx);
+  },
+
+  hoverProvider(ctx: HoverContext) {
+    return hover(ctx);
+  },
+
+  async docs(options?) {
+    const { generateDocs } = await import("./codegen/docs");
+    return generateDocs(options);
+  },
+};

package/src/reference-catalog.ts

@@ -0,0 +1,27 @@
+import type { ReferenceCatalog } from "@intentius/chant/lexicon";
+
+/**
+ * Fountain reference catalog — how observed fountain resources reference
+ * each other, so `chant graph --live` reconstructs the topology.
+ *
+ * One relationship matters: an Agent runs in an Environment
+ * (`environment_id`). `describeResources` puts `environment_id` in the
+ * agent's observed attributes and indexes environments by `id` (their
+ * physicalId), so the edge resolves with no enrichment pass.
+ *
+ * Vaults are deliberately edge-free here: vault↔agent binding is a
+ * conversation-time choice (scoped by `allowed_vault_ids`), not standing
+ * topology.
+ */
+export const fountainReferenceCatalog: ReferenceCatalog = {
+  identities: [{ kind: "Fountain::V1::Environment", ids: ["id"] }],
+  refs: [
+    {
+      from: "Fountain::V1::Agent",
+      path: "environment_id",
+      targetKind: "Fountain::V1::Environment",
+      relation: "reference",
+      label: "environment",
+    },
+  ],
+};

package/src/serializer.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import { fountainSerializer } from "./serializer";
+import type { Declarable } from "@intentius/chant";
+
+function primary(result: unknown): string {
+  return typeof result === "string" ? result : (result as { primary: string }).primary;
+}
+
+function entity(entityType: string, props: Record<string, unknown>): Declarable {
+  return { entityType, lexicon: "fountain", ...props } as unknown as Declarable;
+}
+
+describe("fountain serializer", () => {
+  it("has the correct name and rule prefix", () => {
+    expect(fountainSerializer.name).toBe("fountain");
+    expect(fountainSerializer.rulePrefix).toBe("FTN");
+  });
+
+  it("serializes an empty map to an empty string", () => {
+    expect(fountainSerializer.serialize(new Map())).toBe("");
+  });
+
+  it("emits the fountain-plan.json sidecar for the applier", () => {
+    const env = entity("Fountain::V1::Environment", { name: "e" });
+    const result = fountainSerializer.serialize(new Map([["e", env]]));
+    expect(typeof result).toBe("object");
+    const files = (result as { files: Record<string, string> }).files;
+    const plan = JSON.parse(files["fountain-plan.json"]);
+    expect(plan.e.kind).toBe("Environment");
+  });
+
+  it("emits a fountain manifest per entity", () => {
+    const env = entity("Fountain::V1::Environment", {
+      name: "concierge-env",
+      networking_type: "limited",
+      networking_config: { allowed_hosts: ["github.com"] },
+    });
+
+    const out = primary(fountainSerializer.serialize(new Map([["conciergeEnv", env]])));
+
+    expect(out).toContain("apiVersion: fountain.dev/v1");
+    expect(out).toContain("kind: Environment");
+    expect(out).toContain("name: conciergeEnv");
+    expect(out).toContain("networking_type: limited");
+    expect(out).toContain("allowed_hosts:");
+    expect(out).toContain("- github.com");
+  });
+
+  it("separates multiple entities with document markers", () => {
+    const env = entity("Fountain::V1::Environment", { name: "e" });
+    const vault = entity("Fountain::V1::Vault", { name: "v" });
+
+    const out = primary(
+      fountainSerializer.serialize(
+        new Map([
+          ["env", env],
+          ["vault", vault],
+        ]),
+      ),
+    );
+
+    expect(out).toContain("---\n");
+    expect(out).toContain("kind: Environment");
+    expect(out).toContain("kind: Vault");
+  });
+
+  it("resolves a cross-resource reference to the referenced entity name", () => {
+    const env = entity("Fountain::V1::Environment", { name: "concierge-env" });
+    const agent = entity("Fountain::V1::Agent", {
+      name: "researcher",
+      model: "anthropic/claude-sonnet-4-6",
+      runtime: "claude",
+      environment: env,
+    });
+
+    const out = primary(
+      fountainSerializer.serialize(
+        new Map([
+          ["conciergeEnv", env],
+          ["researcher", agent],
+        ]),
+      ),
+    );
+
+    expect(out).toContain("environment: conciergeEnv");
+  });
+
+  it("quotes YAML-ambiguous strings", () => {
+    const vault = entity("Fountain::V1::Vault", {
+      name: "v",
+      description: "true",
+    });
+
+    const out = primary(fountainSerializer.serialize(new Map([["v", vault]])));
+    expect(out).toContain('description: "true"');
+  });
+
+  it("does not use YAML aliases or tags for substitution references", () => {
+    const agent = entity("Fountain::V1::Agent", {
+      name: "a",
+      model: "anthropic/claude-sonnet-4-6",
+      runtime: "claude",
+      mcp_servers: { github: { env: { GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PAT}" } } },
+    });
+
+    const out = primary(fountainSerializer.serialize(new Map([["a", agent]])));
+    expect(out).toContain('GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PAT}"');
+  });
+});

package/src/serializer.ts

@@ -0,0 +1,143 @@
+import type { Serializer, SerializerResult, Declarable } from "@intentius/chant";
+import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
+import { propsOf } from "./entity-props";
+
+/**
+ * Fountain serializer — emits fountain's native manifest format
+ * (`apiVersion: fountain.dev/v1`), one YAML document per resource, as a
+ * single multi-document stream. The output stays `fountain apply -f`
+ * compatible, so anyone can eject from chant and keep the artifacts.
+ *
+ * Cross-resource references (e.g. `agent.environment`) serialize to the
+ * referenced entity's name — fountain's CLI resolves names to ids at apply.
+ */
+
+const API_VERSION = "fountain.dev/v1";
+
+/** Fountain::V1::Agent → Agent */
+function kindOf(entityType: string): string {
+  const parts = entityType.split("::");
+  return parts[parts.length - 1];
+}
+
+export const fountainSerializer: Serializer = {
+  name: "fountain",
+  rulePrefix: "FTN",
+
+  serialize(entities: Map<string, Declarable>): string | SerializerResult {
+    // Reverse map for reference resolution: Declarable instance → name.
+    const entityNames = new Map<Declarable, string>();
+    for (const [name, entity] of entities) {
+      entityNames.set(entity, name);
+    }
+
+    const visitor: SerializerVisitor = {
+      // A reference to another fountain resource serializes to its name.
+      attrRef(logicalName, _attribute) {
+        return logicalName;
+      },
+      resourceRef(logicalName) {
+        return logicalName;
+      },
+      propertyDeclarable(entity, walk) {
+        const props: Record<string, unknown> = {};
+        for (const [key, val] of Object.entries(propsOf(entity))) {
+          if (val === undefined) continue;
+          props[key] = walk(val);
+        }
+        return props;
+      },
+    };
+
+    const docs: string[] = [];
+    const plan: Record<string, { kind: string; spec: Record<string, unknown> }> = {};
+    for (const [name, entity] of entities) {
+      const spec: Record<string, unknown> = {};
+      for (const [key, val] of Object.entries(propsOf(entity))) {
+        if (val === undefined) continue;
+        spec[key] = walkValue(val, entityNames, visitor);
+      }
+
+      const manifest = {
+        apiVersion: API_VERSION,
+        kind: kindOf(entity.entityType),
+        metadata: { name },
+        spec,
+      };
+      docs.push(toYaml(manifest));
+      plan[name] = { kind: manifest.kind, spec };
+    }
+
+    const yaml = docs.join("---\n");
+    if (docs.length === 0) return yaml;
+
+    // Primary output is the ejectable `fountain apply -f` YAML; the JSON
+    // sidecar is the fountainApply op's input (same data, no YAML parser
+    // needed on the apply side — the fly plan.json pattern).
+    return { primary: yaml, files: { "fountain-plan.json": JSON.stringify(plan, null, 2) } };
+  },
+};
+
+// ── Minimal YAML emitter ───────────────────────────────────────────
+// The manifest shape is plain JSON-compatible data (maps, arrays, scalars),
+// so a small emitter keeps the lexicon dependency-free. Strings are quoted
+// whenever they could be misread as another YAML type.
+
+function toYaml(value: unknown, indent = 0): string {
+  const pad = "  ".repeat(indent);
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return `${pad}[]\n`;
+    let out = "";
+    for (const item of value) {
+      if (isScalar(item)) {
+        out += `${pad}- ${scalar(item)}\n`;
+      } else {
+        const body = toYaml(item, indent + 1);
+        out += `${pad}-\n${body}`;
+      }
+    }
+    return out;
+  }
+
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length === 0) return `${pad}{}\n`;
+    let out = "";
+    for (const [k, v] of entries) {
+      if (isScalar(v)) {
+        out += `${pad}${key(k)}: ${scalar(v)}\n`;
+      } else if (Array.isArray(v) && v.length === 0) {
+        out += `${pad}${key(k)}: []\n`;
+      } else if (v !== null && typeof v === "object" && Object.keys(v as object).length === 0) {
+        out += `${pad}${key(k)}: {}\n`;
+      } else {
+        out += `${pad}${key(k)}:\n${toYaml(v, indent + 1)}`;
+      }
+    }
+    return out;
+  }
+
+  return `${pad}${scalar(value)}\n`;
+}
+
+function isScalar(v: unknown): boolean {
+  return v === null || ["string", "number", "boolean"].includes(typeof v);
+}
+
+const PLAIN_STRING = /^[A-Za-z0-9._/-][A-Za-z0-9._/ -]*$/;
+const YAML_AMBIGUOUS = /^(true|false|null|yes|no|on|off|~|[+-]?[0-9.]+([eE][+-]?[0-9]+)?)$/i;
+
+function scalar(v: unknown): string {
+  if (v === null) return "null";
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  const s = String(v);
+  if (s === "" || !PLAIN_STRING.test(s) || YAML_AMBIGUOUS.test(s) || s.includes("\n")) {
+    return JSON.stringify(s);
+  }
+  return s;
+}
+
+function key(k: string): string {
+  return PLAIN_STRING.test(k) && !YAML_AMBIGUOUS.test(k) ? k : JSON.stringify(k);
+}

package/src/skills/chant-fountain-locked-sandboxes.md

@@ -0,0 +1,34 @@
+---
+skill: chant-fountain-locked-sandboxes
+description: Declare locked-down fountain environments for untrusted or security-sensitive agents, and run conversations against them
+user-invocable: true
+---
+
+# Locked-Down Sandboxes and Conversation Runs
+
+## The posture
+
+For an agent handling anything sensitive (a repo checkout, an internal API), declare the environment closed by construction:
+
+```ts
+export const lockedEnv = new Environment({
+  name: "concierge-env",
+  networking_type: "limited",
+  networking_config: { allowed_hosts: ["registry.npmjs.org", "github.com"] },
+  metadata: { "managed-by": "chant" },
+});
+```
+
+Semantics (from fountain's own schema): `unrestricted` is a no-op — sprites are open by default. `limited` restricts egress to `allowed_hosts`; with **no** hosts (or an empty list) it denies all egress — deny-all, not allow-all. So `limited` + `[]` is the isolation mode.
+
+Pair it with a closed vault policy on the agent — `allowed_vault_ids: []` — so no conversation can override the reviewed environment at spawn, and give the sandbox **no cloud credentials of any kind**: anything readable inside is exfiltratable by prompt injection. Services the agent needs live outside the sandbox behind their own auth; the sandbox gets at most a conversation-scoped token.
+
+Lint posture: FTN010/FTN011 fire on missing/unrestricted networking at warning severity by default. For repos whose environments are all concierge-class, promote them to error via project rules.
+
+## Drift is the alarm
+
+The environment's config is the enforcement boundary, so watch it: `chant lifecycle diff --live` flags a UI edit that adds a secret, opens networking, or drops the marker. Wire it into a scheduled watch — an out-of-band change to a locked environment is an incident, not housekeeping.
+
+## Running conversations
+
+Conversations are runs, not resources. Use the `fountainRun` activity: resolves the agent by name, starts (optionally with a prompt and an allowlisted vault), polls to `completed | failed | timed_out`, and terminates at its deadline so a hung sandbox never outlives the op. Multi-turn interaction (follow-up prompts, interrupt) is fountain's own conversations API — keep chant to the lifecycle edges.

package/src/skills/chant-fountain-secrets.md

@@ -0,0 +1,29 @@
+---
+skill: chant-fountain-secrets
+description: Handle fountain secrets, env vars, and ${VAR} substitution safely from chant
+user-invocable: true
+---
+
+# Fountain Secrets and Substitution
+
+## The model
+
+Everything materialized into a fountain sandbox must be presumed exfiltrated once untrusted agent code runs. Order of preference:
+
+1. **`${VAR}` substitution references** in agent config (MCP server env, system prompts). Resolved at spawn from the merged environment + vault sets. Never a value in source.
+2. **Environment secrets** (`spec.secrets`) — encrypted at rest, write-only over the API (values are never returned once stored). `fountainApply` upserts them through the sub-resource; a changed value cannot be detected, only overwritten.
+3. **`env_vars`** — plaintext config only. FTN012 errors on credential-shaped keys or values here.
+
+Never put a literal credential anywhere in a declaration: FTN001 catches known shapes (AWS keys, GitHub/Slack tokens, `sk-`/`ftn_` keys, private key material) at the AST; FTN015 errors on secret-shaped MCP env keys that are not `${VAR}` references.
+
+## Vault semantics
+
+Vault values **win on key collision** with the environment, silently, at spawn. FTN014 warns when a declared vault shadows a declared environment key, so the override is visible in review. Which vaults may attach to an agent is scoped by `allowed_vault_ids` (nullable: `null` = any tenant vault, `[]` = none, list = allowlist) — set `[]` on agents whose environment must not be overridable.
+
+## Build-time resolution check
+
+FTN013 warns when an agent references `${VAR}` and its declared environment has no such key (env_vars or secret keys). A vault can legitimately supply it at conversation create — the warning is "confirm this is intentional," not "this is broken."
+
+## Round-trips and their limits
+
+`chant import --from` exports live resources but never secrets: values are write-only upstream, and secret keys are not on the typed request surface. Re-declare imported environments' secrets through your secret provider. Upstream discussion of a reference-based model that would fix this: BinaryBourbon/fountain#148.

package/src/skills/chant-fountain.md

@@ -0,0 +1,45 @@
+---
+skill: chant-fountain
+description: Declare, lint, and reconcile fountain Environments, Vaults, and Agents from a chant project
+user-invocable: true
+---
+
+# Fountain Workloads as Typed Estate
+
+## What this lexicon covers
+
+[fountain](https://github.com/BinaryBourbon/fountain) runs coding agents in sandboxed VMs. Its workload layer is three kinds — `Environment` (sandbox baseline), `Vault` (env-var overrides), `Agent` (a runnable agent config) — and this lexicon declares them as typed chant resources. Conversations are runs, not resources: start them with the `fountainRun` op, never declare them.
+
+The source of truth is the TypeScript in `src/`. `chant build` serializes it to fountain's own manifest YAML (ejectable — `fountain apply -f` accepts it verbatim) plus a `fountain-plan.json` sidecar that `fountainApply` reconciles against the API directly: create-if-new, update-by-name, opt-in owned-only prune keyed on the `managed-by: chant` metadata marker.
+
+## Authoring
+
+```ts
+import { Environment, Agent } from "@intentius/chant-lexicon-fountain";
+
+export const env = new Environment({
+  name: "team-env",
+  networking_type: "limited",                     // FTN010 requires explicit intent
+  networking_config: { allowed_hosts: ["github.com"] },
+  metadata: { "managed-by": "chant" },            // enables owned-only reconcile/prune
+});
+
+export const helper = new Agent({
+  name: "helper",
+  model: "anthropic/claude-sonnet-4-6",
+  runtime: "claude",
+  environment: env,                               // typed ref — dangling name = build error
+  skills: [{ source: "owner/skills-repo", ref: "v1.0.0" }],  // always pin a ref
+});
+```
+
+## Endpoint and auth
+
+`FOUNTAIN_ENDPOINT` (defaults to the hosted instance) + `FOUNTAIN_TOKEN` (mint via `POST /api/auth/token` with email+password, or the account UI). The same code applies to a local `mix phx.server` fountain by pointing `FOUNTAIN_ENDPOINT` at it — registration and token mint work headless, so CI needs no browser.
+
+## The loop
+
+1. `chant build` — synthesize + lint (FTN rules catch open networking, credential literals, unresolvable `${VAR}` refs before review).
+2. `chant run <apply op>` or call `fountainApply` — reconcile. Idempotent by name.
+3. `chant lifecycle diff --live` — drift: a UI edit to an owned Environment shows up here.
+4. `chant import --from` — adopt UI-built resources into typed files (secrets stay behind; see the secrets skill).