@intentius/chant-lexicon-fountain 0.44.13 → 0.45.0

package/dist/codegen/docs.d.ts

@@ -2,10 +2,9 @@
  * fountain documentation generator.
  *
  * Calls the core docsPipeline with fountain-specific config. The reference
- * pages (resources, composites, ops, adoption, skills) are declared as
- * `extraPages` rather than left as hand-written files in docs/: the sidebar is
- * rebuilt from generated pages on every run, so a page the config does not
- * know about exists but cannot be navigated to.
+ * pages (resources, composites, ops, adoption, skills) live as authored MDX
+ * under `docs/pages/`, each tagged with its Diátaxis quadrant; the sidebar is
+ * grouped from that field (chant #1731 / #1733).
  */
 /**
  * Generate documentation site for the fountain lexicon.

package/dist/codegen/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAqNH;;GAEG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDjF"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmFH;;GAEG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBjF"}

package/dist/import/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/import/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAc,MAAM,gCAAgC,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAItE,0EAA0E;AAC1E,eAAO,MAAM,aAAa,UAA4F,CAAC;AAYvH,qBAAa,cAAe,SAAQ,eAAgB,YAAW,cAAc;IAC3E,SAAS,CAAC,iBAAiB,IAAI,OAAO,GAAG,IAAI;IAM7C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IAsChC,OAAO,CAAC,QAAQ;CASjB"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/import/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAc,MAAM,gCAAgC,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAItE,0EAA0E;AAC1E,eAAO,MAAM,aAAa,UAA4F,CAAC;AAYvH,qBAAa,cAAe,SAAQ,eAAgB,YAAW,cAAc;IAC3E,SAAS,CAAC,iBAAiB,IAAI,OAAO,GAAG,IAAI;IAM7C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IAwChC,OAAO,CAAC,QAAQ;CASjB"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "39af3e8b8bfc55c5d56cf3ea4342bfe58a8093ca193da8b213b6c3734b705ae7",
+    "manifest.json": "28dd49dfa56314218e8f0679b05ad176cd7996e751444eb51e6887633c04a4ba",
     "meta.json": "6666b7a77db9210a329219c6a5e107e5ae8794a34542f7310ce16d9bf95c64f5",
     "types/index.d.ts": "1dfdcba184fffcf464dac7d1d71ef7abed2ae02a8d638c0de50e0b0317b7eb01",
     "rules/ftn001-no-secret-literals.ts": "897a4ce1ec790b3c1540d32892603bd33ff4bf30eb6ba4cd2565dee356d4962e",
@@ -17,5 +17,5 @@
     "skills/chant-fountain-secrets.md": "27e349a91589510a92e518c7d7824a4a322cab5ef242cf5799373a55cbfcd1cd",
     "skills/chant-fountain-locked-sandboxes.md": "de82f06cb3a08ba6bf3ae45fb9869e21d6da18b9ebe0fc769da8aebaceea7dd1"
   },
-  "composite": "de6a821131caeda225a9eced056bb23d578422f5250bd335427a76ebe7c396a4"
+  "composite": "b7579f9b30c25525a5424d24868d39e12858de8ea2da23773c3760edca697810"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "fountain",
-  "version": "0.44.13",
+  "version": "0.45.0",
   "chantVersion": ">=0.1.0",
   "namespace": "Fountain",
   "specVersion": "v0.3.0"

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,kBAAkB,CAAC;AAyC/D,eAAO,MAAM,kBAAkB,EAAE,UAmDhC,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,kBAAkB,CAAC;AA4C/D,eAAO,MAAM,kBAAkB,EAAE,UAsDhC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-fountain",
-  "version": "0.44.13",
+  "version": "0.45.0",
   "type": "module",
   "description": "Fountain lexicon for chant — sandboxed agent environments, vaults, and agents as typed estate",
   "license": "Apache-2.0",
@@ -50,7 +50,7 @@
     "bundle": "tsx src/package-cli.ts"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.44.13",
+    "@intentius/chant": "^0.45.0",
     "typescript": "^5.9.3"
   },
   "devDependencies": {

package/src/codegen/docs.ts

@@ -2,10 +2,9 @@
  * fountain documentation generator.
  *
  * Calls the core docsPipeline with fountain-specific config. The reference
- * pages (resources, composites, ops, adoption, skills) are declared as
- * `extraPages` rather than left as hand-written files in docs/: the sidebar is
- * rebuilt from generated pages on every run, so a page the config does not
- * know about exists but cannot be navigated to.
+ * pages (resources, composites, ops, adoption, skills) live as authored MDX
+ * under `docs/pages/`, each tagged with its Diátaxis quadrant; the sidebar is
+ * grouped from that field (chant #1731 / #1733).
  */
 
 import { dirname, join } from "path";
@@ -67,14 +66,13 @@ kind: Environment
 metadata:
   name: team-env
 spec:
-  name: team-env
   networking_type: limited
   networking_config:
     allowed_hosts:
       - github.com
 \`\`\`
 
-\`metadata.name\` is the resource's declared \`name\`, not the name of the variable you exported it as. fountain reconciles by that name, so renaming the variable does not orphan the resource. An entity declared without a \`name\` falls back to the export name.
+\`metadata.name\` is the resource's declared \`name\`, not the name of the variable you exported it as. fountain reconciles by that name, so renaming the variable does not orphan the resource. An entity declared without a \`name\` falls back to the export name. The name appears only in \`metadata\`; it is not repeated under \`spec\`, so the apply request carries one name per resource.
 
 The output is ejectable — \`fountain apply -f\` accepts it verbatim, so adopting chant here does not trap the manifests behind chant.
 
@@ -90,135 +88,6 @@ Resources carrying \`metadata."managed-by": chant\` are chant-owned. That marker
 
 \`spec.secrets\` is authored as an ordered \`{key, value}[]\`, same as any other typed prop. \`fountainApply\` converts it to the \`{KEY: value}\` map fountain's bulk apply expects on the wire; the server upserts it through the encrypted envelope path. Values are write-only upstream, so this is upsert-always — a changed value cannot be detected, only overwritten.`;
 
-const resourcesPage = `The lexicon types the three kinds \`fountain apply\` reconciles — the workload
-layer of [fountain](https://github.com/BinaryBourbon/fountain). Types are
-generated from fountain's served OpenAPI spec, so they track the real API.
-Conversations are deliberately **not** a resource: they are runs with a
-status lifecycle, modeled as ops.
-
-## Environment
-
-A reusable sandbox baseline: packages, repos, setup script, env vars,
-encrypted secrets, and the networking policy. \`networking_type\` is
-\`"unrestricted" | "limited"\`; under \`limited\`, egress is restricted to
-\`networking_config.allowed_hosts\`, and with no hosts (or an empty list) the
-sandbox denies all egress — a deny-all, not an allow-all. FTN010 requires the
-networking intent to be explicit.
-
-## Vault
-
-A bag of env-var overrides selected at conversation create. Vault values
-win on key collision with the environment — which is why agents can carry
-a vault allowlist upstream (fountain#136). \`allowed_vault_ids\` on an Agent is
-three-state: \`null\` allows any tenant vault, \`[]\` forbids all, a list is an
-allowlist.
-
-## Agent
-
-A named, re-runnable agent configuration: model, runtime, skills (inline
-SKILL.md or GitHub-sourced with a \`ref\` pin), MCP servers, and an optional
-\`environment\` reference — typed, so a dangling reference is a build error,
-not a 422 at apply time.
-
-## Example
-
-\`\`\`ts
-import { Environment, Agent } from "@intentius/chant-lexicon-fountain";
-
-export const conciergeEnv = new Environment({
-  name: "concierge-env",
-  networking_type: "limited",
-  networking_config: { allowed_hosts: ["registry.npmjs.org", "github.com"] },
-  metadata: { "managed-by": "chant" },
-});
-
-export const researcher = new Agent({
-  name: "researcher",
-  model: "anthropic/claude-sonnet-4-6",
-  runtime: "claude",
-  environment: conciergeEnv,
-  skills: [{ source: "vercel-labs/agent-skills", ref: "main" }],
-});
-\`\`\``;
-
-const compositesPage = `## ConciergeStack
-
-An Environment + Agent pair with the secure-by-construction defaults for agents that touch anything sensitive:
-
-\`\`\`typescript
-import { ConciergeStack } from "@intentius/chant-lexicon-fountain";
-
-export const { environment, agent } = ConciergeStack({
-  name: "concierge",
-  model: "anthropic/claude-sonnet-4-6",
-  allowedHosts: ["registry.npmjs.org", "github.com"],
-});
-\`\`\`
-
-| Default | Effect |
-|---|---|
-| \`networking_type: limited\` with an empty allowlist | deny-all egress — fountain's isolation mode |
-| \`allowed_vault_ids: []\` | no conversation may override the reviewed environment at spawn |
-| \`managed-by: chant\` on both | owned-only reconcile, prune, and drift filtering see them |
-
-Every default is the closed one, so loosening any of it is a visible, reviewable act: pass an allowlist, pass vault ids, or drop to the raw classes.
-
-Give such a sandbox **no cloud credentials of any kind** — anything readable inside it 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.`;
-
-const opsPage = `Two op activities ship with the lexicon, resolvable by name via \`loadActivities(["fountain"])\`.
-
-## fountainApply
-
-The native applier: compiles the serializer's manifest YAML into fountain's bulk \`POST /api/apply\` request and sends it in one call.
-
-| Behavior | Detail |
-|---|---|
-| Create / update | By name, reconciled server-side. An agent's \`environment\` reference resolves by name — against the manifest or the tenant's existing environments — without a client-side id lookup. |
-| Order | Environment → Vault → Agent, fixed server-side regardless of manifest order. |
-| Prune | Off by default. With \`prune: true\`, chant-owned resources absent from the manifest are deleted, in reverse order — the one thing bulk apply doesn't cover, so this still lists live state per kind. |
-| Secrets | \`spec.secrets\` converts from chant's authored \`{key, value}[]\` to the wire's \`{KEY: value}\` map; the server upserts them through the encrypted envelope path in the same request. Upsert-always — values are write-only upstream. |
-| Failure | Best-effort per resource. Every result is collected before this throws, so one bad resource doesn't hide failures elsewhere in the manifest. |
-
-\`\`\`typescript
-await fountainApply({ manifestPath: "build/fountain.yaml", prune: true });
-\`\`\`
-
-Endpoint and token resolution: explicit args win, then \`FOUNTAIN_ENDPOINT\` / \`FOUNTAIN_TOKEN\`, then the hosted default.
-
-## fountainRun
-
-Conversations are runs, not resources, so they are started rather than declared. \`fountainRun\` resolves the agent by name, starts a conversation (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. The lexicon stays at the lifecycle edges.`;
-
-const adoptionPage = `The lexicon reads live fountain state on three paths.
-
-## Drift
-
-\`chant lifecycle diff --live\` reports each declared entity as observed present, observed absent, or **not observed** with a reason — a read failure is never reported as an absence, which would propose a spurious create. Ownership comes from the \`managed-by: chant\` marker, so \`--owned\` filters to what chant declared.
-
-An out-of-band change to a locked environment — a UI edit that adds a secret, opens networking, or drops the marker — is what this catches. Wire it into a scheduled watch and treat a hit as an incident, not housekeeping.
-
-## Import
-
-\`chant import --from\` adopts UI-built resources into typed files. Server-written fields are stripped to the authored shape, and an agent's \`environment_id\` is resolved back to the exported environment's logical name so the generated code carries a reviewable reference.
-
-Secrets do not round-trip: values are write-only upstream and secret keys are not on the typed request surface, so environments export without them and the caller is warned per environment that carried any. Re-declare them through your secret provider.
-
-## Graph
-
-\`chant graph --live\` reconstructs the topology from one edge: an Agent runs in an Environment. Vaults are deliberately edge-free — vault-to-agent binding is a conversation-time choice scoped by \`allowed_vault_ids\`, not standing topology.`;
-
-const skillsPage = `Three agent skills ship with the lexicon and load automatically in a project that uses it.
-
-| Skill | Covers |
-|---|---|
-| \`chant-fountain\` | The core authoring loop — declaring the three kinds, the build/apply/drift/import cycle, endpoint and auth |
-| \`chant-fountain-secrets\` | Secrets, \`env_vars\`, and \`\${VAR}\` substitution: the order of preference, vault precedence, and what does not round-trip |
-| \`chant-fountain-locked-sandboxes\` | The locked-down posture for untrusted or security-sensitive agents, and running conversations against them |
-
-Invoke one directly by name, or let it trigger on context (\`fountain\`, \`vault\`, \`sandbox\`, \`networking_type\`).`;
-
 /**
  * Generate documentation site for the fountain lexicon.
  */
@@ -237,38 +106,6 @@ export async function generateDocs(options?: { verbose?: boolean }): Promise<voi
     // No `resourceTypeUrl` key: DocsConfig has none, so passing it was a
     // silent no-op. The upstream reference link lives in the resources page
     // content, where it actually renders.
-    extraPages: [
-      {
-        slug: "resources",
-        title: "Resources",
-        description: "The three fountain workload kinds the lexicon declares.",
-        content: resourcesPage,
-      },
-      {
-        slug: "composites",
-        title: "Composites",
-        description: "ConciergeStack — a locked-down Environment and Agent pair.",
-        content: compositesPage,
-      },
-      {
-        slug: "ops",
-        title: "Ops",
-        description: "fountainApply and fountainRun — the applier and the conversation runner.",
-        content: opsPage,
-      },
-      {
-        slug: "adoption",
-        title: "Drift and Adoption",
-        description: "Live observation, import, and the graph edge fountain reconstructs.",
-        content: adoptionPage,
-      },
-      {
-        slug: "skills",
-        title: "Skills",
-        description: "The agent skills the lexicon ships.",
-        content: skillsPage,
-      },
-    ],
   };
 
   const result = docsPipeline(config);

