@archinsight/cli 3.0.0-snapshot.4 → 3.0.0-snapshot.6

package/build/index.js

@@ -57,7 +57,7 @@ var require_archy = __commonJS({
 
 // src/index.ts
 var import_archy = __toESM(require_archy(), 1);
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { instance } from "@viz-js/viz";
 
@@ -32343,7 +32343,7 @@ var coreSources = [
   },
   {
     "sourceName": "core_deployment.ai",
-    "source": "define type DeploymentElement of Element\n\ndefine type InfrastructureComponent of DeploymentElement\n    constructor infrastructureComponent\n\n    required Text name\n    Text description\n    List of TypeSlotReference _\n\ndefine type Environment of BoundaryElement\n    constructor environment\n\n    required Text name\n\ndefine type DeploymentProfile of BoundaryElement\n    constructor deploymentProfile\n\n    List of Environment environments\n    List of TypeSlotReference _\n\ndefine type DeploymentProfileReference of TypeSlotReference\n    required DeploymentProfile profile\n\ndefine presentation DeploymentProfile\n    graphviz\n        visible = false"
+    "source": "define type DeploymentElement of Element\n\ndefine type InfrastructureComponent of DeploymentElement\n    constructor infrastructureComponent\n\n    Text name\n    Text technology\n    Text description\n    List of TypeSlotReference _\n\ndefine type Storage of InfrastructureComponent\n    constructor storage\n\n    project:\n        $from -> $this\n\ndefine type Broker of InfrastructureComponent\n    constructor broker\n\n    Text address\n\n    project:\n        $from -> $this\n        $to -> $this\n\ndefine type Compute of InfrastructureComponent\n    constructor compute\n\n    Text address\n    List of InfrastructureComponent components\n\ndefine type NetworkConnection of InfrastructureComponent\n    constructor networkConnection\n\n    project:\n        $from -> $to\n\ndefine type Environment of BoundaryElement\n    constructor environment\n\n    required Text name\n\ndefine type DeploymentProfile of BoundaryElement\n    constructor deploymentProfile\n\n    List of Environment environments\n    List of TypeSlotReference _\n\ndefine type DeploymentProfileReference of TypeSlotReference\n    required DeploymentProfile profile\n\ndefine presentation DeploymentProfile\n    graphviz\n        visible = false\n\ndefine presentation NetworkConnection\n    graphviz\n        visible = false\n"
   },
   {
     "sourceName": "core_operator.ai",
@@ -34184,6 +34184,7 @@ function linkProject(request) {
           sourceIdentity: edge.sourceName,
           fromId: edge.source,
           toId: target.id,
+          projectedAttributes: materialized.edge.attributes,
           ...materialized.edge.annotations === void 0 ? {} : { annotations: materialized.edge.annotations }
         });
         pendingProjections.push({
@@ -34191,6 +34192,7 @@ function linkProject(request) {
           fromId: edge.source,
           toId: target.id,
           attributes: edgeAttributes,
+          projectedAttributes: materialized.edge.attributes,
           ...materialized.edge.annotations === void 0 ? {} : { annotations: materialized.edge.annotations }
         });
       }
@@ -34220,7 +34222,7 @@ function linkProject(request) {
     });
   }
   for (const projection of pendingProjections) {
-    addProjectedEdges(linkedEdges, projection.sourceIdentity, projection.fromId, projection.toId, projection.attributes, linkedElementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, void 0, projection.annotations);
+    addProjectedEdges(linkedEdges, projection.sourceIdentity, projection.fromId, projection.toId, projection.attributes, linkedElementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, void 0, projection.annotations, projection.projectedAttributes);
   }
   const slotDomainTypes = typeSystem.slotDomainTypes();
   for (const element of elements) {
@@ -34233,7 +34235,7 @@ function linkProject(request) {
   const presentations = buildPresentationIndex(request.snapshot.presentations ?? [], typeSystem, diagnostics);
   const graph = buildIndexedGraph(documents, elements, imports, linkedEdges, typeSystem);
   const graphElements = elements.filter(isGraphElement);
-  inspectGraph(graph, graphElements, linkedEdges, diagnostics);
+  inspectGraph(graph, graphElements, linkedEdges, resolvedElementAttributes, diagnostics);
   const tabRoots = tabRootsBySource(documents, elementsByContextAndLocalId);
   for (const document of documents) {
     resolveAttributes(
@@ -35248,7 +35250,14 @@ function resolveAttributes(owner, ownerType, attributes2, referenceAttributePosi
         });
         continue;
       }
-      result[name] = [...result[name] ?? [], { id: resolved.id, element: resolved }];
+      result[name] = [...result[name] ?? [], {
+        id: resolved.id,
+        element: resolved,
+        line: value.line,
+        column: value.column,
+        ...value.endLine === void 0 ? {} : { endLine: value.endLine },
+        ...value.endColumn === void 0 ? {} : { endColumn: value.endColumn }
+      }];
     }
   }
   return result;
@@ -35284,7 +35293,7 @@ function flattenAttributes(scalarAttributes, attributes2) {
     ...Object.fromEntries(Object.entries(attributes2).map(([name, values]) => [name, values.map((value) => value.id)]))
   };
 }
-function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes2, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = [], visitedProjectionElements = /* @__PURE__ */ new Set()) {
+function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes2, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = [], projectedAttributes, visitedProjectionElements = /* @__PURE__ */ new Set()) {
   for (const values of Object.values(attributes2)) {
     for (const value of values) {
       if (value.element === void 0) {
@@ -35301,8 +35310,24 @@ function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes
       if (isDirectSlotReferenceSelfProjection(value.element, fromId, toId)) {
         continue;
       }
-      for (const rule3 of typeSystem.projectionRules(value.element.type)) {
-        addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, value.element, rule3, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2);
+      const rules = typeSystem.projectionRules(value.element.type);
+      if (fromId === toId && rules.some(projectionRuleUsesTo)) {
+        const position3 = value.line === void 0 || value.column === void 0 ? value.element : {
+          line: value.line,
+          column: value.column,
+          ...value.endLine === void 0 ? {} : { endLine: value.endLine },
+          ...value.endColumn === void 0 ? {} : { endColumn: value.endColumn }
+        };
+        diagnostics.push({
+          code: "PROJECTION_TARGET_REQUIRED",
+          message: `Projection for '${value.element.type}' uses '$to' and must be attached to a relationship, not to element '${fromId}'`,
+          sourceName: sourceIdentity,
+          ...diagnosticPosition2(position3)
+        });
+        continue;
+      }
+      for (const rule3 of rules) {
+        addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, value.element, rule3, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2, projectedAttributes);
       }
       addProjectedEdges(
         linkedEdges,
@@ -35317,12 +35342,13 @@ function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes
         diagnostics,
         projectionScope,
         annotations2,
+        void 0,
         visitedProjectionElements
       );
     }
   }
 }