package/src/import/parser.ts

@@ -66,7 +66,9 @@ export class FountainParser extends BaseValueParser implements TemplateParser {
       const meta = isRecord(doc.metadata) ? doc.metadata : {};
       const name = typeof meta.name === "string" ? meta.name : kind.toLowerCase();
       const spec = isRecord(doc.spec) ? doc.spec : {};
-      resources.push(this.resource(type, name, spec));
+      // Manifests carry the name in `metadata` only; the typed resource
+      // needs it as its `name` prop.
+      resources.push(this.resource(type, name, { ...spec, name }));
     }
     return { resources, parameters: [] };
   }

package/src/import/roundtrip.test.ts

@@ -10,7 +10,6 @@ kind: Environment
 metadata:
   name: concierge-env
 spec:
-  name: concierge-env
   networking_type: limited
   networking_config:
     allowed_hosts:
@@ -24,7 +23,6 @@ kind: Agent
 metadata:
   name: researcher
 spec:
-  name: researcher
   model: anthropic/claude-sonnet-4-6
   runtime: claude
   environment: concierge-env
@@ -50,6 +48,18 @@ describe("parser", () => {
     expect(ir.resources[0].properties.networking_type).toBe("limited");
   });
 
+  it("takes the name prop from metadata.name when spec carries none (#1606)", () => {
+    const ir = new FountainParser().parse(MANIFESTS);
+    expect(ir.resources.map((r) => r.properties.name)).toEqual(["concierge-env", "researcher"]);
+  });
+
+  it("lets metadata.name win over a stray spec.name", () => {
+    const ir = new FountainParser().parse(
+      "apiVersion: fountain.dev/v1\nkind: Vault\nmetadata:\n  name: real\nspec:\n  name: stale\n",
+    );
+    expect(ir.resources[0].properties.name).toBe("real");
+  });
+
   it("parses the fountain-plan.json sidecar", () => {
     const ir = new FountainParser().parse(
       JSON.stringify({ v: { kind: "Vault", spec: { name: "staging", id: "drop-me" } } }),

package/src/serializer.test.ts

@@ -43,6 +43,25 @@ describe("fountain serializer", () => {
     expect(out).toContain("- github.com");
   });
 
+  it("carries the name in metadata only, never under spec (#1606)", () => {
+    const agent = entity("Fountain::V1::Agent", {
+      name: "tech-lead",
+      model: "anthropic/claude-sonnet-4-6",
+      runtime: "claude",
+    });
+
+    const out = fountainSerializer.serialize(new Map([["techLead", agent]])) as string;
+
+    expect(out).toContain("metadata:\n  name: tech-lead\n");
+    expect(out).not.toContain("spec:\n  name:");
+    expect(out.match(/^\s*name: /gm)).toHaveLength(1);
+
+    // The apply payload fountain receives has exactly one name per resource.
+    const [resource] = parseManifest(out);
+    expect(resource.name).toBe("tech-lead");
+    expect(resource.spec).not.toHaveProperty("name");
+  });
+
   it("separates multiple entities with document markers", () => {
     const env = entity("Fountain::V1::Environment", { name: "e" });
     const vault = entity("Fountain::V1::Vault", { name: "v" });

package/src/serializer.ts

@@ -15,6 +15,9 @@ import { propsOf } from "./entity-props";
  *
  * Cross-resource references (e.g. `agent.environment`) serialize to the
  * referenced entity's name — fountain resolves names to ids at apply.
+ *
+ * The `name` prop becomes `metadata.name` and is not repeated under `spec`,
+ * matching fountain's own manifest examples.
  */
 
 const API_VERSION = "fountain.dev/v1";
@@ -73,9 +76,12 @@ export const fountainSerializer: Serializer = {
 
     const docs: string[] = [];
     for (const [name, entity] of entities) {
+      // `name` lives in `metadata` only. fountain's manifest format carries
+      // the upsert key there and nowhere else; a second copy under `spec`
+      // is at best redundant and at worst a conflicting value (#1606).
       const spec: Record<string, unknown> = {};
       for (const [key, val] of Object.entries(propsOf(entity))) {
-        if (val === undefined) continue;
+        if (val === undefined || key === "name") continue;
         spec[key] = walkValue(val, entityNames, visitor);
       }