-function addProjectedEdgesForValues(linkedEdges, sourceIdentity, fromId, toId, values, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = []) {
+function addProjectedEdgesForValues(linkedEdges, sourceIdentity, fromId, toId, values, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = [], projectedAttributes) {
   addProjectedEdges(
     linkedEdges,
     sourceIdentity,
@@ -35335,7 +35361,8 @@ function addProjectedEdgesForValues(linkedEdges, sourceIdentity, fromId, toId, v
     typeSystem,
     diagnostics,
     projectionScope,
-    annotations2
+    annotations2,
+    projectedAttributes
   );
 }
 function addEdgeScopes(scopesByCarrierId, attributes2, scope) {
@@ -35352,15 +35379,16 @@ function addEdgeScopes(scopesByCarrierId, attributes2, scope) {
 function isDirectSlotReferenceSelfProjection(element, fromId, toId) {
   return fromId === toId && element.parent === fromId && element.scalarAttributes.parentType !== void 0 && element.scalarAttributes.attributeName !== void 0;
 }
-function addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, projectionElement, rule3, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = []) {
+function addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, projectionElement, rule3, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = [], projectedAttributes) {
   const sources = projectionTerm(rule3.source, fromId, toId, projectionElement, elementsById, resolvedElementAttributes, diagnostics);
   const targets = projectionTerm(rule3.target, fromId, toId, projectionElement, elementsById, resolvedElementAttributes, diagnostics);
+  const carriedAttributes = rule3.source.kind === "from" ? projectedAttributes : void 0;
   for (const source of sources) {
     for (const target of targets) {
       if (!projectionRuleUsesOwner(rule3)) {
         const key = `${projectionElement.id}\0${source}\0${rule3.operator}\0${target}`;
         if (ownerIndependentProjectionKeys.has(key)) {
-          mergeProjectedEdgeAnnotations(linkedEdges, source, rule3.operator, target, annotations2);
+          mergeProjectedEdge(linkedEdges, source, rule3.operator, target, annotations2, carriedAttributes);
           continue;
         }
         ownerIndependentProjectionKeys.add(key);
@@ -35369,6 +35397,18 @@ function addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, project
       const targetElement = elementsById.get(target);
       const operator = sourceElement === void 0 || targetElement === void 0 ? void 0 : typeSystem.operatorConstructor(rule3.operator, sourceElement.type, targetElement.type);
       const type = operator?.ownerType ?? rule3.operator;
+      const existingIndex = linkedEdges.findIndex((edge) => edge.projected === true && edge.source === source && edge.operator === rule3.operator && edge.target === target && edge.projectionScope === projectionScope);
+      if (existingIndex >= 0) {
+        const edge = linkedEdges[existingIndex];
+        if (edge !== void 0) {
+          linkedEdges[existingIndex] = {
+            ...edge,
+            attributes: mergeAttributeValues(carriedAttributes, edge.attributes),
+            annotations: uniqueAnnotations([...edge.annotations ?? [], ...annotations2])
+          };
+        }
+        continue;
+      }
       linkedEdges.push({
         source,
         target,
@@ -35377,7 +35417,7 @@ function addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, project
         operator: rule3.operator,
         type,
         sourceIdentity,
-        attributes: {},
+        attributes: carriedAttributes ?? {},
         ...listAttributesProperty(typeSystem, type),
         projected: true,
         ...projectionScope === void 0 ? {} : { projectionScope },
@@ -35386,8 +35426,8 @@ function addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, project
     }
   }
 }
-function mergeProjectedEdgeAnnotations(linkedEdges, source, operator, target, annotations2) {
-  if (annotations2.length === 0) {
+function mergeProjectedEdge(linkedEdges, source, operator, target, annotations2, attributes2) {
+  if (annotations2.length === 0 && (attributes2 === void 0 || Object.keys(attributes2).length === 0)) {
     return;
   }
   const index = linkedEdges.findIndex((edge2) => edge2.projected === true && edge2.source === source && edge2.operator === operator && edge2.target === target);
@@ -35400,9 +35440,19 @@ function mergeProjectedEdgeAnnotations(linkedEdges, source, operator, target, an
   }
   linkedEdges[index] = {
     ...edge,
+    attributes: mergeAttributeValues(attributes2, edge.attributes),
     annotations: uniqueAnnotations([...edge.annotations ?? [], ...annotations2])
   };
 }
+function mergeAttributeValues(base, override) {
+  if (base === void 0 || Object.keys(base).length === 0) {
+    return override;
+  }
+  if (Object.keys(override).length === 0) {
+    return base;
+  }
+  return { ...base, ...override };
+}
 function uniqueAnnotations(annotations2) {
   const seen = /* @__PURE__ */ new Set();
   const result = [];
@@ -35427,6 +35477,12 @@ function referenceAttributesProperty(attributes2) {
 function projectionRuleUsesOwner(rule3) {
   return projectionTermUsesOwner(rule3.source) || projectionTermUsesOwner(rule3.target);
 }
+function projectionRuleUsesTo(rule3) {
+  return projectionTermUsesTo(rule3.source) || projectionTermUsesTo(rule3.target);
+}
+function projectionTermUsesTo(term) {
+  return term.kind === "to";
+}
 function projectionTermUsesOwner(term) {
   return term.kind === "from" || term.kind === "to" || term.kind === "slot";
 }
@@ -36018,7 +36074,8 @@ function applyDeploymentUsesCarrier(carrier, parent, context) {
       context.typeSystem,
       context.diagnostics,
       projectionScope,
-      annotations2
+      annotations2,
+      scope.projectedAttributes
     );
   }
 }
@@ -36202,14 +36259,14 @@ function nearestAncestor(element, elementsById, predicate) {
   }
   return void 0;
 }
-function inspectGraph(graph, elements, edges, diagnostics) {
+function inspectGraph(graph, elements, edges, resolvedElementAttributes, diagnostics) {
   if (diagnostics.some((diagnostic) => diagnostic.level === void 0 || diagnostic.level === "ERROR")) {
     return;
   }
-  reportIsolatedElements(graph, elements, diagnostics);
+  reportIsolatedElements(graph, elements, edges, resolvedElementAttributes, diagnostics);
   reportShadowedLowerLevelEdges(graph, edges, diagnostics);
 }
-function reportIsolatedElements(graph, elements, diagnostics) {
+function reportIsolatedElements(graph, elements, edges, resolvedElementAttributes, diagnostics) {
   const referenced = /* @__PURE__ */ new Set();
   for (const relationId of graph.relationsOfKind("REFERENCES")) {
     const relation = graph.relation(relationId);
@@ -36218,6 +36275,21 @@ function reportIsolatedElements(graph, elements, diagnostics) {
       referenced.add(relation.target);
     }
   }
+  for (const edge of edges) {
+    referenced.add(edge.source);
+    referenced.add(edge.target);
+  }
+  for (const [elementId, attributes2] of resolvedElementAttributes) {
+    for (const values of Object.values(attributes2)) {
+      if (values.length === 0) {
+        continue;
+      }
+      referenced.add(elementId);
+      for (const value of values) {
+        referenced.add(value.id);
+      }
+    }
+  }
   for (const element of elements) {
     if (element.anonymous || containsNestedElement(graph, element.id) || referenced.has(element.id)) {
       continue;
@@ -37776,7 +37848,7 @@ var QueryParser = class {
 };
 
 // src/version.ts
-var version = "3.0.0-snapshot.4";
+var version = "3.0.0-snapshot.6";
 
 // src/index.ts
 var hiddenStructureTypes = /* @__PURE__ */ new Set(["List", "Nothing", "Text", "text"]);
@@ -37969,11 +38041,24 @@ async function runSkillInit(args, skillPackage) {
   const projectRoot = path.resolve(projectPath(args));
   const usesDefaultOutput = args.output === void 0;
   const outputRoot = path.resolve(projectRoot, args.output ?? skillPackage.defaultOutput);
+  if (args.force && await exists(outputRoot)) {
+    assertSafeSkillOutputRoot(projectRoot, outputRoot);
+    await rm(outputRoot, { recursive: true, force: true });
+  }
   for (const file of skillPackage.files) {
     await writeGeneratedFile(path.join(outputRoot, file.path), file.content, args.force);
   }
   process.stdout.write(skillPackageSuccess(projectRoot, outputRoot, skillPackage, usesDefaultOutput));
 }
+function assertSafeSkillOutputRoot(projectRoot, outputRoot) {
+  if (outputRoot === path.parse(outputRoot).root || outputRoot === process.cwd() || outputRoot === projectRoot) {
+    throw new CliError(`Refusing to delete unsafe skill output directory '${outputRoot}'. Choose a dedicated --out directory.`);
+  }
+  const projectRelativeToOutput = path.relative(outputRoot, projectRoot);
+  if (projectRelativeToOutput !== "" && !projectRelativeToOutput.startsWith("..") && !path.isAbsolute(projectRelativeToOutput)) {
+    throw new CliError(`Refusing to delete skill output directory '${outputRoot}' because it contains the project root.`);
+  }
+}
 async function loadProject(input) {
   const root = path.resolve(input);
   const sources = await readSources(root);
@@ -38426,7 +38511,7 @@ Options:
   -o, --out <file>         Write output to file instead of stdout; for skill init, write the guide directory.
   -t, --theme <theme>      Render theme, default: light.
       --target <target>    Skill target: generic, codex, or claude.
-      --force              Replace existing generated skill files.
+      --force              Delete and recreate the generated skill directory.
   -V, --version            Print version.
   -h, --help               Show help.
 
@@ -38497,6 +38582,26 @@ function sharedSkillFiles() {
       path: "references/layered-architecture.md",
       content: genericLayeredArchitectureReference()
     },
+    {
+      path: "references/c1-context.md",
+      content: genericC1ContextReference()
+    },
+    {
+      path: "references/c2-containers.md",
+      content: genericC2ContainersReference()
+    },
+    {
+      path: "references/c3-components.md",
+      content: genericC3ComponentsReference()
+    },
+    {
+      path: "references/c4-deployment.md",
+      content: genericC4DeploymentReference()
+    },
+    {
+      path: "references/scaling.md",
+      content: genericScalingReference()
+    },
     {
       path: "references/project-structure.md",
       content: genericProjectStructureReference()
@@ -38513,14 +38618,58 @@ function sharedSkillFiles() {
       path: "references/queries.md",
       content: genericQueriesReference()
     },
+    {
+      path: "references/query-recipes.md",
+      content: genericQueryRecipesReference()
+    },
     {
       path: "examples/layered-architecture.ai",
       content: genericLayeredArchitectureExample()
     },
+    {
+      path: "examples/c1-context.ai",
+      content: genericC1ContextExample()
+    },
+    {
+      path: "examples/c2-containers.ai",
+      content: genericC2ContainersExample()
+    },
+    {
+      path: "examples/c3-components.ai",
+      content: genericC3ComponentsExample()
+    },
+    {
+      path: "examples/c4-deployment-framework.ai",
+      content: genericC4DeploymentFrameworkExample()
+    },
+    {
+      path: "examples/c4-deployment.ai",
+      content: genericC4DeploymentExample()
+    },
     {
       path: "examples/c2-containers.aiq",
       content: genericC2QueryExample()
     },
+    {
+      path: "examples/builtin-views/no-filter.aiq",
+      content: noFilterQuery
+    },
+    {
+      path: "examples/builtin-views/c1.aiq",
+      content: c1Query
+    },
+    {
+      path: "examples/builtin-views/c2.aiq",
+      content: c2Query
+    },
+    {
+      path: "examples/builtin-views/c3.aiq",
+      content: c3Query
+    },
+    {
+      path: "examples/builtin-views/c4.aiq",
+      content: c4Query
+    },
     ...coreSkillFiles()
   ];
 }
@@ -38583,8 +38732,13 @@ If \`archinsight\` is not available, ask the user to install or expose
 2. Preserve indentation and the project's existing naming style.
 3. Model architecture from the outside inward: context, external actors/systems,
    systems, containers/services, components, and deployment details.
-4. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
-5. Validate every Insight change with \`archinsight link . --format text\`.
+4. When the task touches infrastructure, runtime placement, regions, or
+   deployment, decide per system whether pragmatic mixed C2 or clean
+   C4/deployment is appropriate.
+5. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
+6. Keep definition/framework files separate from model files that declare
+   \`context <id>\`.
+7. Validate every Insight change with \`archinsight link . --format text\`.
 
 ## References
 
@@ -38593,12 +38747,25 @@ If \`archinsight\` is not available, ask the user to install or expose
 - Read \`references/syntax.md\` before writing unfamiliar Insight syntax.
 - Read \`references/layered-architecture.md\` when decomposing a system across
   C1/C2/C3/C4-style layers.
+- Read \`references/c1-context.md\` when adding or repairing system context
+  models: actors, owned systems, external systems, and boundary choices.
+- Read \`references/c2-containers.md\` when adding or repairing
+  container/service-level C2 models for a selected system.
+- Read \`references/c3-components.md\` when adding or repairing component-level
+  C3 models for a selected container or service.
+- Read \`references/c4-deployment.md\` when adding or repairing deployment/C4
+  models, infrastructure inventories, environment-scoped infrastructure, or
+  projection rules.
+- Read \`references/scaling.md\` when splitting a repository into reusable
+  framework, environment, profile, system, or deployment-view files.
 - Read \`references/project-structure.md\` before searching for declarations,
   planning imports, or making broad edits.
 - Read \`references/core.md\` and \`.core/*.ai\` when checking built-in types,
   attributes, presentations, or projections.
 - Read \`references/queries.md\` when writing custom diagram queries or \`.aiq\`
   files.
+- Read \`references/query-recipes.md\` when a built-in view hides an expected
+  element/edge or needs customization.
 - Read \`references/validation.md\` before running checks, structure inspection,
   or rendering.
 - Use \`examples/layered-architecture.ai\` as a compact valid model.
@@ -38626,12 +38793,25 @@ Treat this \`SKILL.md\` as the entrypoint. Load reference files only when needed
 - Read \`references/syntax.md\` before writing unfamiliar Insight syntax.
 - Read \`references/layered-architecture.md\` before decomposing a system across
   C1/C2/C3/C4-style layers.
+- Read \`references/c1-context.md\` before adding or repairing system context
+  models: actors, owned systems, external systems, and boundary choices.
+- Read \`references/c2-containers.md\` before adding or repairing
+  container/service-level C2 models for a selected system.
+- Read \`references/c3-components.md\` before adding or repairing component-level
+  C3 models for a selected container or service.
+- Read \`references/c4-deployment.md\` before adding or repairing deployment/C4
+  models, infrastructure inventories, environment-scoped infrastructure, or
+  projection rules.
+- Read \`references/scaling.md\` before splitting a repository into reusable
+  framework, environment, profile, system, or deployment-view files.
 - Read \`references/project-structure.md\` before searching for declarations,
   planning imports, or making broad edits.
 - Read \`references/core.md\` and \`.core/*.ai\` before assuming available
   constructors, attributes, presentations, or projections.
 - Read \`references/queries.md\` before writing custom diagram queries or \`.aiq\`
   files.
+- Read \`references/query-recipes.md\` before customizing a built-in view or
+  explaining why an expected element/edge is hidden.
 - Read \`references/validation.md\` before running checks, structure inspection,
   or rendering commands.
 
@@ -38658,11 +38838,16 @@ If \`archinsight\` is not available, ask the user to install or expose
 2. Preserve indentation and the project's existing naming style.
 3. Model architecture from the outside inward: context, external actors/systems,
    systems, containers/services, components, and deployment details.
-4. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
-5. Use \`archinsight structure . --format text\` before broad edits when the
+4. When the task touches infrastructure, runtime placement, regions, or
+   deployment, decide per system whether pragmatic mixed C2 or clean
+   C4/deployment is appropriate.
+5. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
+6. Keep definition/framework files separate from model files that declare
+   \`context <id>\`.
+7. Use \`archinsight structure . --format text\` before broad edits when the
    project shape is unclear.
-6. Validate every Insight change with \`archinsight link . --format text\`.
-7. If validation fails, fix the first real syntax/type/linking error before
+8. Validate every Insight change with \`archinsight link . --format text\`.
+9. If validation fails, fix the first real syntax/type/linking error before
    adding more model content.
 
 ## References
@@ -38672,12 +38857,25 @@ If \`archinsight\` is not available, ask the user to install or expose
 - Read \`references/syntax.md\` before writing unfamiliar Insight syntax.
 - Read \`references/layered-architecture.md\` when decomposing a system across
   C1/C2/C3/C4-style layers.
+- Read \`references/c1-context.md\` when adding or repairing system context
+  models: actors, owned systems, external systems, and boundary choices.
+- Read \`references/c2-containers.md\` when adding or repairing
+  container/service-level C2 models for a selected system.
+- Read \`references/c3-components.md\` when adding or repairing component-level
+  C3 models for a selected container or service.
+- Read \`references/c4-deployment.md\` when adding or repairing deployment/C4
+  models, infrastructure inventories, environment-scoped infrastructure, or
+  projection rules.
+- Read \`references/scaling.md\` when splitting a repository into reusable
+  framework, environment, profile, system, or deployment-view files.
 - Read \`references/project-structure.md\` before searching for declarations,
   planning imports, or making broad edits.
 - Read \`references/core.md\` and \`.core/*.ai\` when checking built-in types,
   attributes, presentations, or projections.
 - Read \`references/queries.md\` when writing custom diagram queries or \`.aiq\`
   files.
+- Read \`references/query-recipes.md\` when a built-in view hides an expected
+  element/edge or needs customization.
 - Read \`references/validation.md\` before running checks, structure inspection,
   or rendering.
 - Use \`examples/layered-architecture.ai\` as a compact valid model.
@@ -38706,12 +38904,25 @@ they are needed:
 - Read \`references/syntax.md\` before writing unfamiliar Insight syntax.
 - Read \`references/layered-architecture.md\` before decomposing a system across
   C1/C2/C3/C4-style layers.
+- Read \`references/c1-context.md\` before adding or repairing system context
+  models: actors, owned systems, external systems, and boundary choices.
+- Read \`references/c2-containers.md\` before adding or repairing
+  container/service-level C2 models for a selected system.
+- Read \`references/c3-components.md\` before adding or repairing component-level
+  C3 models for a selected container or service.
+- Read \`references/c4-deployment.md\` before adding or repairing deployment/C4
+  models, infrastructure inventories, environment-scoped infrastructure, or
+  projection rules.
+- Read \`references/scaling.md\` before splitting a repository into reusable
+  framework, environment, profile, system, or deployment-view files.
 - Read \`references/project-structure.md\` before searching for declarations,
   planning imports, or making broad edits.
 - Read \`references/core.md\` and \`.core/*.ai\` before assuming available
   constructors, attributes, presentations, or projections.
 - Read \`references/queries.md\` before writing custom diagram queries or \`.aiq\`
   files.
+- Read \`references/query-recipes.md\` before customizing a built-in view or
+  explaining why an expected element/edge is hidden.
 - Read \`references/validation.md\` before asking the user to run validation,
   structure inspection, or rendering commands.
 
@@ -38738,12 +38949,17 @@ install or expose \`@archinsight/cli\` before changing \`.ai\` files.
 2. Preserve indentation and the project's existing naming style.
 3. Model architecture from the outside inward: context, external actors/systems,
    systems, containers/services, components, and deployment details.
-4. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
-5. Use \`archinsight structure . --format text\` to inspect the current model
+4. When the task touches infrastructure, runtime placement, regions, or
+   deployment, decide per system whether pragmatic mixed C2 or clean
+   C4/deployment is appropriate.
+5. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
+6. Keep definition/framework files separate from model files that declare
+   \`context <id>\`.
+7. Use \`archinsight structure . --format text\` to inspect the current model
    before broad edits when the CLI is available.
-6. Validate every Insight change with \`archinsight link . --format text\` when
+8. Validate every Insight change with \`archinsight link . --format text\` when
    shell access is available; otherwise ask the user to run validation.
-7. If validation fails, fix the first real syntax/type/linking error before
+9. If validation fails, fix the first real syntax/type/linking error before
    adding more model content.
 
 ## Communication
@@ -38772,12 +38988,25 @@ sections of Insight unless the existing layering is already understood.
 - Read \`references/syntax.md\` before writing unfamiliar Insight syntax.
 - Read \`references/layered-architecture.md\` when decomposing a system across
   C1/C2/C3/C4-style layers.
+- Read \`references/c1-context.md\` when adding or repairing system context
+  models: actors, owned systems, external systems, and boundary choices.
+- Read \`references/c2-containers.md\` when adding or repairing
+  container/service-level C2 models for a selected system.
+- Read \`references/c3-components.md\` when adding or repairing component-level
+  C3 models for a selected container or service.
+- Read \`references/c4-deployment.md\` when adding or repairing deployment/C4
+  models, infrastructure inventories, environment-scoped infrastructure, or
+  projection rules.
+- Read \`references/scaling.md\` when splitting a repository into reusable
+  framework, environment, profile, system, or deployment-view files.
 - Read \`references/project-structure.md\` before searching for declarations,
   planning imports, or making broad edits.
 - Read \`references/core.md\` and \`.core/*.ai\` when checking built-in types,
   attributes, presentations, or projections.
 - Read \`references/queries.md\` when writing custom diagram queries or \`.aiq\`
   files.
+- Read \`references/query-recipes.md\` when a built-in view hides an expected
+  element/edge or needs customization.
 - Read \`references/validation.md\` before running checks, structure inspection,
   or rendering.
 - Use \`examples/layered-architecture.ai\` as a compact valid model.
@@ -38799,6 +39028,40 @@ function genericModelingReference() {
 Insight syntax is small; most mistakes are modeling mistakes. Decide the view
 question before changing files.
 
+## Separate Definitions From Model Sources
+
+Keep language/framework definitions separate from graph model files.
+
+- Definition/framework files contain \`define type\`, \`define operator\`,
+  \`define presentation\`, \`extend type\`, \`extend enum of\`, and
+  \`extend presentation\`.
+- Model files declare \`context <id>\` and create graph objects with
+  constructors such as \`system\`, \`service\`, \`component\`, \`environment\`,
+  or \`deploymentProfile\`.
+
+Do not mix definition declarations and \`context\` declarations in one source
+file. Put shared vocabulary in a framework file, then put concrete contexts,
+systems, environments, profiles, and links in model files. This keeps schema
+changes reviewable and avoids source-level syntax failures.
+
+## Model Source Granularity
+
+Default to one primary owned system per model source file: the system you are
+about to detail with containers, services, components, and deployment
+relationships. This keeps the selected source file useful as a C2/C3/C4 view
+scope and avoids accidental mega-files.
+
+Do not create one file per external actor or external system. Shared external
+dependencies are usually better modeled once in a reusable external context, or
+in a few external contexts grouped by meaning such as \`external_platforms\`,
+\`partners\`, or \`regulators\`. Import those shared declarations from system
+files that need them.
+
+If a user asks for deeper splitting, use \`extend <object>\` files for the
+detail being extracted. For example, keep the main service file readable and put
+large per-service component sets in a small utility subdirectory for that
+context.
+
 ## Projections Are Bottom-Up
 
 Built-in C1/C2/C3/C4 views are selected from the linked model. They are not
@@ -38862,14 +39125,30 @@ type hierarchy:
 If a nested declaration fails type checking, fix the type/ownership model rather
 than forcing a link or inventing a wrapper element.
 
-## Keep Infrastructure in the Right View
+## Choose Infrastructure Depth Per System
+
+Do not force every project into C4/deployment on the first pass. Most modeling
+work can proceed through C1-C3 without asking about deployment depth. When the
+task first touches infrastructure, runtime placement, regions, compute, brokers,
+gateways, storage, or deployment, ask the user or infer from the repository
+whether the affected system needs a pragmatic mixed C2 view or a clean
+C4/deployment model.
 
-Do not transcribe infrastructure into C2 just because another diagram drew it
-there. Databases, queues, secret stores, compute nodes, gateways, and runtime
-placement are usually deployment/C4 concerns unless the project defines them as
-part of the selected view.
+Pragmatic mixed C2 is fast: model databases, brokers, gateways, or secret stores
+next to services when the user wants a quick single-environment diagram. The
+cost is that C2 now mixes logical containers with infrastructure, and C4 is
+effectively absent for that system.
 
-Use deployment types and projection queries when physical realization matters.
+Clean C4 keeps C2 logical and moves physical realization into deployment
+profiles, environments, inventory slots, and projection rules. This is more work
+up front, but it supports many-to-many deployment: one logical service can run
+in several environments whose infrastructure differs by region, provider, or
+organizational boundary.
+
+This choice is per-system, not global. A critical system can use clean C4 while
+peripheral systems stay pragmatic in C2. Starting cheap is acceptable, but know
+that upgrading mixed C2 infrastructure into clean C4 is a migration, not just an
+extra attribute.
 
 ## Eventing
 
@@ -38877,8 +39156,10 @@ Use \`~>\` for asynchronous relationships. Model one async wire per meaningful
 topic or event flow between real producer and consumer elements.
 
 Do not invent a broker node just to make the diagram look familiar. If the
-broker is deployment infrastructure, model it in deployment/C4. If the producer
-or consumer is not known, leave a gap and report it instead of fabricating an
+chosen style is clean C4 and the broker is deployment infrastructure, model it
+in deployment/C4. If the chosen style is pragmatic mixed C2, a broker-like node
+can be acceptable, but document that the view mixes levels. If the producer or
+consumer is not known, leave a gap and report it instead of fabricating an
 element.
 
 ## No Fabricated Elements
@@ -38962,6 +39243,11 @@ Definition files are different from model files. They declare vocabulary:
 \`extend enum of\`, and \`extend presentation\`. Model files usually start with
 \`context <id>\` and then create graph object instances with constructors.
 
+Do not mix these source forms in one file. A framework/definitions file should
+contain only vocabulary/schema declarations. A model file should declare a
+\`context <id>\` and graph object instances. If both are needed, create two
+files and validate the whole project.
+
 ## Type Definitions and Extensions
 
 Use \`define type\` to create a new graph/value type. Use \`extend type\` to add
@@ -39121,8 +39407,8 @@ label feature.
 Projects can extend the language with typed vocabulary:
 
 \`\`\`insight
-define type Broker of InfrastructureComponent
-    constructor broker
+define type Cache of InfrastructureComponent
+    constructor cache
 \`\`\`
 
 When adding custom types, follow the existing framework files and validate
@@ -39138,7 +39424,8 @@ layer useful on its own.
 
 ## C1: System Context
 
-Start with the context, people, owned systems, and external dependencies.
+Start with the context, people, owned systems, and external dependencies. Read
+\`references/c1-context.md\` before writing a real C1 model.
 
 \`\`\`insight
 context ecommerce
@@ -39165,7 +39452,8 @@ which external dependencies matter. Whether a peer is an owned \`system\`, an
 
 ## C2: Containers and Services
 
-Nest deployable units under the owned system:
+Nest deployable units under the owned system. Read
+\`references/c2-containers.md\` before writing a real C2 model.
 
 \`\`\`insight
 system storefront
@@ -39191,8 +39479,9 @@ the selected source file.
 
 ## C3: Components
 
-Put component details in a separate file with \`extend\` when the service becomes
-interesting enough to decompose:
+Put component details in a separate file with \`extend\` when a container or
+service becomes interesting enough to decompose. Read
+\`references/c3-components.md\` before writing a real C3 model.
 
 \`\`\`insight
 context ecommerce
@@ -39218,7 +39507,7 @@ can intentionally choose a different scope.
 ## C4 and Deployment
 
 Use deployment profiles and infrastructure types when physical realization is
-important:
+important. Read \`references/c4-deployment.md\` before writing a real C4 model.
 
 \`\`\`insight
 deploymentProfile production
@@ -39229,9 +39518,12 @@ environment eu
     name = Europe
 \`\`\`
 
-Attach deployment details to systems, containers, services, or links only when
-they clarify real runtime paths.
-C4/deployment files often focus one deployment slice, but the rendered scope is
+Attach deployment details to systems, containers, services, components, or links
+only when they clarify real runtime paths. Prefer attaching deployment to C2
+containers/services when possible because C2 is usually the most representative
+logical runtime boundary.
+
+C4/deployment files often focus one deployment slice. The rendered scope is
 defined by the query, projection selectors, and selected source file.
 
 ## Layering Rules
@@ -39246,6 +39538,1618 @@ defined by the query, projection selectors, and selected source file.
 - Validate after each layer before adding the next.
 `;
 }
+function genericC1ContextReference() {
+  return `# C1 System Context
+
+Use this reference only for C1 work: modeling a bounded context, its users,
+owned systems, external systems, and high-level relationships.
+
+## What C1 Answers
+
+A C1 view answers: "What system are we discussing, who uses it, and which
+outside systems does it depend on?"
+
+Do not include containers, services, components, databases, queues, or runtime
+nodes unless the project deliberately treats them as context-level systems. C1
+is about boundaries and responsibilities, not implementation structure.
+
+## C1 Workflow
+
+1. Name the bounded \`context <id>\`.
+2. Add external actors that initiate or consume behavior.
+3. Add owned \`system\` declarations inside the modeled boundary.
+4. Add \`external system\` declarations for dependencies outside the boundary.
+5. Add high-level links that explain business or capability flow.
+6. Validate with \`archinsight link . --format text\`.
+7. Render with \`archinsight render . -c <context-id> -v c1 -f svg -o c1.svg\`.
+
+## Boundary Choices
+
+Choose the modeled boundary before choosing constructors.
+
+- Use \`system\` for systems owned inside the current context.
+- Use \`external system\` for systems outside the current context boundary.
+- Use \`external actor\` for people, roles, teams, or external automation that
+  interacts with the system from outside.
+- Use \`import <id> from context <context-id>\` when a reusable outside system is
+  declared in another context.
+
+Externality is relative. A system can be external to the current system but
+still owned in the same context. A vendor platform or regulator is usually
+external to the context.
+
+## Basic C1 Pattern
+
+\`\`\`insight
+context commerce
+    name = Commerce Platform
+
+external actor shopper
+    name = Shopper
+    technology = Browser
+    description = Browses products and places orders
+    links:
+        -> storefront
+            description = Shops and checks out
+
+external actor support_agent
+    name = Support agent
+    technology = Back-office browser
+    description = Helps customers investigate orders
+    links:
+        -> order_admin
+            description = Looks up order state and customer communication
+
+external system payment_provider
+    name = Payment Provider
+    technology = HTTPS API
+    description = Authorizes card payments
+
+system storefront
+    name = Storefront
+    technology = Web application
+    description = Lets shoppers browse products and place orders
+    links:
+        -> payment_provider
+            technology = HTTPS
+            description = Requests payment authorization
+
+system order_admin
+    name = Order Admin
+    technology = Internal web application
+    description = Lets support staff inspect and manage orders
+    links:
+        -> storefront
+            description = Reads customer order data
+\`\`\`
+
+## Owned Peer Pattern
+
+Do not make every peer \`external system\`. If two systems are owned inside the
+same architecture boundary, keep both as \`system\` and link them:
+
+\`\`\`insight
+context company_platform
+    name = Company Platform
+
+system fintech
+    name = Fintech
+    description = Payment and account capabilities
+
+system compliance
+    name = Compliance
+    description = Compliance rules, audit, and reporting
+    links:
+        -> fintech
+            description = Reads transactions for screening and reporting
+\`\`\`
+
+Here \`fintech\` can be outside the compliance team boundary, but it is not
+outside the company platform context. Use the context boundary, not team
+ownership alone, to decide \`system\` vs \`external system\`.
+
+## Reusable External Context Pattern
+
+When the same outside dependency appears in many contexts, declare it once and
+import it:
+
+\`\`\`insight
+context external_platforms
+
+external system stripe
+    name = Stripe
+    technology = HTTPS API
+    description = External payment platform
+\`\`\`
+
+\`\`\`insight
+context commerce
+
+import stripe from context external_platforms
+
+system storefront
+    name = Storefront
+    links:
+        -> stripe from external_platforms
+            technology = HTTPS
+            description = Requests payment authorization
+\`\`\`
+
+Use imports for shared declarations; do not duplicate the same vendor system in
+every context unless the project intentionally wants separate local identities.
+
+## C1 Links
+
+Links should be high-level and readable:
+
+\`\`\`insight
+links:
+    -> storefront
+        description = Places orders
+\`\`\`
+
+Add \`technology\`, \`call\`, or \`via\` only when the detail is stable and useful
+at context level. Prefer capability language over endpoint trivia.
+
+Use \`~>\` for meaningful asynchronous context flows:
+
+\`\`\`insight
+links:
+    ~> analytics_platform
+        technology = Kafka
+        via = order.completed
+        description = Publishes completed order events
+\`\`\`
+
+## What Not To Put In C1
+
+- Internal containers such as \`web_app\`, \`api\`, or \`worker\`.
+- Components, classes, packages, screens, handlers, or repositories.
+- Databases, queues, pods, nodes, gateways, or regions unless modeled as
+  context-level systems.
+- Low-level calls between internals.
+- Placeholder systems invented only to make the diagram symmetric.
+
+## Common C1 Mistakes
+
+- Treating a peer owned in the same context as \`external system\`.
+- Duplicating imported external systems instead of importing the shared
+  declaration.
+- Adding implementation details that belong to C2/C3/C4.
+- Drawing a relationship without naming what capability or dependency it means.
+- Choosing constructors before deciding the context boundary.
+
+## Validation Commands
+
+\`\`\`shell
+archinsight structure . --format text
+archinsight link . --format text
+archinsight render . -c commerce -v c1 -f svg -o commerce-c1.svg
+\`\`\`
+
+Use \`examples/c1-context.ai\` as a compact valid C1 model when syntax is
+unclear.
+`;
+}
+function genericC2ContainersReference() {
+  return `# C2 Containers and Services
+
+Use this reference only for C2 work: decomposing one selected owned system into
+deployable containers, backend services, and their runtime collaborations.
+
+## What C2 Answers
+
+A C2 view answers: "Inside this system, which deployable or executable units
+exist, what technologies do they use, and how do they collaborate?"
+
+Prefer one focal system per C2 source file. The built-in C2 view is scoped by
+the selected source file, so a C2 file should usually contain the selected
+\`system <id>\` declaration or an \`extend system <id>\` block with its
+containers/services.
+
+## C2 Purity vs Pragmatic Infrastructure
+
+The clean C2 answer is logical: deployable containers/services and how they
+collaborate. In that mode, databases, brokers, gateways, vaults, compute, and
+regions belong to C4/deployment.
+
+Archinsight does not force that choice. For a quick or single-environment model,
+it is acceptable to put simple infrastructure-like runtime nodes into C2 when
+the user wants speed over strict layer separation. Be explicit about the
+tradeoff: the C2 view becomes mixed, C4 is not really modeled for that system,
+and many-to-many deployment across different environments will not be available
+until the model is migrated to clean C4.
+
+Choose this per system. Do not make the whole repository clean or mixed just
+because one system needs that style.
+
+## C2 Workflow
+
+1. Run \`archinsight structure . --format text\` to find the exact system id,
+   existing containers/services, and external declarations.
+2. Create or edit a C2 file in the same \`context <id>\`.
+3. Import external systems from other contexts when needed.
+4. Add \`container\` declarations for deployable applications or executables.
+5. Add \`service\` declarations for backend services or service-like runtime
+   units.
+6. Add runtime links between containers/services and real external systems.
+7. Validate with \`archinsight link . --format text\`.
+8. Render with \`archinsight render . -c <context-id> -s <c2-file.ai> -v c2 -f svg -o c2.svg\`.
+
+## File Split Pattern
+
+Keep C1 focused on the system boundary:
+
+\`\`\`insight
+context commerce
+    name = Commerce Platform
+
+external system payment_provider
+    name = Payment Provider
+    technology = HTTPS API
+
+system storefront
+    name = Storefront
+    technology = Commerce system
+    description = Lets shoppers browse products and place orders
+\`\`\`
+
+Put C2 details in a system file:
+
+\`\`\`insight
+context commerce
+
+extend system storefront
+    container web_app
+        name = Web app
+        technology = SvelteKit, TypeScript
+        description = Renders product pages and checkout screens
+        links:
+            -> checkout_api
+                technology = HTTPS, JSON
+                call = POST /checkout
+                description = Starts checkout and shows order status
+
+    service checkout_api
+        name = Checkout API
+        technology = Kotlin, PostgreSQL
+        description = Prices carts, creates orders, and coordinates payment
+        links:
+            -> payment_provider
+                technology = HTTPS
+                call = POST /payments/authorizations
+                description = Requests payment authorization
+\`\`\`
+
+## Frontend and Backend Pattern
+
+Use \`container\` for applications and executables that have an addressable
+runtime boundary:
+
+\`\`\`insight
+container web_app
+    name = Web app
+    technology = SvelteKit, TypeScript
+    description = Browser-facing application for customers
+\`\`\`
+
+Use \`service\` for backend services and service-like runtime units:
+
+\`\`\`insight
+service checkout_api
+    name = Checkout API
+    technology = Kotlin, PostgreSQL
+    description = Coordinates checkout and payment authorization
+\`\`\`
+
+Do not turn every library, package, or class into a C2 node. Those belong to C3
+only when they become stable architectural responsibilities.
+
+## External System Pattern
+
+For an external dependency declared in the same context:
+
+\`\`\`insight
+external system payment_provider
+    name = Payment Provider
+    technology = HTTPS API
+
+system storefront
+    name = Storefront
+
+    service checkout_api
+        name = Checkout API
+        links:
+            -> payment_provider
+                technology = HTTPS
+                call = POST /payments/authorizations
+\`\`\`
+
+For a dependency declared in another context, import it:
+
+\`\`\`insight
+context commerce
+
+import stripe from context external_platforms
+
+extend system storefront
+    service checkout_api
+        name = Checkout API
+        links:
+            -> stripe from external_platforms
+                technology = HTTPS
+                call = POST /payments/authorizations
+\`\`\`
+
+Do not copy an outside system into the current context just to satisfy a link.
+Import the real declaration when it is shared.
+
+## Async and Eventing Pattern
+
+Use \`~>\` for meaningful asynchronous relationships:
+
+\`\`\`insight
+service checkout_api
+    name = Checkout API
+    links:
+        ~> analytics_platform
+            technology = Kafka
+            via = checkout.completed
+            description = Publishes completed checkout events
+\`\`\`
+
+Do not add a broker node just to make an event diagram look familiar. In clean
+C2, a broker is usually deployment/C4 infrastructure unless the project defines
+it as a runtime system or service in the selected view. In pragmatic mixed C2,
+adding a broker can be acceptable for a quick view, but it means the diagram is
+no longer strictly logical C2.
+
+## C2 Link Details
+
+Use link attributes to make runtime collaboration understandable:
+
+\`\`\`insight
+links:
+    -> checkout_api
+        technology = HTTPS, JSON
+        call = POST /checkout
+        description = Starts checkout and returns order status
+\`\`\`
+
+\`call\` is singular. Use \`via\` for async topics or channels. Keep endpoint
+details at C2 only when they clarify the architecture; otherwise use a plain
+\`description\`.
+
+## What Not To Put In C2
+
+- Components, classes, handlers, repositories, or UI widgets.
+- Deployment nodes, pods, regions, network gateways, or secret stores in clean
+  C2. Include them only when the user intentionally wants pragmatic mixed C2 or
+  the project models them as C2 runtime systems.
+- Database tables and internal schemas.
+- One-off scripts or build-time tools unless they are real runtime units.
+- Duplicate links already represented at a lower C3 level unless the C2 view is
+  intentionally showing the rollup.
+
+## Common C2 Mistakes
+
+- Adding C2 nodes directly under \`context\` instead of under a \`system\`.
+- Modeling infrastructure in C2 without deciding that the system is using the
+  pragmatic mixed-C2 style.
+- Mixing C2 container/service links with C3 component links in the same source
+  file without a clear view goal.
+- Forgetting \`--source <c2-file.ai>\` when rendering C2.
+- Making every peer an \`external system\` instead of deciding whether it is
+  owned in the current context.
+
+## Validation Commands
+
+\`\`\`shell
+archinsight structure . --format text
+archinsight link . --format text
+archinsight render . -c commerce -s storefront-containers.ai -v c2 -f svg -o storefront-c2.svg
+\`\`\`
+
+Use \`examples/c2-containers.ai\` as a compact valid C2 model when syntax is
+unclear.
+`;
+}
+function genericC3ComponentsReference() {
+  return `# C3 Components
+
+Use this reference only for C3 work: decomposing one selected container or
+service into internal components and their collaborations.
+
+## What C3 Answers
+
+A C3 view answers: "Inside this container/service, what named responsibilities
+collaborate to deliver its behavior?"
+
+Prefer one focal container or service per C3 source file. The built-in C3 view
+is scoped by the selected source file, so the C3 file should usually contain an
+\`extend container <id>\` or \`extend service <id>\` block for the focal element.
+
+Do not model every class, function, method, or package. A component should be a
+stable architectural responsibility that is useful in a diagram and review.
+
+## C3 Workflow
+
+1. Run \`archinsight structure . --format text\` to find the exact container or
+   service id, available constructors, and existing imports.
+2. Create or edit a C3 file in the same \`context <id>\`.
+3. Import elements from other contexts only when the component links to them.
+4. Use \`extend container <id>\` or \`extend service <id>\`.
+5. Add \`component\` declarations with \`name\`, \`technology\`, and
+   \`responsibility\`.
+6. Add links between components and to real external endpoints.
+7. Validate with \`archinsight link . --format text\`.
+8. Render with \`archinsight render . -c <context-id> -s <c3-file.ai> -v c3 -f svg -o c3.svg\`.
+
+## File Split Pattern
+
+Keep the C2 declaration small:
+
+\`\`\`insight
+context commerce
+    name = Commerce Platform
+
+external system payment_provider
+    name = Payment Provider
+    technology = HTTPS API
+
+system storefront
+    name = Storefront
+
+    service checkout_api
+        name = Checkout API
+        technology = Kotlin, PostgreSQL
+        description = Handles cart pricing, order placement, and payment orchestration
+\`\`\`
+
+Put component details in a C3 file:
+
+\`\`\`insight
+context commerce
+
+extend service checkout_api
+    component checkout_controller
+        name = Checkout controller
+        technology = REST controller
+        responsibility = Accepts checkout requests and returns order status
+        links:
+            -> checkout_service
+
+    component checkout_service
+        name = Checkout service
+        technology = Kotlin
+        responsibility = Coordinates pricing, payment authorization, and order creation
+        links:
+            -> payment_gateway
+            -> order_repository
+
+    component payment_gateway
+        name = Payment gateway
+        technology = HTTP client
+        responsibility = Translates internal payment commands to provider API calls
+        links:
+            -> payment_provider
+                technology = HTTPS
+                call = POST /payments/authorizations
+                description = Authorizes customer payment
+
+    component order_repository
+        name = Order repository
+        technology = SQL
+        responsibility = Persists order state and checkout audit records
+\`\`\`
+
+## Frontend Container Pattern
+
+Use C3 for UI responsibilities when the frontend container has distinct
+architectural parts:
+
+\`\`\`insight
+context commerce
+
+extend container web_app
+    component route_shell
+        name = Route shell
+        technology = SvelteKit routing
+        responsibility = Owns route loading, authenticated layout, and page composition
+        links:
+            -> checkout_page
+            -> session_store
+
+    component checkout_page
+        name = Checkout page
+        technology = Svelte
+        responsibility = Collects checkout input and presents order progress
+        links:
+            -> api_client
+
+    component session_store
+        name = Session store
+        technology = Browser storage
+        responsibility = Keeps current user and session state for client-side decisions
+
+    component api_client
+        name = API client
+        technology = Fetch, JSON
+        responsibility = Wraps backend API calls and maps transport errors to UI state
+        links:
+            -> checkout_api
+                technology = HTTPS, JSON
+                call = POST /checkout
+\`\`\`
+
+This is useful when frontend structure affects architecture. If the frontend is
+only a thin page with no meaningful internal decisions, leave it at C2.
+
+## Backend Service Pattern
+
+Use C3 to separate adapters, orchestration, domain logic, persistence, and
+integration boundaries:
+
+\`\`\`insight
+context commerce
+
+extend service inventory_api
+    component inventory_resource
+        name = Inventory resource
+        technology = REST
+        responsibility = Exposes stock reservations and availability endpoints
+        links:
+            -> reservation_service
+
+    component reservation_service
+        name = Reservation service
+        technology = Java
+        responsibility = Applies reservation rules and coordinates stock updates
+        links:
+            -> inventory_policy
+            -> reservation_repository
+            ~> inventory_events
+                technology = Kafka
+                via = inventory.reserved
+                description = Publishes successful reservation events
+
+    component inventory_policy
+        name = Inventory policy
+        technology = Java
+        responsibility = Decides whether stock can be promised to an order
+
+    component reservation_repository
+        name = Reservation repository
+        technology = SQL
+        responsibility = Stores reservation state and idempotency keys
+
+    component inventory_events
+        name = Inventory events
+        technology = Kafka producer
+        responsibility = Publishes inventory domain events for downstream systems
+\`\`\`
+
+Use \`->\` for synchronous calls and \`~>\` for asynchronous flows. Use singular
+\`call\` for the synchronous operation and \`via\` for the asynchronous topic,
+queue, or channel.
+
+## Imported Boundary Pattern
+
+When a component links to an element from another context, import it and use
+\`from <context-id>\` on the link target:
+
+\`\`\`insight
+context commerce
+
+import fraud_api from context risk_platform
+
+extend service checkout_api
+    component risk_adapter
+        name = Risk adapter
+        technology = HTTP client
+        responsibility = Requests fraud decisions before payment authorization
+        links:
+            -> fraud_api from risk_platform
+                technology = HTTPS
+                call = POST /risk/decisions
+                description = Requests checkout risk decision
+\`\`\`
+
+Do not copy an imported system into the current context just to make the C3
+diagram render. Import the real declaration and validate the link.
+
+## Component Naming
+
+Prefer names that reveal responsibility:
+
+- \`checkout_controller\`, \`checkout_service\`, \`payment_gateway\`
+- \`reservation_policy\`, \`reservation_repository\`, \`inventory_events\`
+- \`route_shell\`, \`checkout_page\`, \`api_client\`
+
+Avoid names that are only implementation trivia:
+
+- \`utils\`, \`helpers\`, \`module1\`, \`manager\`
+- individual classes unless the class is the architectural boundary
+- framework-generated files or folders
+
+## Responsibility Boundaries
+
+A good C3 component has at least one of these:
+
+- a distinct external adapter;
+- a domain or orchestration responsibility;
+- a persistence boundary;
+- an asynchronous producer or consumer role;
+- a security, policy, parsing, rendering, or transformation responsibility;
+- a UI composition, state, or backend API boundary that affects architecture.
+
+If a component cannot be described without mentioning code organization only,
+leave it out or ask for a more architectural boundary.
+
+## Links in C3
+
+Links should explain runtime collaboration inside the focal container/service.
+
+Use internal component links:
+
+\`\`\`insight
+links:
+    -> checkout_service
+\`\`\`
+
+Add call details when they matter:
+
+\`\`\`insight
+links:
+    -> payment_gateway
+        call = authorize(paymentCommand)
+        description = Requests payment authorization
+\`\`\`
+
+Use async details for events:
+
+\`\`\`insight
+links:
+    ~> inventory_events
+        via = inventory.reserved
+        description = Publishes reservation completion
+\`\`\`
+
+Do not add a broker as a component unless the broker is actually part of the
+focal container/service. Shared brokers, queues, gateways, and runtime placement
+usually belong to deployment/C4 or infrastructure modeling.
+
+## Common C3 Mistakes
+
+- Writing C3 components under a \`system\` instead of under a container/service
+  unless the project type model explicitly allows that.
+- Creating one C3 file for every class or package.
+- Linking to an external element without importing it when it lives in another
+  context.
+- Forgetting \`--source <c3-file.ai>\` when rendering C3.
+- Mixing C2 container links and C3 component links in one view question.
+- Keeping a broad container/service link and an equivalent lower-level component
+  link without deciding which level should own the relationship.
+- Inventing components to satisfy a diagram shape instead of describing real
+  responsibilities.
+
+## Validation Commands
+
+\`\`\`shell
+archinsight structure . --format text
+archinsight link . --format text
+archinsight render . -c commerce -s checkout_components.ai -v c3 -f svg -o checkout-c3.svg
+\`\`\`
+
+Use \`examples/c3-components.ai\` as a compact valid C3 model when syntax is
+unclear.
+`;
+}
+function genericC4DeploymentReference() {
+  return `# C4 Deployment and Infrastructure
+
+Use this reference only for C4 work: deployment profiles, environments,
+environment-scoped infrastructure inventory, \`uses\` / \`runsOn\`, and
+projection rules.
+
+## Contents
+
+- What C4 Answers
+- Before You Use C4
+- Mental Model
+- C4 Workflow
+- Environment Inventory
+- Why Infrastructure Is Per Environment
+- Attaching Deployment To C1-C3 Elements
+- usesProfile, environmentsFrom, runsOn, and uses
+- Deployment Archetypes
+- Projection Rules
+- Traffic Path Example
+- Compute and Grouping
+- Many-To-Many Deployment
+- What Not To Put In C4
+- Common C4 Mistakes
+- Validation Commands
+
+## What C4 Answers
+
+A C4/deployment view answers: "Where do logical architecture elements run, what
+environment-specific infrastructure do they use, and what physical path does a
+logical relationship expand into?"
+
+C4 is not just another decomposition level. C1-C3 mostly describe logical
+architecture. C4 maps logical elements and links onto environment-local
+infrastructure inventory.
+
+## Before You Use C4
+
+C4/deployment is optional. Do not push the user into environments, projection
+rules, and infrastructure inventory when they only need a quick logical/runtime
+view.
+
+If the work has reached infrastructure, runtime placement, regions, compute, or
+deployment, ask or infer the intended style for the current system:
+
+- Pragmatic mixed C2: put simple infrastructure-like runtime nodes such as a
+  database, broker, gateway, or vault near the services in C2. This is fast and
+  easier for simple or single-environment systems, but it mixes abstraction
+  levels and does not produce a real C4 model.
+- Clean C4: keep C2 logical and describe physical realization through
+  \`Environment\` slots, deployment profiles, inventory, \`runsOn\`, \`uses\`,
+  and projection rules. This takes more design work, but supports region/env
+  differences, many-to-many deployment, and organization-specific runtime
+  complexity.
+
+The choice is per-system. Model a critical system with clean C4 and keep a
+peripheral system pragmatic in C2 if that matches the user's needs. If a system
+starts as mixed C2 and later needs multi-env deployment, expect a migration:
+infrastructure nodes must move into environment inventory and links must gain
+deployment/projection semantics.
+
+## Mental Model
+
+There are three layers:
+
+1. Schema: extend \`Environment\` with infrastructure slots such as
+   \`Compute compute\`, \`Storage storage\`, \`Broker broker\`,
+   \`NetworkConnection network\`, or \`PublicGateway publicGateway\`.
+   \`Compute\`, \`Storage\`, \`Broker\`, and \`NetworkConnection\` are core
+   deployment types.
+2. Inventory: each \`environment <id>\` fills those slots with concrete
+   infrastructure instances for that environment.
+3. Deployment references: logical systems, containers, services, components, or
+   links use \`deployment:\` with \`runsOn\`, \`uses\`, \`usesProfile\`, or
+   \`environmentsFrom\` to reference the inventory.
+
+An \`InfrastructureComponent\` is not an orphan. It is usually inventory inside
+an \`environment\` slot. The hook is the type extension:
+
+\`\`\`insight
+extend type Environment
+    Compute compute
+    Storage storage
+    Broker broker
+    NetworkConnection network
+    PublicGateway publicGateway
+\`\`\`
+
+After that, every \`environment <id>\` can provide those slots:
+
+\`\`\`insight
+environment prod
+    name = Production
+
+    compute:
+        compute kube
+            name = Kubernetes
+
+    storage:
+        storage db
+            name = PostgreSQL
+
+    broker:
+        broker events
+            name = Event broker
+            address = kafka.prod.internal:9092
+
+    network:
+        networkConnection private_path
+            name = Private service path
+\`\`\`
+
+## C4 Workflow
+
+1. Inspect existing deployment types with \`archinsight structure . --format text\`.
+2. Read \`references/core.md\` and project framework files for existing
+   \`extend type Environment\`, infrastructure types, and projection rules.
+3. Add or reuse infrastructure types in a definition file. Prefer core
+   \`Compute\`, \`Storage\`, \`Broker\`, and \`NetworkConnection\` for common
+   deployment inventory.
+4. Extend \`Environment\` with slots for the infrastructure inventory.
+5. Create one or more \`environment <id>\` declarations and fill the slots.
+6. Add \`deploymentProfile\` declarations that select environments and common
+   \`runsOn\` / \`uses\` defaults.
+7. Attach \`deployment:\` blocks to logical elements or links.
+8. Validate with \`archinsight link . --format text\`.
+9. Render with \`archinsight render . -c <context-id> -s <c4-file.ai> -v c4 -f svg -o c4.svg\`.
+
+## Environment Inventory
+
+Define infrastructure vocabulary in a definition file:
+
+\`\`\`insight
+extend type Environment
+    ServiceProvider cloud
+    Compute compute
+    Storage storage
+    Broker broker
+    NetworkConnection network
+    PublicGateway publicGateway
+
+define type ServiceProvider of InfrastructureComponent
+    constructor serviceProvider
+
+define type PublicGateway of InfrastructureComponent
+    constructor publicGateway
+    required InfrastructureComponent cdn
+    required InfrastructureComponent loadBalancer
+\`\`\`
+
+Then fill concrete environments:
+
+\`\`\`insight
+environment prod
+    name = Production
+
+    cloud:
+        serviceProvider aws
+            name = AWS
+
+    compute:
+        compute eks
+            name = EKS
+            runsOn cloud
+
+    storage:
+        storage orders_db
+            name = Orders PostgreSQL
+            runsOn cloud
+
+    broker:
+        broker events
+            name = Event broker
+            technology = Kafka
+            address = kafka.prod.internal:9092
+            runsOn compute
+
+    network:
+        networkConnection private_path
+            name = Private service path
+            runsOn compute
+
+    publicGateway:
+        publicGateway public_edge
+            name = Public edge
+            cdn:
+                infrastructureComponent cloudfront
+                    name = CloudFront
+                    runsOn cloud
+            loadBalancer:
+                infrastructureComponent alb
+                    name = Application Load Balancer
+                    runsOn cloud
+            runsOn compute
+\`\`\`
+
+\`cloud\`, \`compute\`, \`storage\`, and \`publicGateway\` are slots on this
+specific \`prod\` environment. Another environment can fill the same slots with
+different concrete infrastructure.
+
+## Why Infrastructure Is Per Environment
+
+Infrastructure must be per environment because deployment is many-to-many:
+
+- one logical service can run in several environments;
+- each environment can use different compute, storage, gateways, regions, or
+  providers;
+- the same \`uses storage\` reference must resolve to the current environment's
+  storage instance, not to one global database node;
+- projection rules need environment-local inventory to expand logical edges into
+  physical paths.
+
+If infrastructure were modeled as global nodes, the model could not say:
+"Checkout API runs on EKS in production, Cloud Run in staging, and uses a
+different database in each environment" without duplicating logical services.
+
+## Attaching Deployment To C1-C3 Elements
+
+\`deployment\` is available on systems, containers/services, components, and
+wires. Attach it where it best represents the runtime boundary.
+
+Prefer C2 containers/services for most deployment mapping:
+
+- C1 systems are often too broad and hide real runtime placement.
+- C3 components are often too fine and can overfit code structure.
+- C2 containers/services usually represent deployable runtime units.
+
+Use C1 deployment only when the whole system is deployed as one unit. Use C3
+deployment when a component is independently deployed or has a distinct physical
+path. Use wire deployment when a specific logical relationship travels through
+infrastructure such as a public gateway, network connection, broker, or egress
+path.
+
+## Element-Level vs Wire-Level Infrastructure
+
+Attach infrastructure to an element when the projection only needs the deployed
+element itself:
+
+- \`runsOn compute\`: placement/grouping.
+- \`uses storage\`: the element depends on stateful infrastructure.
+- \`uses observability\`: monitoring sidecars or collectors around the element.
+
+Attach infrastructure to a wire when the projection needs a real target:
+
+- \`uses publicGateway\`: expands a caller-to-service path through ingress.
+- \`uses network\`: keeps a direct source-to-target network path on C4.
+- \`uses broker\`: both producer and consumer physically connect to the broker.
+
+Rule of thumb: if the infrastructure type's \`project:\` block mentions \`$to\`,
+use it on a relationship under \`links:\`. Using it on an element is invalid
+because an element deployment has no separate target endpoint.
+
+## usesProfile, environmentsFrom, runsOn, and uses
+
+\`deploymentProfile\` names a reusable deployment scope:
+
+\`\`\`insight
+deploymentProfile global
+    environments:
+        prod
+        staging
+
+    runsOn compute
+\`\`\`
+
+\`usesProfile\` copies the profile's environments and deployment operators to a
+logical element:
+
+\`\`\`insight
+service checkout_api
+    name = Checkout API
+    deployment:
+        usesProfile global
+        uses storage
+\`\`\`
+
+\`runsOn compute\` resolves the \`compute\` slot inside each selected
+environment and stores it as the logical element's placement. \`uses storage\`
+resolves the environment-local \`storage\` slot and projects edges to it.
+
+\`environmentsFrom global\` copies only the environments from a profile. It is
+useful on a link when the path should share the same environment set but use its
+own infrastructure. It deliberately does not copy \`runsOn\` or \`uses\` from
+the profile:
+
+\`\`\`insight
+links:
+    -> checkout_api
+        deployment:
+            environmentsFrom global
+            uses publicGateway
+\`\`\`
+
+\`usesProfile global\` copies environments and profile operators. Use it on an
+element when the profile's defaults apply. Use \`environmentsFrom global\` on a
+link when only the environment scope should be reused.
+
+You can also use \`environmentsFrom\` on an element when it should share the
+profile's environment list but choose its own placement or dependencies:
+
+\`\`\`insight
+service batch_worker
+    name = Batch Worker
+    deployment:
+        environmentsFrom regional_service
+        runsOn compute
+        uses storage
+\`\`\`
+
+Here \`batch_worker\` deploys to the same environments as
+\`regional_service\`, but it does not inherit \`regional_service\` defaults such
+as \`uses observability\`. Add every desired \`runsOn\` and \`uses\` explicitly.
+
+## Deployment Archetypes
+
+Use \`deploymentProfile\` to create named deployment archetypes such as
+\`global_service\`, \`regional_service\`, or \`public_regional_service\`. A
+profile should select concrete \`environment\` instances and attach the common
+deployment operators that most services of that archetype need.
+
+Example environment inventory:
+
+\`\`\`insight
+environment global_edge
+    name = Global edge
+
+    compute:
+        compute edge_runtime
+            name = Edge runtime
+
+    publicGateway:
+        publicGateway edge_gateway
+            name = Global public gateway
+            cdn:
+                infrastructureComponent cloudfront
+                    name = CloudFront
+            loadBalancer:
+                infrastructureComponent global_lb
+                    name = Global Load Balancer
+
+environment eu
+    name = Europe
+
+    compute:
+        compute kube_eu
+            name = Kubernetes EU
+
+    storage:
+        storage db_eu
+            name = PostgreSQL EU
+
+    observability:
+        monitoring otel_eu
+            name = OpenTelemetry Collector EU
+            display:
+                infrastructureComponent grafana
+                    name = Grafana Cloud
+\`\`\`
+
+Example profiles:
+
+\`\`\`insight
+deploymentProfile global_service
+    environments:
+        global_edge
+
+    runsOn compute
+
+deploymentProfile regional_service
+    environments:
+        eu
+
+    runsOn compute
+    uses observability
+\`\`\`
+
+Then attach the archetype with one \`usesProfile\`:
+
+\`\`\`insight
+container web_app
+    name = Web app
+    deployment:
+        usesProfile global_service
+    links:
+        -> checkout_api
+            deployment:
+                environmentsFrom global_service
+                uses publicGateway
+
+service checkout_api
+    name = Checkout API
+    deployment:
+        usesProfile regional_service
+        uses storage
+\`\`\`
+
+The profile supplies the common environment scope, placement, and element-level
+infrastructure. Additional local \`uses\` entries extend the profile for that
+specific element. In the example, \`checkout_api\` inherits regional compute and
+observability from \`regional_service\`, then adds its own \`uses storage\`
+because this service owns persistent state. The \`web_app -> checkout_api\` wire uses
+\`environmentsFrom global_service\` to reuse the environment list while attaching
+the path-only \`publicGateway\` projection to the relationship.
+
+Use separate profiles when the element-level defaults differ. For example,
+\`regional_service\` can include \`runsOn compute\` and \`uses observability\`,
+while \`regional_stateful_service\` can also include \`uses storage\`. Keep
+path-only infrastructure such as \`publicGateway\`, \`network\`, or \`broker\`
+on the wire deployment where the source and target are known.
+
+When an element should reuse only the environments from an archetype, use
+\`environmentsFrom <profile>\` instead of \`usesProfile <profile>\` and then add
+the local \`runsOn\` / \`uses\` entries explicitly.
+
+Do not try to make infrastructure global to avoid repeating profiles. The
+profile should select environment instances; the selected environments provide
+their own concrete infrastructure through slots.
+
+## Projection Rules
+
+Projection rules live on infrastructure types. They explain how a logical
+\`uses <slot>\` reference expands into projected graph edges.
+
+Core defaults:
+
+- \`Storage\`: \`$from -> $this\`.
+- \`Broker\`: \`$from -> $this\` and \`$to -> $this\`, because both sides
+  physically connect to the broker.
+- \`NetworkConnection\`: \`$from -> $to\`, for an ordinary direct network call
+  that should still appear on the deployment layer.
+
+Custom infrastructure types can define their own projection rules.
+
+\`\`\`insight
+define type PublicGateway of InfrastructureComponent
+    constructor publicGateway
+    required InfrastructureComponent cdn
+    required InfrastructureComponent loadBalancer
+
+    project:
+        $from -> cdn
+        cdn -> loadBalancer
+        loadBalancer -> $this
+        $this -> $to
+\`\`\`
+
+When a service says \`uses storage\`, the selected environment's storage instance
+receives a projected edge from the logical service:
+
+\`\`\`text
+checkout_api -> prod.orders_db
+checkout_api -> staging.orders_db
+\`\`\`
+
+When a wire says \`uses network\`, the selected environment's network connection
+keeps the logical source-to-target relationship visible in the deployment view:
+
+\`\`\`insight
+links:
+    -> checkout_api
+        deployment:
+            environmentsFrom regional_service
+            uses network
+\`\`\`
+
+If a logical relationship is missing from a C4/deployment diagram, check whether
+the wire has deployment information and uses a path-producing slot such as
+\`network\`, \`publicGateway\`, or another type with a \`project:\` rule. C4
+queries commonly select projected deployment edges; a plain logical wire without
+deployment projection may be correct in C2/C3 but absent from the deployment
+layer.
+
+If validation reports \`PROJECTION_TARGET_REQUIRED\`, you attached a projection
+that uses \`$to\` to an element. Move that \`uses ...\` entry to the relevant
+wire and reuse the element's environment scope with \`environmentsFrom\`.
+
+Projection terms:
+
+- \`$from\` is the logical source of the deployment use.
+- \`$to\` is the logical target when the deployment is attached to a wire.
+- \`$this\` is the infrastructure component instance selected by \`uses\`.
+- plain names such as \`cdn\` or \`loadBalancer\` are attributes/slots on
+  \`$this\`.
+
+## Traffic Path Example
+
+A public gateway can expand one logical edge into a physical path:
+
+\`\`\`insight
+define type PublicGateway of InfrastructureComponent
+    constructor publicGateway
+    required InfrastructureComponent cdn
+    required InfrastructureComponent loadBalancer
+
+    project:
+        $from -> cdn
+        cdn -> loadBalancer
+        loadBalancer -> $this
+        $this -> $to
+\`\`\`
+
+Given this logical relationship:
+
+\`\`\`insight
+external actor customer
+    name = Customer
+    links:
+        -> web_app
+            deployment:
+                environmentsFrom public_regional_service
+                uses publicGateway
+\`\`\`
+
+And this environment inventory:
+
+\`\`\`insight
+environment prod
+    name = Production
+
+    publicGateway:
+        publicGateway public_edge
+            name = Public edge
+            cdn:
+                infrastructureComponent cloudfront
+                    name = CloudFront
+            loadBalancer:
+                infrastructureComponent alb
+                    name = Application Load Balancer
+\`\`\`
+
+The projection creates the physical path:
+
+\`\`\`text
+customer -> cloudfront -> alb -> public_edge -> web_app
+\`\`\`
+
+The logical edge remains the authoring intent. The projected edges are derived
+from deployment inventory and the \`project:\` rule.
+
+## Compute and Grouping
+
+\`runsOn compute\` is placement, not a traffic path by itself. It resolves the
+selected environment's compute slot and marks where a logical element runs:
+
+\`\`\`insight
+deploymentProfile regional_service
+    environments:
+        prod
+        staging
+
+    runsOn compute
+    uses observability
+
+deploymentProfile public_regional_service
+    environments:
+        prod
+        staging
+
+    runsOn compute
+    uses observability
+
+service checkout_api
+    name = Checkout API
+    deployment:
+        usesProfile global
+\`\`\`
+
+If \`prod.compute\` is EKS and \`staging.compute\` is Cloud Run, the same
+\`checkout_api\` can render in both compute groups. The built-in C4 query groups
+by \`node.runsOn\`, so compute is usually the visual grouping anchor.
+
+Use \`runsOn\` on infrastructure too:
+
+\`\`\`insight
+storage orders_db
+    name = Orders PostgreSQL
+    runsOn cloud
+\`\`\`
+
+This places the database under its provider or parent infrastructure in the
+rendered deployment graph.
+
+## Many-To-Many Deployment
+
+This is the core reason for the model:
+
+\`\`\`insight
+deploymentProfile global
+    environments:
+        prod
+        staging
+
+    runsOn compute
+
+service checkout_api
+    name = Checkout API
+    deployment:
+        usesProfile global
+        uses storage
+\`\`\`
+
+If \`prod.compute = EKS\`, \`prod.storage = Aurora\`,
+\`staging.compute = Cloud Run\`, and \`staging.storage = Cloud SQL\`, the single
+logical service projects into both environments without duplicating
+\`checkout_api\`.
+
+## What Not To Put In C4
+
+- Global infrastructure nodes when the infrastructure differs by environment.
+- Logical components invented only to represent physical routing.
+- C3 internals unless they are independently deployed.
+- Cloud resources with no relationship to a deployment question.
+- A broker/gateway/load balancer in C2 just because it appears in deployment,
+  unless the system intentionally uses the pragmatic mixed-C2 style.
+
+## Common C4 Mistakes
+
+- Defining infrastructure types but forgetting to extend \`Environment\` with
+  slots for them.
+- Creating \`infrastructureComponent\` nodes at context level when they should
+  live in an \`environment\` inventory slot.
+- Using \`usesProfile\` on a wire when only \`environmentsFrom\` is intended.
+- Forgetting \`--source <c4-file.ai>\` when rendering C4.
+- Expecting \`runsOn\` to draw traffic; use \`project:\` rules and \`uses\` for
+  traffic/path projections.
+- Treating projected edges as source declarations; they are derived.
+
+## Validation Commands
+
+\`\`\`shell
+archinsight structure . --format text
+archinsight link . --format text
+archinsight render . -c deployment_shop -s c4-deployment.ai -v c4 -f svg -o deployment-c4.svg
+\`\`\`
+
+Use \`examples/c4-deployment-framework.ai\` and \`examples/c4-deployment.ai\` as
+a compact valid C4 model when syntax is unclear.
+`;
+}
+function genericScalingReference() {
+  return `# Scaling an Archinsight Repository
+
+Use this reference when a project grows beyond one or two files and you need to
+reuse definitions, environments, deployment profiles, or systems without
+duplicating them.
+
+## Repository Shape
+
+Prefer one shared framework per repository:
+
+- one definitions/framework area for \`extend type Environment\`, custom
+  infrastructure types, presentation tweaks, projection-capable infrastructure,
+  and reusable deployment profiles;
+- source files grouped by context directories when the repository is large;
+- model files that usually focus on one primary owned system being detailed;
+- one or more inventory files for concrete \`environment <id>\` instances and
+  their env-local infrastructure;
+- shared external contexts for external actors and systems reused by many
+  systems;
+- focused deployment-view files that attach deployment profiles and per-view
+  traffic paths.
+
+Do not copy the same \`extend type Environment\`, infra type definitions, or
+\`deploymentProfile\` blocks into every system file. Define the vocabulary and
+reusable archetypes once, import or reference them where needed, and validate the
+whole project.
+
+## Framework Once, Use Everywhere
+
+A typical deployment framework file contains only shared vocabulary: type
+definitions, type extensions, projection rules, and presentation overrides. Do
+not mix \`define type\` / \`extend type\` declarations and \`context\`
+declarations in the same source file.
+
+\`\`\`insight
+define type PublicGateway of InfrastructureComponent
+    constructor publicGateway
+    required InfrastructureComponent cdn
+    required InfrastructureComponent loadBalancer
+
+    project:
+        $from -> cdn
+        cdn -> loadBalancer
+        loadBalancer -> $this
+        $this -> $to
+
+extend type Environment
+    Compute compute
+    Storage storage
+    Broker broker
+    PublicGateway publicGateway
+    NetworkConnection network
+\`\`\`
+
+Concrete inventory/profile files then declare contexts, environments, and
+profiles:
+
+\`\`\`insight
+context infra
+    name = Shared Infrastructure
+
+environment prod_eu
+    name = Production EU
+    compute:
+        compute ecs
+            name = ECS
+            technology = AWS ECS
+    broker:
+        broker kafka
+            name = Kafka
+            technology = MSK
+            address = kafka.prod.eu.internal
+
+deploymentProfile regional_service
+    environments:
+        prod_eu
+
+    runsOn compute
+\`\`\`
+
+System files should reuse these definitions instead of recreating \`compute\`,
+\`broker\`, or profile declarations locally.
+
+## System Files and External Contexts
+
+The default model file is centered on one owned system:
+
+\`\`\`text
+commerce/
+    checkout.ai
+    catalog.ai
+    fulfillment.ai
+external/
+    platforms.ai
+    regulators.ai
+\`\`\`
+
+\`commerce/checkout.ai\` would declare \`context commerce\`, the
+\`system checkout\` focal object, and the containers/services/components needed
+to explain checkout. \`commerce/catalog.ai\` would do the same for catalog.
+
+Shared external actors and systems should not be copied into every system file.
+Put them in one external context, or a few semantically grouped external
+contexts:
+
+\`\`\`insight
+context external_platforms
+
+external system stripe
+    name = Stripe
+
+external system sendgrid
+    name = SendGrid
+\`\`\`
+
+Then import them where needed:
+
+\`\`\`insight
+context commerce
+
+import stripe from context external_platforms
+
+system checkout
+    links:
+        -> stripe from external_platforms
+\`\`\`
+
+Avoid making a separate file for every external actor or vendor unless the
+external dependency itself has substantial reusable structure. A small number of
+well-named external contexts gives all repository systems one shared vocabulary
+for outside dependencies.
+
+When a system file becomes too large, split details by extending the focal
+object in utility subdirectories:
+
+\`\`\`text
+commerce/
+    checkout.ai
+    checkout-components/
+        pricing.ai
+        payment.ai
+        inventory.ai
+\`\`\`
+
+Those files should repeat the same \`context commerce\`, explicitly import the
+object being extended when it lives in another source file, and use
+\`extend service checkout_api\`, \`extend container web_app\`, or another object
+extension to add focused details.
+
+## Same-Context Cross-File Imports
+
+Insight resolves unqualified ids in this order: declarations in the same source
+file, explicit imports in the same source file, then it reports an error if the
+same id exists only in another source file of the same context.
+
+That means splitting one context across files still requires imports:
+
+\`\`\`insight
+context services
+
+deploymentProfile eu_service
+\`\`\`
+
+\`\`\`insight
+context services
+
+import eu_service from context services
+
+system checkout
+    name = Checkout
+    deployment:
+        usesProfile eu_service
+\`\`\`
+
+This is intentional. If a file is extracted, removed, or not included in the
+project, the linker should fail with an explicit identifier/import diagnostic
+instead of silently binding to whatever remains in the context.
+
+## Inline from Context
+
+When a relationship target is declared outside the current source file, prefer
+an explicit context qualifier on the link target:
+
+\`\`\`insight
+context commerce
+
+import payments from context external_systems
+
+system checkout
+    name = Checkout
+    links:
+        -> payments from external_systems
+            technology = HTTPS
+            call = POST /payments
+\`\`\`
+
+The \`import <id> from context <context-id>\` line documents the dependency and
+makes the id available for attributes such as profiles and environment slots.
+The inline \`from <context-id>\` on a link target states which context owns the
+linked element. Use the same pattern for same-context cross-file links when the
+source has been split and ambiguity matters:
+
+\`\`\`insight
+context services
+
+import inventory_api from context services
+
+system checkout_api
+    links:
+        -> inventory_api from services
+            technology = HTTPS
+            call = GET /inventory
+\`\`\`
+
+This explicitness is useful during refactors: if the source file holding
+\`inventory_api\` disappears, validation points at the missing declaration
+instead of creating a hidden dependency on file layout.
+
+## C4 Multi-File Pattern
+
+For C4, keep these responsibilities separate:
+
+- framework file: type extensions, infra constructors, presentation/projection
+  definitions;
+- inventory/profile file: concrete environments and reusable deployment
+  profiles;
+- deployment-view file: the relationships whose deployment path you want to
+  render for one selected view.
+
+When rendering C4 with \`-s <source.ai>\`, remember that source/tab scoping is
+part of the view. Put the view-driving logical relationships in the selected
+source file, or render from the source file that owns those relationships. Keep
+imported framework and inventory reusable, but validate the rendered C4 output
+after moving traffic relationships across files:
+
+\`\`\`shell
+archinsight link . --format text
+archinsight render . -c deployment_shop -s c4-deployment.ai -v c4 -f svg -o deployment-c4.svg
+\`\`\`
+
+If projected infrastructure edges disappear after a split, first check whether
+the selected \`-s\` file still contains the source logical relationship or an
+intended imported deployment-view relationship. Do not fix that by duplicating
+infrastructure nodes; fix the source selection or the file boundary.
+
+## Practical Workflow
+
+1. Run \`archinsight structure . --format text\`.
+2. Identify contexts, source files, and declaration ids before editing.
+3. Move shared vocabulary into one framework file.
+4. Group model files by context directory when the repository is large.
+5. Keep each ordinary system file focused on one owned system being detailed.
+6. Put external actors/systems in shared external contexts, not one file per
+   external element.
+7. Move reusable environments and deployment profiles into inventory/profile
+   files.
+8. Add explicit imports for every cross-file dependency, including same-context
+   dependencies.
+9. Add inline \`from <context-id>\` on relationship targets that live outside
+   the current source file.
+10. Validate with \`archinsight link . --format text\`.
+11. Render important C1/C2/C3/C4 views with explicit \`-c\`, \`-s\`, and \`-v\`
+   options.
+`;
+}
 function genericProjectStructureReference() {
   return `# Project Structure Workflow
 
@@ -39253,6 +41157,37 @@ Use \`archinsight structure\` before broad edits, imports, or declaration lookup
 Do not start with raw grep when you need to know what the linked project
 contains.
 
+## Source File Classes
+
+Keep source files in one role:
+
+- definition/framework files: \`define type\`, \`define operator\`,
+  \`define presentation\`, \`extend type\`, \`extend enum of\`, and
+  \`extend presentation\`;
+- model files: \`context <id>\`, imports, graph object declarations,
+  relationships, environments, and deployment profiles.
+
+Do not mix definition/framework declarations with \`context <id>\` in one file.
+When a model needs custom vocabulary, add or edit a framework file first, then
+use the resulting constructors and attributes from model files.
+
+## Directory and File Granularity
+
+For larger repositories, group model files by context directory. Inside a
+context directory, default to one primary owned system per ordinary model file:
+the system that will be detailed by containers, services, components, links, and
+deployment information.
+
+External actors and systems are different. Put reusable outside dependencies in
+one external context or a few semantically grouped external contexts. Do not
+create a separate file for every external actor or vendor unless that external
+dependency has real internal structure to model.
+
+If a system needs further splitting, create a utility subdirectory for focused
+\`extend <object>\` files, such as per-service component files. Import the
+extended object explicitly when it is declared in another source file. Keep the
+main system file as the readable entry point.
+
 ## Commands
 
 Human-readable overview:
@@ -39300,6 +41235,33 @@ links:
     -> payments from external_systems
 \`\`\`
 
+Imports are also required when a declaration lives in another source file of the
+same context:
+
+\`\`\`insight
+context services
+
+import eu_service from context services
+
+system checkout_api
+    deployment:
+        usesProfile eu_service
+\`\`\`
+
+The explicit import is intentional. If the source file that declared
+\`eu_service\` is removed or excluded, validation should fail with a clear
+missing import/identifier diagnostic instead of depending on hidden file layout.
+
+For links, \`from <context-id>\` on the target is an inline context qualifier:
+
+\`\`\`insight
+links:
+    -> inventory_api from services
+\`\`\`
+
+Use it when the relationship target is owned by another context or another
+source file whose context ownership should remain visible at the call site.
+
 Do not guess context ids from filenames. Filenames, context ids, and element ids
 can differ.
 
@@ -39357,6 +41319,25 @@ Interpretation:
 Users can define more types in project files. Always inspect project structure
 and project framework files before assuming only core constructors exist.
 
+## Built-in Deployment Infrastructure
+
+\`core_deployment.ai\` provides common infrastructure inventory types:
+
+- \`InfrastructureComponent\`: optional \`name\`, \`technology\`,
+  \`description\`, plus deployment references.
+- \`Storage\` / constructor \`storage\`: for databases, buckets, volumes, and
+  other stateful stores.
+- \`Broker\` / constructor \`broker\`: for message brokers and event buses;
+  adds optional \`address\`.
+- \`Compute\` / constructor \`compute\`: for runtimes, clusters, nodes, and
+  platforms; adds optional \`address\` and can contain nested infrastructure
+  components in a \`components:\` block.
+- \`NetworkConnection\` / constructor \`networkConnection\`: for a direct
+  network hop that projects \`$from -> $to\` on deployment views.
+
+Extend \`Environment\` with slots for these types, then fill each concrete
+\`environment <id>\` with env-local instances.
+
 ## Reading Type Extensions
 
 Project files can extend built-in or custom types:
@@ -39365,6 +41346,7 @@ Project files can extend built-in or custom types:
 extend type Environment
     Compute compute
     Storage storage
+    Broker broker
 \`\`\`
 
 Interpretation:
@@ -39737,6 +41719,16 @@ diagram needs stable layout.
 
 ## Built-In View Patterns
 
+Exact built-in query sources are bundled in:
+
+\`\`\`text
+examples/builtin-views/no-filter.aiq
+examples/builtin-views/c1.aiq
+examples/builtin-views/c2.aiq
+examples/builtin-views/c3.aiq
+examples/builtin-views/c4.aiq
+\`\`\`
+
 C1 usually selects systems in the selected context and rolls lower-level links
 up to system-level relationships.
 
@@ -39749,6 +41741,10 @@ and returns component relationships.
 C4 usually selects deployment and container nodes from \`$tab\`, uses
 \`OPTIONAL MATCH ROLLUP\`, and returns projected relationships.
 
+When a built-in view is close but hides the wrong thing, read
+\`references/query-recipes.md\`, copy the nearest built-in \`.aiq\`, and change
+the filter or grouping deliberately.
+
 ## Authoring Rules
 
 - Start from the view question: context, containers, components, or deployment.
@@ -39759,6 +41755,189 @@ C4 usually selects deployment and container nodes from \`$tab\`, uses
 - Keep custom queries in \`.aiq\` files when they are reused.
 `;
 }
+function genericQueryRecipesReference() {
+  return `# Query Recipes and Built-In View Customization
+
+Use this reference when a built-in C1/C2/C3/C4 view is close but not quite right:
+an expected element is hidden, a relationship is missing, infrastructure is too
+noisy, or the diagram needs a different scope.
+
+## Start From Built-In Queries
+
+The generated skill includes exact built-in view queries:
+
+\`\`\`text
+examples/builtin-views/no-filter.aiq
+examples/builtin-views/c1.aiq
+examples/builtin-views/c2.aiq
+examples/builtin-views/c3.aiq
+examples/builtin-views/c4.aiq
+\`\`\`
+
+Before inventing a query from scratch, open the nearest built-in query, copy it
+to the project, and make the smallest change.
+
+\`\`\`shell
+archinsight query . -c <context-id> -s <source.ai> -q queries/custom.aiq -f text
+archinsight render . -c <context-id> -s <source.ai> -q queries/custom.aiq -f svg -o custom.svg
+\`\`\`
+
+Use \`references/queries.md\` for syntax details. Use this file for common
+customization patterns.
+
+## When To Customize
+
+Write or adjust a \`.aiq\` query when:
+
+- the built-in view hides a node or edge that exists in \`archinsight link\`;
+- the source/tab scope is right but the view intentionally filters out a type;
+- C4 should include actors, vendors, or a special deployment path;
+- the diagram should show only one layer, one flow, or one relationship class;
+- grouping needs to change, such as grouping by parent instead of \`runsOn\`.
+
+Do not compensate for a view filter by duplicating model elements. First inspect
+the built-in query and decide whether the model or the query owns the behavior.
+
+## Diagnose A Missing Element
+
+1. Validate the model:
+
+\`\`\`shell
+archinsight link . --format text
+\`\`\`
+
+2. Inspect declarations and source identities:
+
+\`\`\`shell
+archinsight structure . --format text
+\`\`\`
+
+3. Run the built-in query text explicitly:
+
+\`\`\`shell
+archinsight query . -c <context-id> -s <source.ai> -q examples/builtin-views/c4.aiq -f text
+\`\`\`
+
+4. Check the query filters:
+
+- \`node.sourceIdentity = $tab\` means the node must be declared in the selected
+  source file.
+- \`node IS DeploymentElement\` hides actors and ordinary logical elements.
+- \`{projected}\` means only derived deployment projection edges are selected.
+- \`{derived}\` means only rolled-up relationships are selected.
+- \`sourceIdentity: $tab\` on an edge means the relationship/projection must come
+  from the selected source.
+
+## Include External Actors In C4
+
+The built-in C4 query focuses on deployment/container nodes. If a deployment
+diagram needs the external actor that starts the traffic path, copy
+\`examples/builtin-views/c4.aiq\` and widen the node and projected target filters:
+
+\`\`\`cypher
+MATCH (node:Element)
+WHERE node.sourceIdentity = $tab
+  AND (node IS DeploymentElement OR node IS ContainerElement OR node IS Actor)
+OPTIONAL MATCH ROLLUP (node)-[projectedLink {projected, sourceIdentity: $tab}]->(projectedTarget:Element)
+WHERE projectedTarget IS DeploymentElement
+   OR projectedTarget IS ContainerElement
+   OR projectedTarget IS External
+   OR projectedTarget IS Actor
+OPTIONAL MATCH (node)-[directDeploymentLink {sourceIdentity: $tab}]->(directDeploymentTarget:Element)
+WHERE node IS DeploymentElement
+  AND (directDeploymentTarget IS DeploymentElement OR directDeploymentTarget IS External)
+GROUP BY node.runsOn
+RETURN node, projectedLink, projectedTarget, directDeploymentLink, directDeploymentTarget
+\`\`\`
+
+If the actor is declared in another source file, either render from that source
+or relax the \`node.sourceIdentity = $tab\` condition intentionally.
+
+## Show Only Async Flows
+
+Use edge attributes when the question is about relationship kind:
+
+\`\`\`cypher
+MATCH (source:Element)-[link]->(target:Element)
+WHERE source.context = $context
+  AND link.model = 'async'
+GROUP BY source.parent
+RETURN source, link, target
+\`\`\`
+
+This is useful for event-stream, broker, queue, or notification diagrams. Add
+\`source.sourceIdentity = $tab\` when the query should stay scoped to one file.
+
+## Hide Deployment Infrastructure
+
+When a C4-oriented source file is too noisy and you only need logical containers
+or services, select logical container elements and direct logical relationships:
+
+\`\`\`cypher
+MATCH (node:ContainerElement)
+WHERE node.sourceIdentity = $tab
+OPTIONAL MATCH (node)-[link]->(target:ContainerElement)
+GROUP BY node.parent
+RETURN node, link, target
+\`\`\`
+
+This is intentionally closer to C2 than C4. Use it when deployment annotations
+exist in the file but the diagram question is still logical.
+
+## Show Projected Edges Across Split Files
+
+The built-in C4 query restricts projected edges to \`sourceIdentity: $tab\`. That
+is usually correct for a focused deployment-view source file, but it can hide
+projected edges when traffic relationships were split across files.
+
+Copy \`examples/builtin-views/c4.aiq\` and relax only the projected edge selector:
+
+\`\`\`cypher
+MATCH (node:Element)
+WHERE node.sourceIdentity = $tab
+  AND (node IS DeploymentElement OR node IS ContainerElement)
+OPTIONAL MATCH ROLLUP (node)-[projectedLink {projected}]->(projectedTarget:Element)
+WHERE projectedTarget IS DeploymentElement
+   OR projectedTarget IS ContainerElement
+   OR projectedTarget IS External
+OPTIONAL MATCH (node)-[directDeploymentLink {sourceIdentity: $tab}]->(directDeploymentTarget:Element)
+WHERE node IS DeploymentElement
+  AND (directDeploymentTarget IS DeploymentElement OR directDeploymentTarget IS External)
+GROUP BY node.runsOn
+RETURN node, projectedLink, projectedTarget, directDeploymentLink, directDeploymentTarget
+\`\`\`
+
+Use this deliberately. Removing the source filter can bring in projections from
+other view files, so validate the result with \`archinsight query\` before
+rendering.
+
+## Change Grouping
+
+Grouping controls visual clusters. If C4 grouping by \`runsOn\` is not helpful,
+try grouping by parent:
+
+\`\`\`cypher
+MATCH (node:Element)
+WHERE node.sourceIdentity = $tab
+  AND (node IS DeploymentElement OR node IS ContainerElement)
+OPTIONAL MATCH ROLLUP (node)-[projectedLink {projected, sourceIdentity: $tab}]->(projectedTarget:Element)
+WHERE projectedTarget IS DeploymentElement
+   OR projectedTarget IS ContainerElement
+   OR projectedTarget IS External
+GROUP BY node.parent
+RETURN node, projectedLink, projectedTarget
+\`\`\`
+
+Use \`GROUP BY node.runsOn\` for deployment placement; use \`GROUP BY node.parent\`
+for logical ownership.
+
+## Working Rule
+
+If a diagram looks wrong but \`archinsight link\` is clean, inspect the selected
+source, built-in query, and returned aliases before changing the model. Many
+display issues are query scope issues, not schema or linker bugs.
+`;
+}
 function genericLayeredArchitectureExample() {
   return `context shop
     name = Shop Platform
@@ -39811,6 +41990,429 @@ system storefront
             responsibility = Calls the payment provider and normalizes errors
 `;
 }
+function genericC1ContextExample() {
+  return `context customer_portal
+    name = Customer Portal
+
+external actor customer
+    name = Customer
+    technology = Browser, mobile app
+    description = Manages account details and service requests
+    links:
+        -> portal
+            description = Views account state and submits requests
+
+external actor support_agent
+    name = Support agent
+    technology = Back-office browser
+    description = Helps customers resolve account and service issues
+    links:
+        -> service_console
+            description = Reviews account state and updates service requests
+
+external system identity_provider
+    name = Identity Provider
+    technology = OIDC
+    description = Authenticates customers and support staff
+
+external system notification_platform
+    name = Notification Platform
+    technology = Email, SMS
+    description = Sends customer notifications
+
+system portal
+    name = Portal
+    technology = Web application
+    description = Customer-facing self-service experience
+    links:
+        -> identity_provider
+            technology = OIDC
+            description = Authenticates customers
+        -> notification_platform
+            technology = HTTPS
+            description = Sends request status notifications
+
+system service_console
+    name = Service Console
+    technology = Internal web application
+    description = Support-facing account and request management
+    links:
+        -> portal
+            description = Reads customer account and request state
+        -> identity_provider
+            technology = OIDC
+            description = Authenticates support staff
+`;
+}
+function genericC2ContainersExample() {
+  return `context fulfillment
+    name = Fulfillment Platform
+
+external actor warehouse_operator
+    name = Warehouse operator
+    technology = Browser
+    description = Picks, packs, and ships orders
+    links:
+        -> warehouse_ui
+            description = Processes pick, pack, and ship work
+
+external system carrier_api
+    name = Carrier API
+    technology = HTTPS API
+    description = Books shipments and returns tracking updates
+
+external system notification_platform
+    name = Notification Platform
+    technology = HTTPS API
+    description = Sends shipment notifications to customers
+
+system fulfillment
+    name = Fulfillment
+    technology = Fulfillment system
+    description = Coordinates packing, shipping, and customer shipment updates
+
+    container warehouse_ui
+        name = Warehouse UI
+        technology = React, TypeScript
+        description = Guides warehouse operators through pick, pack, and ship flows
+        links:
+            -> fulfillment_api
+                technology = HTTPS, JSON
+                call = POST /shipments
+                description = Creates and updates shipment work
+
+    service fulfillment_api
+        name = Fulfillment API
+        technology = Kotlin, PostgreSQL
+        description = Owns fulfillment workflow state and carrier integration
+        links:
+            -> carrier_api
+                technology = HTTPS
+                call = POST /labels
+                description = Buys shipment labels
+            -> notification_worker
+                description = Enqueues shipment notification work
+
+    service notification_worker
+        name = Notification Worker
+        technology = Node.js worker
+        description = Sends asynchronous shipment notifications
+        links:
+            -> notification_platform
+                technology = HTTPS
+                call = POST /messages
+                description = Sends shipment status notifications
+`;
+}
+function genericC3ComponentsExample() {
+  return `context commerce
+    name = Commerce Platform
+
+external actor shopper
+    name = Shopper
+    technology = Browser
+    links:
+        -> web_app
+
+external system payment_provider
+    name = Payment Provider
+    technology = HTTPS API
+
+external system analytics_platform
+    name = Analytics Platform
+    technology = Kafka consumer
+
+system storefront
+    name = Storefront
+    technology = Commerce system
+
+    container web_app
+        name = Web app
+        technology = SvelteKit, TypeScript
+        description = Presents checkout screens and calls the backend API
+
+        component checkout_page
+            name = Checkout page
+            technology = Svelte
+            responsibility = Collects checkout details and shows order progress
+            links:
+                -> api_client
+
+        component api_client
+            name = API client
+            technology = Fetch, JSON
+            responsibility = Wraps backend calls and maps transport errors to UI state
+            links:
+                -> checkout_api
+                    technology = HTTPS, JSON
+                    call = POST /checkout
+
+    service checkout_api
+        name = Checkout API
+        technology = Kotlin, PostgreSQL
+        description = Prices carts, creates orders, and coordinates payment
+        links:
+            ~> analytics_platform
+                technology = Kafka
+                via = checkout.completed
+                description = Publishes completed checkout events
+
+        component checkout_controller
+            name = Checkout controller
+            technology = REST controller
+            responsibility = Accepts checkout requests and returns order status
+            links:
+                -> checkout_service
+
+        component checkout_service
+            name = Checkout service
+            technology = Kotlin
+            responsibility = Coordinates pricing, payment authorization, and order creation
+            links:
+                -> payment_gateway
+                    call = authorize(paymentCommand)
+                    description = Requests payment authorization
+                -> order_repository
+                ~> checkout_events
+                    technology = Kafka
+                    via = checkout.completed
+                    description = Publishes completed checkout events
+
+        component payment_gateway
+            name = Payment gateway
+            technology = HTTP client
+            responsibility = Translates internal payment commands to provider API calls
+            links:
+                -> payment_provider
+                    technology = HTTPS
+                    call = POST /payments/authorizations
+                    description = Authorizes customer payment
+
+        component order_repository
+            name = Order repository
+            technology = SQL
+            responsibility = Stores order state and checkout audit records
+
+        component checkout_events
+            name = Checkout events
+            technology = Kafka producer
+            responsibility = Publishes checkout lifecycle events for downstream consumers
+`;
+}
+function genericC4DeploymentFrameworkExample() {
+  return `extend type Environment
+    ServiceProvider cloud
+    Compute compute
+    Storage storage
+    Broker broker
+    PublicGateway publicGateway
+    Monitoring observability
+    NetworkConnection network
+
+define type ServiceProvider of InfrastructureComponent
+    constructor serviceProvider
+
+define type PublicGateway of InfrastructureComponent
+    constructor publicGateway
+    required InfrastructureComponent cdn
+    required InfrastructureComponent loadBalancer
+
+    project:
+        $from -> cdn
+        cdn -> loadBalancer
+        loadBalancer -> $this
+        $this -> $to
+
+define type Monitoring of InfrastructureComponent
+    constructor monitoring
+    required InfrastructureComponent display
+
+    project:
+        $this -> $from
+        $this -> display
+
+`;
+}
+function genericC4DeploymentExample() {
+  return `context deployment_shop
+    name = Deployment Shop
+
+external actor shopper
+    name = Shopper
+    technology = Browser
+    links:
+        -> web_app
+            deployment:
+                environmentsFrom public_regional_service
+                uses publicGateway
+
+external system payment_provider
+    name = Payment Provider
+    technology = HTTPS API
+
+deploymentProfile regional_service
+    environments:
+        prod
+        staging
+
+    runsOn compute
+    uses observability
+
+deploymentProfile public_regional_service
+    environments:
+        prod
+        staging
+
+    runsOn compute
+    uses observability
+
+environment prod
+    name = Production
+
+    cloud:
+        serviceProvider _
+            name = AWS
+
+    compute:
+        compute _
+            name = EKS
+            runsOn cloud
+
+    storage:
+        storage _
+            name = Aurora PostgreSQL
+            technology = PostgreSQL
+            runsOn cloud
+
+    broker:
+        broker _
+            name = Event broker
+            technology = MSK Kafka
+            address = kafka.prod.internal:9092
+            runsOn compute
+
+    publicGateway:
+        publicGateway _
+            name = Public edge
+            cdn:
+                infrastructureComponent cloudfront
+                    name = CloudFront
+                    runsOn cloud
+            loadBalancer:
+                infrastructureComponent alb
+                    name = Application Load Balancer
+                    runsOn cloud
+            runsOn compute
+
+    observability:
+        monitoring _
+            name = OpenTelemetry Collector
+            display:
+                infrastructureComponent _
+                    name = Grafana Cloud
+            runsOn compute
+
+    network:
+        networkConnection _
+            name = Service mesh
+            runsOn compute
+
+environment staging
+    name = Staging
+
+    cloud:
+        serviceProvider _
+            name = Google Cloud
+
+    compute:
+        compute _
+            name = Cloud Run
+            runsOn cloud
+
+    storage:
+        storage _
+            name = Cloud SQL
+            technology = PostgreSQL
+            runsOn cloud
+
+    broker:
+        broker _
+            name = Event broker
+            technology = Pub/Sub
+            address = pubsub.googleapis.com
+            runsOn compute
+
+    publicGateway:
+        publicGateway _
+            name = Public edge
+            cdn:
+                infrastructureComponent cloud_cdn
+                    name = Cloud CDN
+                    runsOn cloud
+            loadBalancer:
+                infrastructureComponent https_lb
+                    name = HTTPS Load Balancer
+                    runsOn cloud
+            runsOn compute
+
+    observability:
+        monitoring _
+            name = Cloud Monitoring Agent
+            display:
+                infrastructureComponent _
+                    name = Cloud Monitoring
+            runsOn compute
+
+    network:
+        networkConnection _
+            name = Internal routes
+            runsOn compute
+
+system storefront
+    name = Storefront
+    technology = Commerce system
+
+    container web_app
+        name = Web app
+        technology = SvelteKit, TypeScript
+        description = Customer-facing checkout application
+        deployment:
+            usesProfile public_regional_service
+        links:
+            -> checkout_api
+                technology = HTTPS, JSON
+                call = POST /checkout
+                deployment:
+                    environmentsFrom regional_service
+                    uses network
+
+    service checkout_api
+        name = Checkout API
+        technology = Kotlin, PostgreSQL
+        description = Creates orders and coordinates payment
+        deployment:
+            usesProfile regional_service
+            uses storage
+        links:
+            ~> order_worker
+                technology = Kafka
+                via = orders.events
+                deployment:
+                    environmentsFrom regional_service
+                    uses broker
+
+            -> payment_provider
+                technology = HTTPS
+                call = POST /payments/authorizations
+
+    service order_worker
+        name = Order Worker
+        technology = Kotlin
+        description = Processes order events asynchronously
+        deployment:
+            usesProfile regional_service
+`;
+}
 function genericC2QueryExample() {
   return `MATCH (container:ContainerElement)
 WHERE container.sourceIdentity = $tab