@archinsight/cli 3.0.0 → 3.0.1

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, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { instance } from "@viz-js/viz";
 
@@ -22530,7 +22530,7 @@ var InsightParser = class _InsightParser extends Parser {
         this.state = 288;
         this.errorHandler.sync(this);
         _la = this.tokenStream.LA(1);
-        while ((_la & ~31) === 0 && (1 << _la & 58720512) !== 0 || (_la - 34 & ~31) === 0 && (1 << _la - 34 & 6695) !== 0) {
+        while ((_la & ~31) === 0 && (1 << _la & 58720512) !== 0 || (_la - 34 & ~31) === 0 && (1 << _la - 34 & 6759) !== 0) {
           {
             {
               this.state = 285;
@@ -24748,10 +24748,27 @@ var InsightParser = class _InsightParser extends Parser {
     let localContext = new IdentifierReferenceContext(this.context, this.state);
     this.enterRule(localContext, 136, _InsightParser.RULE_identifierReference);
     try {
-      this.enterOuterAlt(localContext, 1);
-      {
-        this.state = 692;
-        this.identifier();
+      this.state = 694;
+      this.errorHandler.sync(this);
+      switch (this.tokenStream.LA(1)) {
+        case _InsightParser.PROJECT:
+        case _InsightParser.PROJECTION:
+        case _InsightParser.IDENTIFIER:
+          this.enterOuterAlt(localContext, 1);
+          {
+            this.state = 692;
+            this.identifier();
+          }
+          break;
+        case _InsightParser.ANONYMOUS_ATTRIBUTE:
+          this.enterOuterAlt(localContext, 2);
+          {
+            this.state = 693;
+            this.match(_InsightParser.ANONYMOUS_ATTRIBUTE);
+          }
+          break;
+        default:
+          throw new NoViableAltException(this);
       }
     } catch (re) {
       if (re instanceof RecognitionException) {
@@ -24771,7 +24788,7 @@ var InsightParser = class _InsightParser extends Parser {
     try {
       this.enterOuterAlt(localContext, 1);
       {
-        this.state = 694;
+        this.state = 696;
         this.identifier();
       }
     } catch (re) {
@@ -24792,7 +24809,7 @@ var InsightParser = class _InsightParser extends Parser {
     try {
       this.enterOuterAlt(localContext, 1);
       {
-        this.state = 696;
+        this.state = 698;
         this.identifier();
       }
     } catch (re) {
@@ -24813,7 +24830,7 @@ var InsightParser = class _InsightParser extends Parser {
     try {
       this.enterOuterAlt(localContext, 1);
       {
-        this.state = 698;
+        this.state = 700;
         this.identifier();
       }
     } catch (re) {
@@ -24834,7 +24851,7 @@ var InsightParser = class _InsightParser extends Parser {
     try {
       this.enterOuterAlt(localContext, 1);
       {
-        this.state = 700;
+        this.state = 702;
         this.constructorName();
       }
     } catch (re) {
@@ -24855,7 +24872,7 @@ var InsightParser = class _InsightParser extends Parser {
     try {
       this.enterOuterAlt(localContext, 1);
       {
-        this.state = 702;
+        this.state = 704;
         this.identifier();
       }
     } catch (re) {
@@ -24876,9 +24893,9 @@ var InsightParser = class _InsightParser extends Parser {
     try {
       this.enterOuterAlt(localContext, 1);
       {
-        this.state = 704;
+        this.state = 706;
         this.match(_InsightParser.COMMENT);
-        this.state = 705;
+        this.state = 707;
         this.match(_InsightParser.EOL);
       }
     } catch (re) {
@@ -24899,7 +24916,7 @@ var InsightParser = class _InsightParser extends Parser {
     try {
       this.enterOuterAlt(localContext, 1);
       {
-        this.state = 707;
+        this.state = 709;
         this.match(_InsightParser.COMMENT);
       }
     } catch (re) {
@@ -24918,20 +24935,20 @@ var InsightParser = class _InsightParser extends Parser {
     let localContext = new TriviaContext(this.context, this.state);
     this.enterRule(localContext, 152, _InsightParser.RULE_trivia);
     try {
-      this.state = 711;
+      this.state = 713;
       this.errorHandler.sync(this);
       switch (this.tokenStream.LA(1)) {
         case _InsightParser.COMMENT:
           this.enterOuterAlt(localContext, 1);
           {
-            this.state = 709;
+            this.state = 711;
             this.commentLine();
           }
           break;
         case _InsightParser.EOL:
           this.enterOuterAlt(localContext, 2);
           {
-            this.state = 710;
+            this.state = 712;
             this.match(_InsightParser.EOL);
           }
           break;
@@ -24954,7 +24971,7 @@ var InsightParser = class _InsightParser extends Parser {
     4,
     1,
     49,
-    714,
+    716,
     2,
     0,
     7,
@@ -26439,6 +26456,11 @@ var InsightParser = class _InsightParser extends Parser {
     68,
     1,
     68,
+    3,
+    68,
+    695,
+    8,
+    68,
     1,
     69,
     1,
@@ -26475,7 +26497,7 @@ var InsightParser = class _InsightParser extends Parser {
     76,
     3,
     76,
-    712,
+    714,
     8,
     76,
     1,
@@ -26586,7 +26608,7 @@ var InsightParser = class _InsightParser extends Parser {
     25,
     39,
     39,
-    744,
+    747,
     0,
     157,
     1,
@@ -26996,55 +27018,55 @@ var InsightParser = class _InsightParser extends Parser {
     0,
     0,
     136,
-    692,
+    694,
     1,
     0,
     0,
     0,
     138,
-    694,
+    696,
     1,
     0,
     0,
     0,
     140,
-    696,
+    698,
     1,
     0,
     0,
     0,
     142,
-    698,
+    700,
     1,
     0,
     0,
     0,
     144,
-    700,
+    702,
     1,
     0,
     0,
     0,
     146,
-    702,
+    704,
     1,
     0,
     0,
     0,
     148,
-    704,
+    706,
     1,
     0,
     0,
     0,
     150,
-    707,
+    709,
     1,
     0,
     0,
     0,
     152,
-    711,
+    713,
     1,
     0,
     0,
@@ -30920,25 +30942,31 @@ var InsightParser = class _InsightParser extends Parser {
     0,
     0,
     692,
-    693,
+    695,
     3,
     122,
     61,
     0,
     693,
-    137,
+    695,
+    5,
+    40,
+    0,
+    0,
+    694,
+    692,
     1,
     0,
     0,
     0,
     694,
-    695,
-    3,
-    122,
-    61,
+    693,
+    1,
+    0,
+    0,
     0,
     695,
-    139,
+    137,
     1,
     0,
     0,
@@ -30950,7 +30978,7 @@ var InsightParser = class _InsightParser extends Parser {
     61,
     0,
     697,
-    141,
+    139,
     1,
     0,
     0,
@@ -30962,7 +30990,7 @@ var InsightParser = class _InsightParser extends Parser {
     61,
     0,
     699,
-    143,
+    141,
     1,
     0,
     0,
@@ -30970,11 +30998,11 @@ var InsightParser = class _InsightParser extends Parser {
     700,
     701,
     3,
-    90,
-    45,
+    122,
+    61,
     0,
     701,
-    145,
+    143,
     1,
     0,
     0,
@@ -30982,76 +31010,88 @@ var InsightParser = class _InsightParser extends Parser {
     702,
     703,
     3,
-    122,
-    61,
+    90,
+    45,
     0,
     703,
-    147,
+    145,
     1,
     0,
     0,
     0,
     704,
     705,
+    3,
+    122,
+    61,
+    0,
+    705,
+    147,
+    1,
+    0,
+    0,
+    0,
+    706,
+    707,
     5,
     46,
     0,
     0,
-    705,
-    706,
+    707,
+    708,
     5,
     45,
     0,
     0,
-    706,
+    708,
     149,
     1,
     0,
     0,
     0,
-    707,
-    708,
+    709,
+    710,
     5,
     46,
     0,
     0,
-    708,
+    710,
     151,
     1,
     0,
     0,
     0,
-    709,
-    712,
+    711,
+    714,
     3,
     148,
     74,
     0,
-    710,
     712,
+    714,
     5,
     45,
     0,
     0,
+    713,
     711,
-    709,
     1,
     0,
     0,
     0,
-    711,
-    710,
+    713,
+    712,
     1,
     0,
     0,
     0,
-    712,
+    714,
     153,
     1,
     0,
     0,
     0,
-    78,
+    79,
     157,
     162,
     169,
@@ -31129,7 +31169,8 @@ var InsightParser = class _InsightParser extends Parser {
     666,
     686,
     690,
-    711
+    694,
+    713
   ];
   static __ATN;
   static get _ATN() {
@@ -33360,6 +33401,9 @@ var IdentifierReferenceContext = class extends ParserRuleContext {
   identifier() {
     return this.getRuleContext(0, IdentifierContext);
   }
+  ANONYMOUS_ATTRIBUTE() {
+    return this.getToken(InsightParser.ANONYMOUS_ATTRIBUTE, 0);
+  }
   get ruleIndex() {
     return InsightParser.RULE_identifierReference;
   }
@@ -33551,6 +33595,10 @@ var TriviaContext = class extends ParserRuleContext {
 
 // ../packages/insight-language/src/generated/core-source.ts
 var coreSources = [
+  {
+    "sourceName": "core_code.ai",
+    "source": "define type CodeElement of Element\n"
+  },
   {
     "sourceName": "core_component.ai",
     "source": "define type ComponentElement of Element\n\ndefine type Component of ComponentElement\n    constructor component\n\n    required Text name\n    Text technology\n    Text responsibility\n    Text description\n    List of Wire links\n\n\ndefine presentation Component\n    header = name\n    subtitle = technology\n    body = responsibility\n\n    graphviz\n        shape = box\n        style = filled,rounded\n"
@@ -34178,7 +34226,11 @@ function validateRequiredConstructors(snapshot, diagnostics) {
     ));
   }
 }
+var CONSTRUCTORLESS_EXTENSION_POINT_TYPES = /* @__PURE__ */ new Set(["CodeElement"]);
 function requiresConstructor(snapshot, type) {
+  if (CONSTRUCTORLESS_EXTENSION_POINT_TYPES.has(type)) {
+    return false;
+  }
   if (type !== "Environment" && isAssignable(snapshot, type, "Environment")) {
     return false;
   }
@@ -34894,7 +34946,7 @@ function safeId(value) {
 }
 
 // ../packages/insight-language/src/indexed-graph.ts
-var IndexedGraph = class {
+var IndexedGraph = class _IndexedGraph {
   nodesById = /* @__PURE__ */ new Map();
   relationsById = /* @__PURE__ */ new Map();
   outgoingRelationsByNode = /* @__PURE__ */ new Map();
@@ -35078,6 +35130,16 @@ var IndexedGraph = class {
   relations() {
     return [...this.relationsById.values()];
   }
+  clone() {
+    const graph = new _IndexedGraph();
+    for (const node of this.nodes()) {
+      graph.addNode(node);
+    }
+    for (const relation of this.relations()) {
+      graph.addRelation(relation);
+    }
+    return graph;
+  }
   removeNode(nodeId2, removedNodes, removedRelations, dependentSources, removedSource) {
     const node = this.nodesById.get(nodeId2);
     if (node === void 0) {
@@ -35271,6 +35333,12 @@ function normalizeRelation(relation) {
 
 // ../packages/insight-language/src/project-linker.ts
 var ELEMENT_TYPE = "Element";
+var WIRE_TYPE = "Wire";
+var DEPLOYMENT_ELEMENT_TYPE = "DeploymentElement";
+var COMPONENT_ELEMENT_TYPE = "ComponentElement";
+var CONTAINER_ELEMENT_TYPE = "ContainerElement";
+var SYSTEM_TYPE = "System";
+var ACTOR_TYPE = "Actor";
 var ORIGINAL_LINK_OPERATOR = "originalLink";
 var DEPLOYMENT_PROFILE_TYPE = "DeploymentProfile";
 var INFRASTRUCTURE_COMPONENT_TYPE = "InfrastructureComponent";
@@ -35304,6 +35372,8 @@ function linkProject(request) {
   const linkedEdges = [];
   const ownerIndependentProjectionKeys = /* @__PURE__ */ new Set();
   const pendingProjections = [];
+  const wireDeploymentCoverage = [];
+  const deployedElementIds = /* @__PURE__ */ new Set();
   const linkedElementsById = /* @__PURE__ */ new Map();
   for (const element of elements) {
     linkedElementsById.set(element.id, element);
@@ -35336,6 +35406,9 @@ function linkProject(request) {
       continue;
     }
     const application = element.deploymentActions.length === 0 ? { deployments: [], runsOn: [], uses: [] } : resolveDeploymentApplication(element, element.deploymentActions, false, deploymentContext);
+    if (application.runsOn.length > 0 || application.uses.length > 0) {
+      deployedElementIds.add(element.id);
+    }
     const inheritedDeployments = element.parent === void 0 ? [] : deploymentContext.effectiveDeploymentsByElementId.get(element.parent) ?? [];
     const effectiveDeployments = application.deployments.length > 0 ? application.deployments : inheritedDeployments;
     deploymentContext.effectiveDeploymentsByElementId.set(element.id, effectiveDeployments);
@@ -35385,6 +35458,17 @@ function linkProject(request) {
       diagnostics.push(...materialized.diagnostics ?? []);
       if (materialized.edge !== void 0) {
         linkedEdges.push(materialized.edge);
+        const deploymentSource = deploymentViewLogicalEndpoint(edge.source, linkedElementsById, typeSystem);
+        const deploymentTarget = deploymentViewLogicalEndpoint(target.id, linkedElementsById, typeSystem);
+        const coverage = typeSystem.isAssignable(edgeType, WIRE_TYPE) && !typeSystem.isAssignable(edge.sourceType, DEPLOYMENT_ELEMENT_TYPE) && deploymentSource !== void 0 && deploymentTarget !== void 0 && deploymentSource !== deploymentTarget ? {
+          parsed: edge,
+          linked: materialized.edge,
+          deploymentDefined: edge.deploymentActions.length > 0,
+          projected: false
+        } : void 0;
+        if (coverage !== void 0) {
+          wireDeploymentCoverage.push(coverage);
+        }
         pendingProjections.push({
           sourceIdentity: edge.sourceName,
           fromId: edge.source,
@@ -35392,13 +35476,14 @@ function linkProject(request) {
           attributes: effectiveEdgeAttributes,
           projectedAttributes: materialized.edge.attributes,
           projectedOperator: materialized.edge.operator,
-          ...materialized.edge.annotations === void 0 ? {} : { annotations: materialized.edge.annotations }
+          ...materialized.edge.annotations === void 0 ? {} : { annotations: materialized.edge.annotations },
+          ...coverage === void 0 ? {} : { coverage }
         });
       }
     }
   }
   for (const projection of pendingProjections) {
-    addProjectedEdges(linkedEdges, projection.sourceIdentity, projection.fromId, projection.toId, projection.attributes, linkedElementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, void 0, projection.annotations, projection.projectedAttributes, projection.projectedOperator);
+    addProjectedEdges(linkedEdges, projection.sourceIdentity, projection.fromId, projection.toId, projection.attributes, linkedElementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, void 0, projection.annotations, projection.projectedAttributes, projection.projectedOperator, /* @__PURE__ */ new Set(), projection.coverage);
   }
   const slotDomainTypes = typeSystem.slotDomainTypes();
   for (const element of elements) {
@@ -35411,7 +35496,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, resolvedElementAttributes, diagnostics);
+  inspectGraph(graph, graphElements, linkedEdges, resolvedElementAttributes, typeSystem, deployedElementIds, wireDeploymentCoverage, diagnostics);
   const tabRoots = tabRootsBySource(documents, elementsByContextAndLocalId);
   for (const document of documents) {
     resolveAttributes(
@@ -35453,6 +35538,7 @@ function linkProject(request) {
       ...element.parent === void 0 ? {} : { parent: element.parent },
       baseTypes: typeSystem.baseTypes(element.type),
       attributes: flattenAttributes(element.scalarAttributes, resolvedElementAttributes.get(element.id) ?? {}),
+      ...deployedElementIds.has(element.id) ? { deployed: true } : {},
       ...listAttributesProperty(typeSystem, element.type),
       ...referenceAttributesProperty(resolvedElementAttributes.get(element.id) ?? {}),
       ...element.note === void 0 ? {} : { note: element.note },
@@ -37168,7 +37254,7 @@ function mergeUniqueElements(left, right) {
 function sanitizeLocalId(value) {
   return value.replace(/[^A-Za-z0-9_]/g, "_");
 }
-function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = [], projectedAttributes, projectedOperator, visitedProjectionElements = /* @__PURE__ */ new Set()) {
+function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = [], projectedAttributes, projectedOperator, visitedProjectionElements = /* @__PURE__ */ new Set(), coverage) {
   for (const [attributeName, values] of Object.entries(attributes)) {
     if (attributeName === "_") {
       continue;
@@ -37205,7 +37291,7 @@ function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes
         continue;
       }
       for (const rule3 of rules) {
-        addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, value.element, rule3, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2, projectedAttributes, projectedOperator);
+        addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, value.element, rule3, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2, projectedAttributes, projectedOperator, coverage);
       }
       addProjectedEdges(
         linkedEdges,
@@ -37222,7 +37308,8 @@ function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes
         annotations2,
         void 0,
         projectedOperator,
-        visitedProjectionElements
+        visitedProjectionElements,
+        coverage
       );
     }
   }
@@ -37230,7 +37317,7 @@ function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes
 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 = [], projectedAttributes, projectedOperator) {
+function addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, projectionElement, rule3, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = [], projectedAttributes, projectedOperator, coverage) {
   if (!validateConcreteProjectionRule(rule3, typeSystem, diagnostics)) {
     return;
   }
@@ -37246,6 +37333,9 @@ function addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, project
   );
   for (const source of sources) {
     for (const target of targets) {
+      if (coverage !== void 0) {
+        coverage.projected = true;
+      }
       if (!projectionRuleUsesOwner(rule3)) {
         const key = `${projectionElement.id}\0${source}\0${effectiveOperator}\0${target}`;
         if (ownerIndependentProjectionKeys.has(key)) {
@@ -37869,12 +37959,92 @@ function unsupportedOperatorResult(operator, spelling, phase, sourceName, source
     }]
   };
 }
-function inspectGraph(graph, elements, edges, resolvedElementAttributes, diagnostics) {
+function inspectGraph(graph, elements, edges, resolvedElementAttributes, typeSystem, deployedElementIds, wireDeploymentCoverage, diagnostics) {
   if (diagnostics.some((diagnostic) => diagnostic.level === void 0 || diagnostic.level === "ERROR")) {
     return;
   }
   reportIsolatedElements(graph, elements, edges, resolvedElementAttributes, diagnostics);
   reportShadowedLowerLevelEdges(graph, edges, diagnostics);
+  reportIncompleteWireDeployments(wireDeploymentCoverage, diagnostics);
+  reportIncompleteElementDeployments(elements, typeSystem, deployedElementIds, diagnostics);
+}
+function reportIncompleteWireDeployments(coverage, diagnostics) {
+  if (!coverage.some((item) => item.deploymentDefined)) {
+    return;
+  }
+  for (const item of coverage) {
+    if (item.deploymentDefined && item.projected) {
+      continue;
+    }
+    const source = localName(item.linked.source);
+    const target = localName(item.linked.target);
+    const declaration = item.linked.declaration;
+    diagnostics.push({
+      level: "WARNING",
+      code: item.deploymentDefined ? "WIRE_DEPLOYMENT_NOT_PROJECTED" : "WIRE_MISSING_DEPLOYMENT",
+      message: item.deploymentDefined ? `Wire from '${source}' to '${target}' has deployment configuration but produces no physical projection` : `Wire from '${source}' to '${target}' has no deployment configuration and is omitted from deployment views`,
+      sourceName: item.parsed.sourceName,
+      line: declaration?.line ?? item.parsed.line,
+      column: declaration?.column ?? item.parsed.column,
+      ...declaration?.endLine === void 0 ? {} : { endLine: declaration.endLine },
+      ...declaration?.endColumn === void 0 ? {} : { endColumn: declaration.endColumn }
+    });
+  }
+}
+function reportIncompleteElementDeployments(elements, typeSystem, deployedElementIds, diagnostics) {
+  const candidates = elements.flatMap((element) => {
+    const family = elementDeploymentFamily(element, typeSystem);
+    return family === void 0 ? [] : [{ element, family }];
+  });
+  const activeFamilies = new Set(candidates.filter(({ element }) => element.deploymentActions.length > 0).map(({ family }) => family));
+  for (const { element, family } of candidates) {
+    if (!activeFamilies.has(family) || deployedElementIds.has(element.id)) {
+      continue;
+    }
+    diagnostics.push({
+      level: "WARNING",
+      code: element.deploymentActions.length > 0 ? "ELEMENT_DEPLOYMENT_NOT_PHYSICAL" : "ELEMENT_MISSING_DEPLOYMENT",
+      message: element.deploymentActions.length > 0 ? `Element '${element.localId}' has deployment configuration but resolves to no physical infrastructure` : `Element '${element.localId}' has no deployment configuration and is omitted from deployment views`,
+      sourceName: element.sourceName,
+      ...diagnosticPosition2({
+        line: element.idLine,
+        column: element.idColumn,
+        ...element.idEndLine === void 0 ? {} : { endLine: element.idEndLine },
+        ...element.idEndColumn === void 0 ? {} : { endColumn: element.idEndColumn }
+      })
+    });
+  }
+}
+function deploymentViewLogicalEndpoint(elementId, elementsById, typeSystem) {
+  let element = elementsById.get(elementId);
+  while (element !== void 0) {
+    if (typeSystem.isAssignable(element.type, CONTAINER_ELEMENT_TYPE) || element.scalarAttributes.kind === "external") {
+      return element.id;
+    }
+    element = element.parent === void 0 ? void 0 : elementsById.get(element.parent);
+  }
+  return void 0;
+}
+function elementDeploymentFamily(element, typeSystem) {
+  if (typeSystem.isAssignable(element.type, DEPLOYMENT_ELEMENT_TYPE) || typeSystem.isAssignable(element.type, DEPLOYMENT_PROFILE_TYPE)) {
+    return void 0;
+  }
+  if (element.scalarAttributes.kind === "external" && element.deploymentActions.length === 0) {
+    return void 0;
+  }
+  if (typeSystem.isAssignable(element.type, COMPONENT_ELEMENT_TYPE)) {
+    return COMPONENT_ELEMENT_TYPE;
+  }
+  if (typeSystem.isAssignable(element.type, CONTAINER_ELEMENT_TYPE)) {
+    return CONTAINER_ELEMENT_TYPE;
+  }
+  if (typeSystem.isAssignable(element.type, ACTOR_TYPE)) {
+    return ACTOR_TYPE;
+  }
+  if (typeSystem.isAssignable(element.type, SYSTEM_TYPE)) {
+    return SYSTEM_TYPE;
+  }
+  return typeSystem.isAssignable(element.type, ELEMENT_TYPE) ? element.type : void 0;
 }
 function reportIsolatedElements(graph, elements, edges, resolvedElementAttributes, diagnostics) {
   const referenced = /* @__PURE__ */ new Set();
@@ -37982,6 +38152,14 @@ function localName(id) {
   return id.includes("/") ? id.slice(id.lastIndexOf("/") + 1) : id;
 }
 function resolveEdgeTarget(edge, currentContext, sourceElementsBySourceAndLocalId, elementsByContextAndLocalId, importsBySourceAndAlias, diagnostics) {
+  if (edge.targetId === "_") {
+    diagnostics.push(missingElement(
+      edge,
+      "Anonymous instance '_' cannot be referenced; give the target a named id",
+      "ANONYMOUS_INSTANCE_NOT_REFERENCEABLE"
+    ));
+    return void 0;
+  }
   if (edge.targetContext !== void 0) {
     const explicit = elementsByContextAndLocalId.get(`${edge.targetContext}\0${edge.targetId}`)?.[0];
     if (explicit !== void 0) {
@@ -38472,7 +38650,7 @@ function rollupMatchRows(context, inputRows, pattern, where) {
       if (sourceEndpoint === void 0) {
         continue;
       }
-      for (const targetEndpoint of rollupTargetCandidates(edge, boundRight, parentByChild)) {
+      for (const targetEndpoint of rollupTargetCandidates(context, edge, boundRight, parentByChild)) {
         const source = queryNodeById(context.result, sourceEndpoint.id);
         const target = queryNodeById(context.result, targetEndpoint.id);
         if (source === void 0 || target === void 0) {
@@ -38482,7 +38660,7 @@ function rollupMatchRows(context, inputRows, pattern, where) {
           nodes: {
             ...row.nodes,
             [pattern.left.alias]: sourceEndpoint.binding,
-            [right.alias]: target
+            [right.alias]: targetEndpoint.binding
           },
           relationships: relationship.alias === void 0 ? row.relationships : {
             ...row.relationships,
@@ -38493,7 +38671,7 @@ function rollupMatchRows(context, inputRows, pattern, where) {
             }
           }
         };
-        if (matchesNode(sourceEndpoint.binding, pattern.left, context) && matchesNode(target, right, context) && evaluateExpression(nextRow, where, context)) {
+        if (matchesNode(sourceEndpoint.binding, pattern.left, context) && matchesNode(targetEndpoint.binding, right, context) && evaluateExpression(nextRow, where, context)) {
           rows.push(nextRow);
           break;
         }
@@ -38514,11 +38692,20 @@ function rollupSourceEndpoint(context, edge, pattern, bound, parentByChild) {
   }
   return nearestEndpoint(context, edge.source, pattern, void 0, parentByChild);
 }
-function rollupTargetCandidates(edge, bound, parentByChild) {
+function rollupTargetCandidates(context, edge, bound, parentByChild) {
   if (bound !== void 0) {
-    return lineage(edge.target, parentByChild).includes(bound.id) || edgeOriginTargetLineage(edge, parentByChild).includes(bound.id) ? [{ id: bound.id }] : [];
+    if (lineage(edge.target, parentByChild).includes(bound.id)) {
+      return [{ id: bound.id, binding: bound }];
+    }
+    if (edgeOriginTargetLineage(edge, parentByChild).includes(bound.id)) {
+      return queryNodeById(context.result, edge.target) === void 0 ? [] : [{ id: edge.target, binding: bound }];
+    }
+    return [];
   }
-  return lineage(edge.target, parentByChild).map((id) => ({ id }));
+  return lineage(edge.target, parentByChild).flatMap((id) => {
+    const binding = queryNodeById(context.result, id);
+    return binding === void 0 ? [] : [{ id, binding }];
+  });
 }
 function nearestEndpoint(context, start, pattern, where, parentByChild, binding = void 0) {
   for (const id of lineage(start, parentByChild)) {
@@ -38968,6 +39155,9 @@ function propertyValue(node, name) {
     return void 0;
   }
   const element = node.element;
+  if (name === "deployed") {
+    return String(element.deployed === true);
+  }
   if (name === "id") {
     return element.localId;
   }
@@ -39528,15 +39718,49 @@ var BUILTIN_VIEW_QUERIES = {
   "c1": "MATCH (system:SystemElement)\nWHERE system.context = $context\nOPTIONAL MATCH (system)-[realOutboundLink]->(externalSystem:SystemElement)\nOPTIONAL MATCH (sourceSystem:SystemElement)-[realInboundLink]->(system)\nOPTIONAL MATCH (system)-[rollupOutboundLink {derived}]->(rollupSystem:SystemElement)\nOPTIONAL MATCH (rollupSourceSystem:SystemElement)-[rollupInboundLink {derived}]->(system)\nGROUP BY system.parent\nRETURN system, realOutboundLink, externalSystem, realInboundLink, sourceSystem, rollupOutboundLink, rollupSystem, rollupInboundLink, rollupSourceSystem",
   "c2": "MATCH (container:ContainerElement)\nWHERE container.sourceIdentity = $tab\nOPTIONAL MATCH (container)-[internalLink]->(targetContainer:ContainerElement)\nOPTIONAL MATCH (container)-[rollupOutboundLink {derived}]->(rollupContainer:ContainerElement)\nOPTIONAL MATCH (container)-[outboundLink]->(externalSystem:SystemElement)\nWHERE externalSystem IS External\nOPTIONAL MATCH (sourceSystem:SystemElement)-[inboundLink]->(container)\nWHERE sourceSystem IS External\nOPTIONAL MATCH (container)-[rollupExternalOutboundLink {derived}]->(rollupExternalSystem:SystemElement)\nWHERE rollupExternalSystem IS External\nOPTIONAL MATCH (rollupExternalSourceSystem:SystemElement)-[rollupExternalInboundLink {derived}]->(container)\nWHERE rollupExternalSourceSystem IS External\nGROUP BY container.parent\nRETURN container, internalLink, targetContainer, rollupOutboundLink, rollupContainer, outboundLink, externalSystem, inboundLink, sourceSystem, rollupExternalOutboundLink, rollupExternalSystem, rollupExternalInboundLink, rollupExternalSourceSystem",
   "c3": "MATCH (container:ContainerElement)-[contains:CONTAINS]->(component:ComponentElement)\nWHERE container.sourceIdentity = $tab\nOPTIONAL MATCH (component)-[link]->(targetComponent:ComponentElement)\nOPTIONAL MATCH (component)-[externalLink]->(externalSystem:SystemElement)\nWHERE externalSystem IS External\nOPTIONAL MATCH (externalSourceSystem:SystemElement)-[externalInboundLink]->(component)\nWHERE externalSourceSystem IS External\nOPTIONAL MATCH (component)-[rollupExternalLink {derived}]->(rollupExternalSystem:SystemElement)\nWHERE rollupExternalSystem IS External\nOPTIONAL MATCH (rollupExternalSourceSystem:SystemElement)-[rollupExternalInboundLink {derived}]->(component)\nWHERE rollupExternalSourceSystem IS External\nGROUP BY component.parent\nRETURN component, link, targetComponent, externalLink, externalSystem, externalInboundLink, externalSourceSystem, rollupExternalLink, rollupExternalSystem, rollupExternalInboundLink, rollupExternalSourceSystem",
-  "c4": "MATCH (node:Element)\nWHERE node.sourceIdentity = $tab\n  AND (node IS DeploymentElement OR node IS ContainerElement OR node IS External)\nOPTIONAL MATCH (deploymentTarget:InfrastructureComponent)\nWHERE deploymentTarget IN node.uses OR deploymentTarget = node.runsOn\nOPTIONAL MATCH ROLLUP (node)-[projectedLink {projected}]->(projectedTarget:Element)\nWHERE projectedTarget IS DeploymentElement\n   OR projectedTarget IS ContainerElement\n   OR projectedTarget IS External\nOPTIONAL MATCH (node)-[directDeploymentLink]->(directDeploymentTarget:Element)\nWHERE node IS DeploymentElement\n  AND (directDeploymentTarget IS DeploymentElement OR directDeploymentTarget IS External)\nOPTIONAL MATCH (node)-[logicalPeerLink]->(logicalPeerTarget:ContainerElement)\nWHERE logicalPeerTarget.sourceIdentity <> $tab\nOPTIONAL MATCH (incomingProjectedSource:Element)-[incomingProjectedLink {projected}]->(node)\nWHERE (incomingProjectedSource IS DeploymentElement\n   OR incomingProjectedSource IS ContainerElement\n   OR incomingProjectedSource IS External)\n  AND incomingProjectedSource.id <> node.id\nOPTIONAL MATCH ROLLUP (incomingProjectedOrigin:Element)-[incomingProjectedOriginLink {projected}]->(incomingProjectedSource)\nWHERE (incomingProjectedOrigin IS DeploymentElement\n   OR incomingProjectedOrigin IS ContainerElement\n   OR incomingProjectedOrigin IS External)\n  AND incomingProjectedOrigin.id <> incomingProjectedSource.id\nOPTIONAL MATCH (projectedPathSource:DeploymentElement)-[projectedPathLink {projected}]->(projectedPathTarget:DeploymentElement)\nGROUP BY node.runsOn\nRETURN node, deploymentTarget, projectedLink, projectedTarget, directDeploymentLink, directDeploymentTarget, logicalPeerLink, logicalPeerTarget, incomingProjectedLink, incomingProjectedSource, incomingProjectedOriginLink, incomingProjectedOrigin, projectedPathSource, projectedPathLink, projectedPathTarget"
+  "c4": "MATCH (code:CodeElement)\nWHERE code.sourceIdentity = $tab\nOPTIONAL MATCH (code)-[link]->(targetCode:CodeElement)\nGROUP BY code.parent\nRETURN code, link, targetCode",
+  "deployment": "MATCH (node:Element)\nWHERE node.sourceIdentity = $tab\n  AND (node IS DeploymentElement\n    OR ((node IS ContainerElement OR node IS External) AND node.deployed = true))\nOPTIONAL MATCH (deploymentTarget:InfrastructureComponent)\nWHERE deploymentTarget IN node.uses OR deploymentTarget = node.runsOn\nOPTIONAL MATCH ROLLUP (node)-[projectedLink {projected}]->(projectedTarget:Element)\nWHERE projectedTarget IS DeploymentElement\n   OR (projectedTarget IS ContainerElement AND projectedTarget.deployed = true)\n   OR projectedTarget IS External\nOPTIONAL MATCH (node)-[directDeploymentLink]->(directDeploymentTarget:Element)\nWHERE node IS DeploymentElement\n  AND (directDeploymentTarget IS DeploymentElement OR directDeploymentTarget IS External)\nOPTIONAL MATCH ROLLUP (incomingProjectedSource:Element)-[incomingProjectedLink {projected}]->(node)\nWHERE (incomingProjectedSource IS DeploymentElement\n   OR (incomingProjectedSource IS ContainerElement AND incomingProjectedSource.deployed = true)\n   OR incomingProjectedSource IS External)\n  AND incomingProjectedSource.id <> node.id\nOPTIONAL MATCH (projectedPathSource:DeploymentElement)-[projectedPathLink {projected}]->(projectedPathTarget:DeploymentElement)\nGROUP BY node.runsOn\nRETURN node, deploymentTarget, projectedLink, projectedTarget, directDeploymentLink, directDeploymentTarget, incomingProjectedLink, incomingProjectedSource, projectedPathSource, projectedPathLink, projectedPathTarget"
 };
 
 // src/version.ts
-var version = "3.0.0";
+var version = "3.0.1";
 
 // src/index.ts
 var hiddenStructureTypes = /* @__PURE__ */ new Set(["List", "Nothing", "Text", "text"]);
 var viewQueries = BUILTIN_VIEW_QUERIES;
+function textFileContent(content) {
+  return content.endsWith("\n") ? content : `${content}
+`;
+}
+function replaceExactlyOnce(source, expected, replacement, description) {
+  const parts = source.split(expected);
+  if (parts.length !== 2) {
+    throw new Error(`Cannot generate ${description}: expected one matching built-in Deployment fragment, found ${parts.length - 1}`);
+  }
+  return `${parts[0]}${replacement}${parts[1]}`;
+}
+function deploymentInternalActorsQuery() {
+  let query = viewQueries.deployment;
+  query = replaceExactlyOnce(
+    query,
+    "    OR ((node IS ContainerElement OR node IS External) AND node.deployed = true))",
+    "    OR ((node IS ContainerElement OR node IS External) AND node.deployed = true)\n    OR node IS Actor)",
+    "Deployment internal-actor query"
+  );
+  query = replaceExactlyOnce(
+    query,
+    "   OR projectedTarget IS External",
+    "   OR projectedTarget IS External\n   OR projectedTarget IS Actor",
+    "Deployment internal-actor projected target filter"
+  );
+  query = replaceExactlyOnce(
+    query,
+    "   OR incomingProjectedSource IS External)",
+    "   OR incomingProjectedSource IS External\n   OR incomingProjectedSource IS Actor)",
+    "Deployment internal-actor incoming source filter"
+  );
+  return query;
+}
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.version) {
@@ -39667,12 +39891,54 @@ 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)) {
+  const outputExists = await exists(outputRoot);
+  if (outputExists && !args.force) {
+    throw new CliError(
+      `Refusing to initialize skill because output directory '${outputRoot}' already exists. Pass --force to replace the complete generated skill package.`
+    );
+  }
+  if (args.force) {
     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);
+  const outputParent = path.dirname(outputRoot);
+  await mkdir(outputParent, { recursive: true });
+  const stagingRoot = await mkdtemp(path.join(outputParent, `.${path.basename(outputRoot)}.tmp-`));
+  let previousRoot;
+  let installed = false;
+  try {
+    for (const file of skillPackage.files) {
+      await writeGeneratedFile(path.join(stagingRoot, file.path), file.content);
+    }
+    if (!args.force && await exists(outputRoot)) {
+      throw new CliError(
+        `Refusing to initialize skill because output directory '${outputRoot}' was created concurrently. No generated files were installed.`
+      );
+    }
+    if (args.force && await exists(outputRoot)) {
+      previousRoot = `${stagingRoot}.previous`;
+      await rename(outputRoot, previousRoot);
+    }
+    try {
+      await rename(stagingRoot, outputRoot);
+      installed = true;
+    } catch (error) {
+      if (previousRoot !== void 0 && !await exists(outputRoot)) {
+        await rename(previousRoot, outputRoot);
+        previousRoot = void 0;
+      }
+      throw error;
+    }
+    if (previousRoot !== void 0) {
+      await rm(previousRoot, { recursive: true, force: true });
+      previousRoot = void 0;
+    }
+  } finally {
+    if (!installed) {
+      await rm(stagingRoot, { recursive: true, force: true });
+    }
+    if (installed && previousRoot !== void 0 && await exists(previousRoot)) {
+      await rm(previousRoot, { recursive: true, force: true });
+    }
   }
   process.stdout.write(skillPackageSuccess(projectRoot, outputRoot, skillPackage, usesDefaultOutput));
 }
@@ -39959,9 +40225,9 @@ async function writeOutput(file, content) {
   await mkdir(path.dirname(path.resolve(file)), { recursive: true });
   await writeFile(file, content);
 }
-async function writeGeneratedFile(file, content, force) {
-  if (!force && await exists(file)) {
-    throw new CliError(`Refusing to overwrite '${file}'. Pass --force to replace generated agent files.`);
+async function writeGeneratedFile(file, content) {
+  if (await exists(file)) {
+    throw new CliError(`Generated skill package contains duplicate file path '${file}'.`);
   }
   await mkdir(path.dirname(file), { recursive: true });
   await writeFile(file, content);
@@ -40083,7 +40349,7 @@ function viewOption(value) {
   if (value === void 0) {
     return void 0;
   }
-  if (value === "c1" || value === "c2" || value === "c3" || value === "c4" || value === "no-filter") {
+  if (value === "c1" || value === "c2" || value === "c3" || value === "c4" || value === "deployment" || value === "no-filter") {
     return value;
   }
   throw new CliError(`Unknown view '${String(value)}'`);
@@ -40121,8 +40387,8 @@ function helpText() {
 
 Usage:
   archinsight link [project-dir] [--format text|json] [--out file]
-  archinsight render [project-dir] -c <context> [-s <source>] [-v c1|c2|c3|c4|no-filter] [-q query.aiq] [-f dot|svg|json] [-o file]
-  archinsight query [project-dir] -c <context> [-s <source>] [-v c1|c2|c3|c4|no-filter] [-q query.aiq] [-f text|json] [-o file]
+  archinsight render [project-dir] -c <context> [-s <source>] [-v c1|c2|c3|c4|deployment|no-filter] [-q query.aiq] [-f dot|svg|json] [-o file]
+  archinsight query [project-dir] -c <context> [-s <source>] [-v c1|c2|c3|c4|deployment|no-filter] [-q query.aiq] [-f text|json] [-o file]
   archinsight structure [project-dir] [--format text|json] [--out file]
   archinsight skill init [project-dir] [--target generic|codex|claude] [--out dir] [--force]
 
@@ -40131,13 +40397,13 @@ Options:
   -c, --context <id>       Context id for query/render.
   -s, --source <file>      Selected project file for queries using $tab.
       --tab <source>       Backward-compatible alias for --source.
-  -v, --view <name>        Built-in view: c1, c2, c3, c4, no-filter.
+  -v, --view <name>        Built-in view: c1, c2, c3, c4, deployment, no-filter.
   -q, --query <file>       Query file; overrides --view.
   -f, --format <format>    Output format.
   -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              Delete and recreate the generated skill directory.
+      --force              Replace the complete generated skill directory.
   -V, --version            Print version.
   -h, --help               Show help.
 
@@ -40196,10 +40462,18 @@ function claudeSkillPackage() {
 }
 function sharedSkillFiles() {
   return [
+    {
+      path: "references/cli.md",
+      content: genericCliReference()
+    },
     {
       path: "references/modeling.md",
       content: genericModelingReference()
     },
+    {
+      path: "references/importing-models.md",
+      content: genericImportingModelsReference()
+    },
     {
       path: "references/syntax.md",
       content: genericSyntaxReference()
@@ -40221,8 +40495,12 @@ function sharedSkillFiles() {
       content: genericC3ComponentsReference()
     },
     {
-      path: "references/c4-deployment.md",
-      content: genericC4DeploymentReference()
+      path: "references/c4-code.md",
+      content: genericC4CodeReference()
+    },
+    {
+      path: "references/deployment.md",
+      content: genericDeploymentReference()
     },
     {
       path: "references/scaling.md",
@@ -40240,6 +40518,10 @@ function sharedSkillFiles() {
       path: "references/validation.md",
       content: genericValidationReference()
     },
+    {
+      path: "references/analysis.md",
+      content: genericAnalysisReference()
+    },
     {
       path: "references/queries.md",
       content: genericQueriesReference()
@@ -40264,42 +40546,51 @@ function sharedSkillFiles() {
       path: "examples/c3-components.ai",
       content: genericC3ComponentsExample()
     },
+    ...genericC4CodeExampleFiles(),
     {
-      path: "examples/c4-deployment-framework.ai",
-      content: genericC4DeploymentFrameworkExample()
+      path: "examples/deployment-framework.ai",
+      content: genericDeploymentFrameworkExample()
     },
     {
-      path: "examples/c4-deployment-infrastructure.ai",
-      content: genericC4DeploymentInfrastructureExample()
+      path: "examples/deployment-infrastructure.ai",
+      content: genericDeploymentInfrastructureExample()
     },
     {
-      path: "examples/c4-deployment.ai",
-      content: genericC4DeploymentExample()
+      path: "examples/deployment.ai",
+      content: genericDeploymentExample()
     },
-    ...genericC4PrivateGatewayExampleFiles(),
+    ...genericDeploymentPrivateGatewayExampleFiles(),
     {
       path: "examples/c2-containers.aiq",
       content: genericC2QueryExample()
     },
     {
       path: "examples/builtin-views/no-filter.aiq",
-      content: viewQueries["no-filter"]
+      content: textFileContent(viewQueries["no-filter"])
     },
     {
       path: "examples/builtin-views/c1.aiq",
-      content: viewQueries.c1
+      content: textFileContent(viewQueries.c1)
     },
     {
       path: "examples/builtin-views/c2.aiq",
-      content: viewQueries.c2
+      content: textFileContent(viewQueries.c2)
     },
     {
       path: "examples/builtin-views/c3.aiq",
-      content: viewQueries.c3
+      content: textFileContent(viewQueries.c3)
     },
     {
       path: "examples/builtin-views/c4.aiq",
-      content: viewQueries.c4
+      content: textFileContent(viewQueries.c4)
+    },
+    {
+      path: "examples/builtin-views/deployment.aiq",
+      content: textFileContent(viewQueries.deployment)
+    },
+    {
+      path: "examples/queries/deployment-internal-actors.aiq",
+      content: textFileContent(deploymentInternalActorsQuery())
     },
     ...coreSkillFiles()
   ];
@@ -40337,42 +40628,98 @@ function skillPackageSuccess(projectRoot, outputRoot, skillPackage, usesDefaultO
   lines.push("");
   return lines.join("\n");
 }
+function skillCompatibilityNotice() {
+  return `This package was generated by Archinsight CLI ${version}. Run
+\`archinsight --version\` before editing. If the installed version differs,
+regenerate the skill so its references, core sources, examples, and built-in
+queries match the runtime.`;
+}
+function skillReferenceRoutingGuide() {
+  return `## Reference routing
+
+- Read \`references/cli.md\` when the CLI is missing, its version differs from
+  the generated skill, or the skill package must be regenerated.
+- Read \`references/modeling.md\` before creating or extending a
+  model.
+- Read \`references/importing-models.md\` when translating an existing
+  architecture description, diagram, inventory, or foreign DSL into Insight.
+- Read \`references/syntax.md\` before writing unfamiliar Insight syntax.
+- Read \`references/layered-architecture.md\` when decomposing a system across
+  C1, C2, C3, C4, and Deployment views.
+- Read \`references/c1-context.md\` when working with system context models.
+- Read \`references/c2-containers.md\` when working with containers or services.
+- Read \`references/c3-components.md\` when working with component internals.
+- Infer and reuse an existing C4 Code vocabulary from the repository. Ask the
+  user about entity kinds only when creating the Code layer or extending that
+  vocabulary, unless the current request already makes the choice.
+- Read \`references/c4-code.md\` when defining or querying modules, packages,
+  classes, functions, schemas, or other project-specific code concepts.
+- Read \`references/deployment.md\` when working with environments,
+  deployments, infrastructure, placement, or projections.
+- Read \`references/scaling.md\` when splitting a repository into reusable
+  framework, environment, profile, system, or view files.
+- Read \`references/project-structure.md\` before declaration lookup, imports,
+  or broad file changes.
+- Read \`references/core.md\` and \`.core/*.ai\` before assuming built-in types,
+  constructors, attributes, presentations, or projections.
+- Read \`references/queries.md\` before writing queries or interpreting query
+  JSON.
+- Read \`references/query-recipes.md\` when a view hides expected content,
+  returns unexpected content, or needs customization.
+- Read \`references/validation.md\` before validating semantic or rendered
+  results.
+- Read \`references/analysis.md\` for read-only architecture analysis,
+  dependency questions, impact exploration, and the boundary between Insight
+  queries and analysis of their JSON output.
+- Use \`examples/layered-architecture.ai\` as a compact valid model.`;
+}
 function skillTaskModesGuide() {
   return `## Task modes
 
 Choose one mode before acting:
 
-- **Analyze:** stay read-only. Inspect sources, run \`structure\`, \`link\`, and
-  the relevant query/render, then separate model, linker, query, and layout
-  findings with evidence.
-- **Repair:** reproduce the defect first. For a visual defect, request the
-  current image or rendered output when it is not available. Make the smallest
-  model or query change and validate the same path again.
+- **Analyze:** stay read-only and follow \`references/analysis.md\`. Inspect
+  sources, run \`structure\`, \`link\`, and the relevant query, then separate
+  authored facts, derived relationships, deployment projections, and rendered
+  presentation in the findings.
+- **Repair:** reproduce the defect first. For a visual defect, inspect
+  \`archinsight query ... --format json\` before treating the image as evidence
+  that the model is wrong. Request the current image or rendered output when it
+  is not available, make the smallest model or query change, and validate the
+  same semantic path again before rendering.
 - **Build or rebuild:** perform discovery before editing, then model from the
   outside inward and validate after each architectural layer.
-- **Extend or migrate:** inventory existing ids, imports, edges, and view scope;
-  preserve stable identities and compare the linked/rendered result before and
+- **Extend an existing model:** inventory existing ids, imports, edges, and view
+  scope; preserve stable identities and compare linked/query results before and
   after each focused change.
-
-Before any build, rebuild, or migration edit, inspect the supplied context and
-ask one short, non-repetitive discovery message. Ask only for missing facts that
-could materially change the model: existing descriptions, diagrams or documents,
-unclear boundaries and flows, and relevant deployment constraints. Do not use a
-questionnaire or ask about the audience by default. If the request already
-answers everything, only invite the user to share any existing artifacts before
-proceeding. Use supplied material as the source of truth; do not invent missing
+- **Import an existing model:** follow \`references/importing-models.md\`.
+  Establish which source artifacts are authoritative, translate facts rather
+  than drawing layout, record uncertain mappings, and validate one
+  architectural layer at a time.
+
+Before any build, rebuild, import, or structural edit, inspect the supplied
+context and every relevant source already available through the repository,
+attachments, configured skills, MCP integrations, or other authorized tools.
+Do not ask the user to repeat information the agent can retrieve reliably on its
+own. If a material fact is still missing after those sources are exhausted, ask
+one short, non-repetitive message containing only the one or two questions that
+could change the model. Do not use a questionnaire or ask about the audience by
+default. If the available evidence is sufficient, proceed without a discovery
+question. Use retrieved material as the source of truth; do not invent missing
 architecture.
 `;
 }
 function genericSkillGuide() {
   return `# Archinsight Agent Guide
 
-Use this guide when creating, analyzing, repairing, or migrating Insight \`.ai\`
-architecture models.
+Use this guide when creating, analyzing, or repairing Insight \`.ai\` models, or
+when importing an existing architecture description into Insight.
 
 Insight is its own typed architecture-as-code language. Do not infer its syntax
 from YAML, Mermaid, PlantUML, Structurizr, or C4 DSL.
 
+${skillCompatibilityNotice()}
+
 ## Required Tool
 
 Use the Archinsight CLI as the validation source of truth:
@@ -40382,8 +40729,8 @@ archinsight --help
 archinsight link . --format text
 \`\`\`
 
-If \`archinsight\` is not available, ask the user to install or expose
-\`@archinsight/cli\` before changing \`.ai\` files.
+If \`archinsight\` is not available, read \`references/cli.md\`. Do not install
+or update packages without the user's authorization.
 
 ${skillTaskModesGuide()}
 
@@ -40392,99 +40739,46 @@ ${skillTaskModesGuide()}
 1. Read the existing \`.ai\` files before editing.
 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.
+   systems, containers/services, components, project-defined code when needed,
+   and deployment details.
 4. Do not ask about deployment depth until the task touches infrastructure,
    runtime placement, regions, brokers, gateways, storage, or deployment.
-5. At that point, decide per system whether pragmatic mixed C2 or clean
-   C4/deployment is appropriate. If modeling clean C4: attach placement/storage
-   to elements, attach path infrastructure that needs \`$to\` to wires, and make
-   pub/sub dependencies consumer-owned.
+5. At that point, decide per system whether pragmatic mixed C2 or explicit
+   deployment modeling is appropriate. For explicit deployment, attach
+   placement/storage to elements, attach path infrastructure that needs \`$to\`
+   to wires, and make pub/sub dependencies consumer-owned.
 6. If a diagram becomes noisy, adjust scope/query before changing a correct
    graph model.
 7. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
 8. Keep definition, context, and environment sources in separate files.
 9. Validate every Insight change with \`archinsight link . --format text\`.
+10. For C2, C3, C4, Deployment, or query changes, inspect the selected graph with
+    \`archinsight query ... --format json\` before rendering.
 
-## References
-
-- Read \`references/modeling.md\` before creating, migrating, or extending a
-  model.
-- 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.
+${skillReferenceRoutingGuide()}
 `;
 }
 function codexSkillGuide() {
   return `---
 name: archinsight
-description: Create, edit, migrate, analyze, repair, validate, inspect, and render Archinsight Insight architecture-as-code models. Use when working with .ai Insight files, C4-style architecture models, system/container/component diagrams, deployment projections, or when the user asks to model or diagnose software architecture with Archinsight.
+description: Create, edit, import, analyze, repair, validate, inspect, and render Archinsight Insight architecture-as-code models. Use when working with .ai Insight files, migrating architecture from another DSL or diagram, C4-style architecture models, system/container/component/code diagrams, deployment projections, or when the user asks to model or diagnose software architecture with Archinsight.
 ---
 
 # Archinsight
 
-Use this skill when creating, analyzing, repairing, or migrating Insight \`.ai\`
-architecture models.
+Use this skill when creating, analyzing, or repairing Insight \`.ai\` models, or
+when importing an existing architecture description into Insight.
 
 Insight is its own typed architecture-as-code language. Do not infer its syntax
 from YAML, Mermaid, PlantUML, Structurizr, or C4 DSL.
 
 ## Codex Usage Notes
 
-Treat this \`SKILL.md\` as the entrypoint. Load reference files only when needed:
+Treat this \`SKILL.md\` as the entrypoint and load routed reference files only
+when the task needs them. Use shell access to run validation. Do not silently
+install global npm packages or change machine configuration.
 
-- Read \`references/modeling.md\` before creating, migrating, or extending a
-  model.
-- 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.
-
-Use Codex shell access to validate changes when available. Do not silently
-install global npm packages or change machine configuration. If \`archinsight\`
-is missing, ask the user whether they want to install or expose
-\`@archinsight/cli\`.
+${skillCompatibilityNotice()}
 
 ## Required Tool
 
@@ -40495,8 +40789,8 @@ archinsight --help
 archinsight link . --format text
 \`\`\`
 
-If \`archinsight\` is not available, ask the user to install or expose
-\`@archinsight/cli\` before changing \`.ai\` files.
+If \`archinsight\` is not available, read \`references/cli.md\`. Do not install
+or update packages without the user's authorization.
 
 ${skillTaskModesGuide()}
 
@@ -40505,13 +40799,14 @@ ${skillTaskModesGuide()}
 1. Read the existing \`.ai\` files before editing.
 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.
+   systems, containers/services, components, project-defined code when needed,
+   and deployment details.
 4. Do not ask about deployment depth until the task touches infrastructure,
    runtime placement, regions, brokers, gateways, storage, or deployment.
-5. At that point, decide per system whether pragmatic mixed C2 or clean
-   C4/deployment is appropriate. If modeling clean C4: attach placement/storage
-   to elements, attach path infrastructure that needs \`$to\` to wires, and make
-   pub/sub dependencies consumer-owned.
+5. At that point, decide per system whether pragmatic mixed C2 or explicit
+   deployment modeling is appropriate. For explicit deployment, attach
+   placement/storage to elements, attach path infrastructure that needs \`$to\`
+   to wires, and make pub/sub dependencies consumer-owned.
 6. If a diagram becomes noisy, adjust scope/query before changing a correct
    graph model.
 7. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
@@ -40519,90 +40814,36 @@ ${skillTaskModesGuide()}
 9. Use \`archinsight structure . --format text\` before broad edits when the
    project shape is unclear.
 10. Validate every Insight change with \`archinsight link . --format text\`.
-11. If validation fails, fix the first real syntax/type/linking error before
-   adding more model content.
+11. For C2, C3, C4, Deployment, or query changes, inspect the selected graph with
+    \`archinsight query ... --format json\` before rendering.
+12. If validation fails, fix the first real syntax/type/linking error before
+    adding more model content.
 
-## References
-
-- Read \`references/modeling.md\` before creating, migrating, or extending a
-  model.
-- 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.
+${skillReferenceRoutingGuide()}
 `;
 }
 function claudeSkillGuide() {
   return `---
 name: archinsight
-description: Create, edit, migrate, analyze, repair, validate, inspect, and render Archinsight Insight architecture-as-code models. Use when working with .ai Insight files, C4-style architecture models, system/container/component diagrams, deployment projections, or when the user asks to model or diagnose software architecture with Archinsight.
+description: Create, edit, import, analyze, repair, validate, inspect, and render Archinsight Insight architecture-as-code models. Use when working with .ai Insight files, migrating architecture from another DSL or diagram, C4-style architecture models, system/container/component/code diagrams, deployment projections, or when the user asks to model or diagnose software architecture with Archinsight.
 ---
 
 # Archinsight
 
-Use this skill when creating, analyzing, repairing, or migrating Insight \`.ai\`
-architecture models.
+Use this skill when creating, analyzing, or repairing Insight \`.ai\` models, or
+when importing an existing architecture description into Insight.
 
 Insight is its own typed architecture-as-code language. Do not infer its syntax
 from YAML, Mermaid, PlantUML, Structurizr, or C4 DSL.
 
 ## Claude Usage Notes
 
-Treat this \`SKILL.md\` as the entrypoint. Load the reference files only when
-they are needed:
+Treat this \`SKILL.md\` as the entrypoint and load routed references only when
+the task needs them. With shell access, run validation directly. Without it, ask
+the user to run the exact command and paste the output. Do not silently install
+npm packages or change machine configuration.
 
-- Read \`references/modeling.md\` before creating, migrating, or extending a
-  model.
-- 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.
-
-When Claude has direct shell access, run validation yourself. When Claude is
-embedded in an editor without shell access, ask the user to run the exact command
-and paste the output. Do not silently install npm packages or change machine
-configuration.
+${skillCompatibilityNotice()}
 
 ## Required Tool
 
@@ -40613,8 +40854,9 @@ archinsight --help
 archinsight link . --format text
 \`\`\`
 
-If \`archinsight\` is not available in Claude's environment, ask the user to
-install or expose \`@archinsight/cli\` before changing \`.ai\` files.
+If \`archinsight\` is not available in Claude's environment, read
+\`references/cli.md\`. Do not install or update packages without the user's
+authorization.
 
 ${skillTaskModesGuide()}
 
@@ -40623,13 +40865,14 @@ ${skillTaskModesGuide()}
 1. Read the existing \`.ai\` files before editing.
 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.
+   systems, containers/services, components, project-defined code when needed,
+   and deployment details.
 4. Do not ask about deployment depth until the task touches infrastructure,
    runtime placement, regions, brokers, gateways, storage, or deployment.
-5. At that point, decide per system whether pragmatic mixed C2 or clean
-   C4/deployment is appropriate. If modeling clean C4: attach placement/storage
-   to elements, attach path infrastructure that needs \`$to\` to wires, and make
-   pub/sub dependencies consumer-owned.
+5. At that point, decide per system whether pragmatic mixed C2 or explicit
+   deployment modeling is appropriate. For explicit deployment, attach
+   placement/storage to elements, attach path infrastructure that needs \`$to\`
+   to wires, and make pub/sub dependencies consumer-owned.
 6. If a diagram becomes noisy, adjust scope/query before changing a correct
    graph model.
 7. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
@@ -40638,7 +40881,9 @@ ${skillTaskModesGuide()}
    before broad edits when the CLI is available.
 10. Validate every Insight change with \`archinsight link . --format text\` when
    shell access is available; otherwise ask the user to run validation.
-11. If validation fails, fix the first real syntax/type/linking error before
+11. For C2, C3, C4, Deployment, or query changes, inspect the selected graph with
+   \`archinsight query ... --format json\` before rendering.
+12. If validation fails, fix the first real syntax/type/linking error before
    adding more model content.
 
 ## Communication
@@ -40660,35 +40905,7 @@ archinsight render . -c <context-id> -s <source.ai> -v c2 -f svg -o diagram.svg
 Report diagnostics by source, line, column, and message. Avoid rewriting large
 sections of Insight unless the existing layering is already understood.
 
-## References
-
-- Read \`references/modeling.md\` before creating, migrating, or extending a
-  model.
-- 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.
+${skillReferenceRoutingGuide()}
 `;
 }
 function codexOpenAiYaml() {
@@ -40701,6 +40918,85 @@ policy:
   allow_implicit_invocation: true
 `;
 }
+function genericCliReference() {
+  return `# CLI Installation, Updates, and Skill Regeneration
+
+The generated skill uses the Archinsight CLI as its parser, linker, query
+runtime, and validation authority. Check the available command before editing:
+
+\`\`\`shell
+archinsight --version
+archinsight --help
+\`\`\`
+
+Do not silently install or update the CLI. Package installation changes the
+developer environment or the project's dependency manifest and lockfile. Use an
+existing installation when possible; otherwise ask the user to authorize the
+appropriate installation method.
+
+## Project-Local Installation
+
+Prefer a project-local dependency when the repository already manages Node.js
+developer tools this way. Respect its package manager and lockfile. For an npm
+project, the user can install or update the current release with:
+
+\`\`\`shell
+npm install --save-dev @archinsight/cli@latest
+npm exec -- archinsight --version
+\`\`\`
+
+Use the equivalent command for pnpm or Yarn when that package manager owns the
+repository. Do not introduce a second lockfile merely to install Archinsight.
+
+## Global Installation
+
+A user who wants the \`archinsight\` command available across projects can
+install or update it globally:
+
+\`\`\`shell
+npm install -g @archinsight/cli@latest
+archinsight --version
+\`\`\`
+
+Global installation is a user-level machine change. Suggest it as an option;
+run it only when the user explicitly authorizes that installation scope.
+
+## Generate a New Skill Package
+
+Choose the target used by the agent runtime:
+
+\`\`\`shell
+archinsight skill init . --target codex
+archinsight skill init . --target claude
+archinsight skill init . --target generic
+\`\`\`
+
+Without \`--out\`, these commands use the target's standard directory. A normal
+\`skill init\` requires that the complete output directory does not exist. If it
+does exist, the CLI reports \`Refusing to initialize skill because output
+directory ... already exists\` before writing any generated file.
+
+## Regenerate an Existing Skill Package
+
+Use \`--force\` only for deliberate replacement of a generated package:
+
+\`\`\`shell
+archinsight skill init . --target codex --force
+\`\`\`
+
+The CLI generates the complete new package in a temporary sibling directory
+before replacing the target. \`--force\` removes everything under the target
+directory, including files not generated by the current release. Inspect the
+resolved target first and keep project-authored instructions outside that
+generated directory. Use \`--out <dedicated-directory>\` when the standard path
+is not appropriate.
+
+Never update a generated skill by running plain \`skill init\` repeatedly or by
+copying only the files that happen to be missing. Regenerate the entire package
+with the installed CLI, then restart the agent session when its runtime discovers
+skills only at startup.
+`;
+}
 function genericModelingReference() {
   return `# Modeling Guidance
 
@@ -40715,8 +41011,8 @@ Keep language/framework definitions separate from graph model files.
   \`define enum of\`, \`define presentation\`, \`extend type\`,
   \`extend enum of\`, and \`extend presentation\`.
 - Context files begin with \`context <id>\` and describe logical architecture.
-- Environment files begin with \`environment <id>\` and describe concrete
-  deployments and infrastructure inventory.
+- Environment files begin with exactly one \`environment <id>\`, followed by
+  one or more concrete deployments and their infrastructure inventory.
 
 Each source has one role. Do not mix definitions, a context, and an environment
 in one file. Put shared vocabulary in framework files, logical objects and
@@ -40727,9 +41023,9 @@ 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.
+about to detail with containers, services, components, code, and deployment
+relationships. This keeps the selected source file useful as a C2, C3, C4, or
+Deployment 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
@@ -40744,19 +41040,19 @@ context.
 
 ## Projections Are Bottom-Up
 
-Built-in C1/C2/C3/C4 views are selected from the linked model. They are not
-separate diagrams to author by hand.
+Built-in C1, C2, C3, C4, and Deployment views are selected from the linked model.
+They are not separate diagrams to author by hand.
 
 - C1 is context-oriented and can aggregate lower-level relationships upward.
-- C2, C3, and C4 are usually scoped by the selected source file through
+- C2, C3, C4, and Deployment are usually scoped by the selected source file through
   \`--source\` / \`$tab\`.
 - A file often has one focal system, container, or deployment slice for the view
   it is meant to render, but the exact scope is determined by the query used for
   visualization.
 - Do not try to reconstruct a deeper view from a broader one. C1 carries too
-  little information to recreate C2/C3 details.
+  little information to recreate C2, C3, or C4 details.
 
-If an element is missing from a C2/C3/C4 render, first check the query, selected
+If an element is missing from a C2, C3, C4, or Deployment render, first check the query, selected
 source file, and relationship level before assuming the model is wrong.
 
 ## Keep Relationship Levels Deliberate
@@ -40799,6 +41095,8 @@ type hierarchy:
 - Built-in containers/services live under systems because \`System\` declares
   \`List of Container _\`.
 - Components live where the relevant container/service type allows them.
+- Project-defined code types derive from \`CodeElement\` and live where the
+  project framework exposes compatible component or code-element slots.
 - Custom project types can change the available constructors and allowed child
   slots; inspect them before writing.
 
@@ -40807,28 +41105,28 @@ than forcing a link or inventing a wrapper element.
 
 ## Choose Infrastructure Depth Per System
 
-Do not force every project into C4/deployment on the first pass. Most modeling
+Do not force every project into 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.
+deployment model.
 
 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.
+cost is that C2 now mixes logical containers with infrastructure, and a
+separate Deployment view is effectively absent for that system.
 
-Clean C4 keeps C2 logical and moves physical realization into concrete
-deployments, context-owned deployment profiles, inventory slots, and projection
-rules. This is more work up front, but it supports many-to-many deployment: one
-logical service can target several concrete deployments whose infrastructure
-differs by stage, region, provider, or organizational boundary.
+Explicit deployment modeling keeps C2 logical and moves physical realization
+into concrete deployments, context-owned deployment profiles, inventory slots,
+and projection rules. This is more work up front, but it supports many-to-many
+deployment: one logical service can target several concrete deployments whose
+infrastructure differs by stage, 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.
+This choice is per-system, not global. A critical system can use explicit
+deployment modeling while peripheral systems stay pragmatic in C2. Starting
+cheap is acceptable, but upgrading mixed C2 infrastructure into explicit
+deployment modeling is a migration, not just an extra attribute.
 
 ## Eventing
 
@@ -40845,8 +41143,9 @@ For pub/sub, make the dependency consumer-owned:
   dependencies instead of editing a subscriber list on the producer.
 
 Do not invent a broker node just to make the diagram look familiar. If the
-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
+chosen style is explicit deployment modeling and the broker is deployment
+infrastructure, model it in the deployment inventory. 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.
@@ -40858,6 +41157,147 @@ no legitimate endpoint in scope, flag the uncertainty and ask for the missing
 boundary or owner.
 `;
 }
+function genericImportingModelsReference() {
+  return `# Importing Existing Architecture Models
+
+Use this reference when architecture already exists in another DSL, a diagram,
+an inventory, or prose. Import is a semantic reconstruction: the objective is
+to preserve supported architecture facts in Insight, not to reproduce the
+source file line by line or preserve its drawing coordinates.
+
+## Establish the Source Contract
+
+Before writing Insight, identify which inputs are authoritative and what each
+one represents. A repository-wide model may describe ownership and identity;
+an individual diagram may be only one filtered view. An infrastructure
+inventory can describe deployed resources without explaining logical systems.
+Prose can contain facts that are absent from every diagram.
+
+Create a small mapping ledger while working. For each source object, record its
+source identity, intended Insight id and type, owner or context, evidence, and
+any unresolved ambiguity. Preserve stable source ids when they are meaningful
+and valid Insight identifiers. Never merge objects solely because their display
+names look similar.
+
+## Judge the Evidence, Not Just the Format
+
+Source formats provide different levels of architectural evidence.
+
+PlantUML, Mermaid, and DOT are often used as drawing languages. Their text may
+be deterministic enough to reproduce one picture, while architectural identity,
+ownership, relationship meaning, and consistency across several diagrams remain
+author conventions. Treat a node or arrow found there as an observation from
+that diagram. Do not assume that repeated labels identify one object, that a
+visual boundary is semantic containment, or that an arrow carries the same
+dependency meaning in every file.
+
+LikeC4, Structurizr, and other model-oriented DSLs usually provide more reliable
+identities, containment, and directed relationships. Accept facts that are
+explicitly encoded in their model, but do not treat the model as complete by
+default. A workspace or selected view may omit deployment, lower architectural
+levels, external ownership, relationship technology, operational constraints,
+or the reason a boundary was chosen. Deterministic input can still be partial
+input.
+
+Inventories and generated exports are reliable only for the fields their
+producer owns. A cloud inventory can prove that a resource exists and expose
+its configuration, but it may say nothing about the logical service using it or
+the architectural dependency it realizes.
+
+When required semantics are absent or contradictory, first search the relevant
+repository sources, attached artifacts, configured skills, MCP integrations,
+and other authorized information sources available to the agent. Prefer the
+most authoritative source for the fact and record conflicts instead of silently
+choosing one. Do not ask the user to provide information that can be retrieved
+reliably through those sources.
+
+Only when the missing fact cannot be obtained independently should the agent
+stop that part of the translation and ask the user for context or documentation.
+Send one short message with one or two focused questions. Good questions resolve
+a specific mapping decision, for example:
+
+- Does \`A -> B\` represent a runtime call, data flow, or dependency ownership?
+- Is this system external to the modeled context, or only outside the current
+  diagram's focal system?
+- Is this deployment node a concrete resource, a reusable environment slot, or
+  a visual grouping?
+
+Continue with independent, well-supported facts while the answer is pending.
+Record unresolved mappings instead of selecting the most plausible type,
+boundary, direction, or deployment structure.
+
+## Interpret Common Sources Carefully
+
+| Source concept | Likely Insight concept | Required judgment |
+| --- | --- | --- |
+| C4 person or actor | \`Actor\` or \`ExternalActor\` | Decide externality relative to the selected context. |
+| C4 software system | \`System\` or \`ExternalSystem\` | Confirm ownership and context boundary. |
+| C4 container | \`Container\` or \`Service\` | Choose the name that best communicates its runtime purpose. |
+| C4 component | \`Component\` | Confirm its owning container or service. |
+| C4 code element | Project-defined \`CodeElement\` descendant | Preserve the source vocabulary and introduce a concrete code type only when the source identifies its meaning and containment. |
+| Relationship | Insight wire | Preserve direction, kind, technology, and the object that owns the dependency. |
+| Deployment node or resource | Environment, deployment, or infrastructure component | Separate a reusable deployment scheme from a concrete resource instance. |
+| Diagram boundary | Context, owner, group, or query scope | A visual box alone does not prove semantic containment. |
+
+LikeC4, Structurizr, and other C4-oriented DSLs usually provide the closest logical mapping,
+but their deployment instances and views still do not map mechanically to
+Insight profiles and projections. Mermaid, PlantUML, and DOT often provide
+visible nodes and arrows while omitting type, ownership, context, and deployment
+semantics. YAML, JSON, and cloud inventories provide structure but do not make
+field names architectural facts. Apply the evidence rules above and ask for
+missing semantics instead of deriving them from visual placement or
+serialization shape.
+
+## Import Outside In
+
+1. Inventory the source objects, relationships, boundaries, and views without
+   editing them.
+2. Define the Insight context boundary and shared external contexts.
+3. Create project-specific definitions only when the source has a real reusable
+   concept that the built-in type system does not express.
+4. Import C1 actors, systems, and their highest-level relationships. Link the
+   project and resolve identity or ownership errors.
+5. Add C2 containers and services, then move relationships to the lowest known
+   logical endpoints so built-in rollup can produce higher-level views.
+6. Add C3 components only where the source provides component-level evidence.
+7. If C4 is in scope, first inspect the repository for existing \`CodeElement\`
+   descendants and containment slots. Reuse that vocabulary without asking. Ask
+   the user which entity kinds to model only when the project has no Code layer
+   or the import requires extending its vocabulary, unless the request already
+   makes that choice. Add code elements only where the source identifies their
+   containment and dependencies.
+8. Build deployment models separately from concrete environments and deployments. Use
+   profiles, \`runsOn\`, \`uses\`, and projections to map the logical model to
+   physical infrastructure; do not turn every deployment node into a logical
+   C2 element.
+9. Split definitions, contexts, and environments into valid source roles and
+   make cross-file visibility explicit with imports.
+
+For a normal synchronous wire, the element that owns the dependency declares
+the wire and the arrow points from that owner to its target. Async pub/sub can
+use consumer-owned dependencies as described in \`references/modeling.md\`.
+Preserve source direction unless the target architecture semantics explicitly
+require a different ownership model, and record that decision.
+
+## Reconcile the Result
+
+Validate each imported layer rather than translating the complete source before
+the first link:
+
+\`\`\`shell
+archinsight link . --format text
+archinsight structure . --format json
+archinsight query . -c <context-id> -v no-filter --format json
+\`\`\`
+
+Use C1, C2, C3, C4, and Deployment query JSON to compare the intended scope and
+relationships at each level. Counts can reveal omissions, but equal counts do
+not prove semantic equivalence. Compare qualified identities, types, ownership,
+wire direction, externality, and deployment projection. Keep unresolved source
+facts visible in the import report instead of fabricating declarations to make
+the model appear complete.
+`;
+}
 function genericSyntaxReference() {
   return `# Insight Syntax Reference
 
@@ -40885,6 +41325,11 @@ environment eu
 Definitions, contexts, and environments are separate source roles. Never put
 more than one of these roles in the same file.
 
+An environment source has exactly one \`environment <id>\` header. Any
+\`deployment\` declarations that follow are top-level declarations in the file,
+but the linker attaches them to that environment. Put a second environment in a
+second source file. One environment source may contain several deployments.
+
 Use indentation to define ownership. Children belong to the nearest less-indented
 parent.
 
@@ -40900,7 +41345,7 @@ extensions, links, queries, and generated navigation refer to those identities.
 
 ## Common Elements
 
-Use built-in constructors for C4-style architecture:
+Use built-in constructors for the C1-C3 parts of a C4 architecture:
 
 \`\`\`insight
 external actor customer
@@ -40929,6 +41374,11 @@ Useful built-ins include:
 - \`service\` for backend/container services.
 - \`component\` for internals of a selected container or service.
 
+Core has no concrete constructor for the C4 Code level. It provides the
+constructorless \`CodeElement\` base, while project definitions supply concrete
+code types and their constructors. Read \`references/c4-code.md\` before adding
+or instantiating code-level concepts.
+
 Built-in nesting follows the core type tree, not the English noun. For example,
 actors and systems are context-level because their base type is a boundary
 element, while containers are allowed under systems because the \`System\` type
@@ -40991,6 +41441,18 @@ but reports a warning because a scattered effective schema is difficult to
 inspect and review. An agent should consolidate them rather than create another
 extension elsewhere.
 
+There are two valid ways to define environment slots, with different scope:
+
+- \`extend type Environment\` adds one project-wide slot schema to every
+  environment.
+- \`define type ApplicationEnvironment of Environment\` creates a distinct,
+  constructorless environment schema. Environment declarations infer that
+  subtype from its slot names when the match is unambiguous.
+
+Use the base-type extension when every environment shares one contract. Use a
+named subtype when the project needs isolated environment families. Do not
+describe these forms as interchangeable.
+
 After changing a type definition, run \`archinsight structure . --format text\`
 to see the updated type tree and available constructors.
 
@@ -41074,6 +41536,12 @@ It must be the last attribute in the type body. Compatible child declarations
 can then appear directly under the parent. The \`_\` symbol can also replace an
 object id when no source-level reference to that instance is needed.
 
+An anonymous instance cannot later be the target of \`runsOn\`, a typed
+reference attribute, an import, or a relationship. Give the object a stable id
+whenever another declaration must reference it. The linker reports
+\`ANONYMOUS_INSTANCE_NOT_REFERENCEABLE\` when \`_\` is used as a reference
+target.
+
 ## Enumerations
 
 An enum uses a constructorless type as its closed value domain:
@@ -41171,7 +41639,7 @@ agents without changing the model:
 context checkout
 
 system checkout_platform
-    # Keep logical services here; deployment inventory belongs in C4 files.
+    # Keep logical services here; deployment inventory belongs in deployment files.
     name = Checkout Platform
 \`\`\`
 
@@ -41234,7 +41702,7 @@ Available annotations:
   useful. The default Graphviz renderer highlights it in red.
 
 Annotations can be stacked and are preserved on projected relationships, so a
-C4 projection can still show that the original logical relationship was planned
+Deployment projection can still show that the original logical relationship was planned
 or deprecated. Annotations cannot decorate assignments; use a comment above the
 assignment when you only need a local authoring hint.
 
@@ -41385,10 +41853,22 @@ Components should describe responsibilities, not every class or function.
 As with C2, a C3 file often focuses one container or service, but custom queries
 can intentionally choose a different scope.
 
-## C4: Deployment
+## C4: Code
+
+Use project-defined \`CodeElement\` descendants when a component needs a code
+view. Read \`references/c4-code.md\` before introducing modules, packages,
+classes, functions, schemas, or another code vocabulary. Keep those type and
+containment definitions separate from the context source, and use
+\`examples/c4-code\` as the minimal working pattern.
+
+The built-in C4 query selects the project's code elements without prescribing
+what they mean. Model only implementation structures that explain stable
+responsibilities, interfaces, or dependencies.
+
+## Deployment
 
 Use deployment profiles and infrastructure types when physical realization is
-important. Read \`references/c4-deployment.md\` before writing a real C4 model.
+important. Read \`references/deployment.md\` before writing a real deployment model.
 
 \`\`\`insight
 environment eu
@@ -41411,7 +41891,7 @@ 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
+deployment files often focus one deployment slice. The rendered scope is
 defined by the query, projection selectors, and selected source file.
 
 ## Layering Rules
@@ -41620,7 +42100,8 @@ external system analytics_platform
 - 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.
+- Adding implementation details that belong to C2, C3, or a project-defined
+  code model.
 - Drawing a relationship without naming what capability or dependency it means.
 - Choosing constructors before deciding the context boundary.
 
@@ -41661,14 +42142,14 @@ containers/services.
 
 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.
+regions belong to 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,
+tradeoff: the C2 view becomes mixed, deployment is not modeled for that system,
 and many-to-many deployment across different environments will not be available
-until the model is migrated to clean C4.
+until the model is migrated to explicit deployment modeling.
 
 Choose this per system. Do not make the whole repository clean or mixed just
 because one system needs that style.
@@ -41822,7 +42303,7 @@ Do not list consumers under the producer just to answer "who listens to this
 topic?" That answer belongs in a query over incoming async dependencies.
 
 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
+C2, a broker is usually deployment 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.
@@ -42150,7 +42631,7 @@ links:
 
 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.
+usually belong to deployment or infrastructure modeling.
 
 The built-in views roll a component dependency up to its owning containers at
 C2 and, when it crosses system boundaries, to its owning systems at C1. Remove
@@ -42183,22 +42664,127 @@ Use \`examples/c3-components.ai\` as a compact valid C3 model when syntax is
 unclear.
 `;
 }
-function genericC4DeploymentReference() {
-  return `# C4 Deployment
+function genericC4CodeReference() {
+  return `# C4 Code
+
+Use C4 when the task needs to explain the implementation structure inside one
+or more components. Archinsight intentionally does not prescribe whether that
+structure consists of modules, packages, namespaces, classes, functions,
+schemas, or another project vocabulary.
+
+## Determine the Modeling Vocabulary
+
+Inspect project definitions and existing C4 sources before asking questions. If
+the repository already defines \`CodeElement\` descendants and containment slots
+that cover the task, infer the intended entity kinds from that vocabulary and
+reuse it without asking the user to choose again.
+
+Ask the user which code entity kinds they want only when creating a new C4 Code
+layer or when the requested work requires new entity kinds or containment rules
+beyond the existing vocabulary. Do not ask when the current request already
+makes that choice. This decision cannot be inferred from implementation source
+alone because a new or expanded Code vocabulary is user-defined by design.
+
+## Core Contract
+
+\`CodeElement\` is a constructorless subtype of \`Element\`. Project definitions
+derive concrete code types from it and supply their constructors, attributes,
+relationships, presentations, and containment rules. Do not instantiate
+\`CodeElement\` directly and do not assume a code ontology that the project has
+not defined.
+
+Keep code types and extensions in a definitions source. A minimal framework can
+derive a module type and make code elements anonymous children of components:
+
+\`\`\`insight
+define type Module of CodeElement
+    constructor module
+
+    required Text name
+    Text responsibility
+    List of Wire links
+    List of CodeElement children
+
+extend type Component
+    List of CodeElement _
+\`\`\`
+
+The anonymous list allows code declarations to appear directly below a
+component without a \`code:\` wrapper. It must be the component type's only
+anonymous list and the final attribute in this extension. Use a named slot only
+when that wrapper conveys useful structure in the project's chosen vocabulary.
+
+\`CodeElement\` is separate from \`ComponentElement\`. This keeps code objects out
+of C3 unless a custom query intentionally combines both levels.
+
+A code type named for a schema represents a logical or source-controlled code
+artifact. A deployed database, volume, or bucket is physical infrastructure and
+uses \`Storage\` in the Deployment model. Do not use a code-level schema as a
+substitute for its physical storage instance, or model the storage instance as
+code.
+
+## Built-In View
+
+The built-in \`c4\` query selects every \`CodeElement\` whose
+\`sourceIdentity\` belongs to \`$tab\`, including code contributed to roots from
+that tab through \`extend\`. It returns direct relationships between code
+elements and groups them by immediate parent. A relationship can bring its
+target code element into the result from outside the selected tab.
+
+The query does not infer classes, packages, or nesting from source paths. Read
+the project's definitions and actual containment slots before editing a C4
+model. Copy \`examples/builtin-views/c4.aiq\` only when the project needs a
+different type filter or grouping rule.
+
+## Workflow
+
+1. Inspect existing definitions for \`CodeElement\` descendants and component
+   containment slots.
+2. Reuse the existing vocabulary when it covers the requested model.
+3. If the project has no Code layer or the task requires extending its
+   vocabulary, ask the user which new entity kinds and containment rules they
+   want unless the request already specifies them.
+4. Define only the confirmed additions, keeping the definition source separate
+   from context sources.
+5. Place code instances under the component slots provided by that framework.
+6. Preserve relationship ownership: the code object containing a wire is its
+   source, and the referenced object is its target.
+7. Prefer responsibilities, stable interfaces, and important dependencies over
+   an inventory of every declaration.
+8. Validate the full project, then inspect the exact C4 graph:
+
+\`\`\`shell
+archinsight link . --format text
+archinsight query . -c <context-id> -s <code-source.ai> -v c4 --format json
+archinsight render . -c <context-id> -s <code-source.ai> -v c4 -f svg -o code.svg
+\`\`\`
+
+Use the self-contained \`examples/c4-code\` project when the syntax for a code
+framework or model is unclear. Deployment is a separate view selected with
+\`--view deployment\`; never use C4 as an alias for Deployment.
+`;
+}
+function genericDeploymentReference() {
+  return `# Deployment
 
-Use C4 to project the logical architecture onto physical infrastructure: where
+Use Deployment modeling to project the logical architecture onto physical infrastructure: where
 logical elements run, which infrastructure they use, and how their wires pass
-through the physical world. Keep C1-C3 logical; deployment inventory and
+through the physical world. Keep C1-C4 logical; deployment inventory and
 projections supply the physical view.
 
+The built-in Deployment view includes a logical element only when its deployment
+resolves at least one \`runsOn\` or \`uses\` infrastructure object. A logical wire
+appears only through physical edges created by its deployment projection. A
+plain logical wire is intentionally omitted from Deployment.
+
 Model the infrastructure immediately relevant to those logical elements and
-connections. Do not expand C4 into a complete provider, transit, replication,
+connections. Do not expand a Deployment view into a complete provider, transit, replication,
 or network topology. Keep replication modes and deeper operational detail in
 \`description\`, \`technology\`, \`via\`, notes, or project-specific attributes
 unless an intermediate component is itself important to the architecture.
 
 When a project models deployment explicitly, databases, storage, brokers,
-gateways, network connections, compute, and observability belong at C4. Leave
+gateways, network connections, compute, and observability belong in the Deployment view. Leave
 them at C2 only when the project deliberately chooses a compact mixed model and
 does not plan to describe deployment in detail.
 
@@ -42206,8 +42792,9 @@ does not plan to describe deployment in detail.
 
 There are four distinct concepts:
 
-1. \`Environment\` owns one or more named \`Deployment\` objects, such as
-   \`test\` and \`production\`.
+1. One environment source starts with exactly one \`environment <id>\` and may
+   own one or more named \`Deployment\` objects, such as \`test\` and
+   \`production\`.
 2. A concrete \`Deployment\` fills infrastructure slots defined by the
    environment type.
 3. A context-owned \`DeploymentProfile\` maps logical elements to concrete
@@ -42221,9 +42808,12 @@ Do not put application deployment profiles in environment inventory files.
 Environment files own concrete infrastructure. The application context owns
 the profiles that decide where its systems, containers, and services run.
 
-One environment can contain several deployment schemes. Profiles may select
-different schemes such as \`production from eu\` and \`test from eu\` without a
-conflict because these are different concrete deployments.
+Deployments are written as top-level siblings after the environment header, not
+indented inside it, but they remain owned by that environment. A second
+environment requires a second source file. One environment can contain several
+deployment schemes, and profiles may select \`production from eu\` and
+\`test from eu\` without a conflict because they are different concrete
+deployments.
 
 ## Framework and inventory
 
@@ -42249,6 +42839,13 @@ define type Monitoring of InfrastructureComponent
     constructor monitoring
 \`\`\`
 
+A project with one shared environment contract may instead use
+\`extend type Environment\` with the same slots. That extension changes the base
+type for every environment. A named subtype such as \`ApplicationEnvironment\`
+keeps the contract isolated and is preferable when the project has several
+environment families. Environment declarations infer a constructorless subtype
+from the slots used by their deployments; the match must be unambiguous.
+
 Fill those slots inside concrete deployments:
 
 \`\`\`insight
@@ -42286,6 +42883,29 @@ deployment production
 An explicit object id may differ from the slot name: \`public_edge\` still fills
 the \`publicGateway\` slot of \`eu/production\`.
 
+## Concrete infrastructure placement
+
+The \`runsOn:\` attribute on an infrastructure component is a typed reference to
+one concrete, named infrastructure instance:
+
+\`\`\`insight
+compute kubernetes
+    name = Kubernetes
+
+infrastructureComponent ingress
+    name = Ingress
+    runsOn:
+        kubernetes
+\`\`\`
+
+The target \`kubernetes\` is an object id. It must be visible in the source and
+cannot be the anonymous id \`_\`. Anonymous objects are suitable only when no
+other declaration needs to address them.
+
+This reference form is different from \`runsOn compute\` inside a deployment
+profile. The profile form names an environment slot and resolves its concrete
+instance separately in every deployment selected by \`appliesTo\`.
+
 ## Context-owned deployment profiles
 
 Declare profiles in the logical context and reference concrete deployments with
@@ -42382,6 +43002,15 @@ Components inherit effective deployments from their nearest deployed logical
 ancestor, normally a container or service. Put profiles on independently
 deployable C2 elements unless a C3 component truly has distinct placement.
 
+Deployment completeness checks become active only after the project starts
+using the corresponding feature. Once a deployment-relevant wire has a \`deployment\`
+block, the linker warns about other wires between different deployment endpoints with
+no deployment and about configured wires that produce no physical projection.
+A component relationship inside one container collapses to a self-relationship
+in the Deployment view and does not require a physical projection. Element checks activate
+separately by logical modeling family, so starting container placement does not
+demand artificial placement for every system, component, or external actor.
+
 ## Projection execution semantics
 
 Projection rules belong to concrete infrastructure instances because paths can
@@ -42469,13 +43098,21 @@ Run:
 
 \`\`\`shell
 archinsight link . --format text
-archinsight render . -c <context> -s <source.ai> -v c4 -f svg -o c4.svg
+archinsight query . -c <context> -s <logical-source.ai> -v deployment --format json
+archinsight render . -c <context> -s <logical-source.ai> -v deployment -f svg -o deployment.svg
 \`\`\`
 
+A clean link proves that syntax, types, imports, and deployment references are
+valid. It does not prove that a view selected the intended semantic graph.
+Inspect query JSON before relying on SVG: query output is the authoritative list
+of elements and edges selected for rendering.
+
 Treat missing slots, overlapping profile deployments, non-network wire uses,
-and ambiguous references as model errors. If a physical arrow is absent, check
-the endpoint profiles, their \`appliesTo\` deployments, the requested network
-slot, and the concrete instance projection in that order.
+and ambiguous references as model errors. Treat \`WIRE_MISSING_DEPLOYMENT\`,
+\`WIRE_DEPLOYMENT_NOT_PROJECTED\`, \`ELEMENT_MISSING_DEPLOYMENT\`, and
+\`ELEMENT_DEPLOYMENT_NOT_PHYSICAL\` as incomplete deployment coverage. If a physical
+arrow is absent, check the endpoint profiles, their \`appliesTo\` deployments,
+the requested network slot, and the concrete instance projection in that order.
 `;
 }
 function genericScalingReference() {
@@ -42493,8 +43130,8 @@ Prefer one shared framework per repository:
   types, and presentation tweaks;
 - 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;
+- one or more inventory files, each with exactly one concrete
+  \`environment <id>\` header and one or more deployments owned by it;
 - shared external contexts for external actors and systems reused by many
   systems;
 - context-owned deployment profile files that map logical elements to concrete
@@ -42505,6 +43142,12 @@ Do not copy the same environment or infrastructure type definitions into every
 system file. Keep concrete inventory in environment files and keep each
 application's deployment profiles in its logical context.
 
+Use \`extend type Environment\` when the repository intentionally has one slot
+contract shared by every environment. If several environment families need
+different contracts, define constructorless subtypes such as
+\`ApplicationEnvironment\` and \`DataEnvironment\` instead. Keep either form in
+the shared framework area rather than repeating it in inventory files.
+
 ## Framework Once, Use Everywhere
 
 A typical deployment framework file contains only shared vocabulary: type
@@ -42693,9 +43336,9 @@ 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
+## Deployment Multi-File Pattern
 
-For C4, keep these responsibilities separate:
+For Deployment modeling, keep these responsibilities separate:
 
 - framework file: environment schemas, infrastructure constructors, and
   presentation definitions;
@@ -42703,15 +43346,16 @@ For C4, keep these responsibilities separate:
 - logical context files: deployment profiles with \`appliesTo\` references and
   the relationships whose network paths should render.
 
-When rendering C4 with \`-s <source.ai>\`, remember that source/tab scoping is
+When rendering Deployment with \`-s <source.ai>\`, remember that source/tab scoping is
 part of the view. The selected tab includes the full model fragment rooted in
 that source, including relationships contributed to those roots by \`extend\`
 files. Keep imported framework and inventory reusable, and validate the rendered
-C4 output after changing which root a traffic relationship extends:
+Deployment output after changing which root a traffic relationship extends:
 
 \`\`\`shell
 archinsight link . --format text
-archinsight render . -c deployment_shop -s c4-deployment.ai -v c4 -f svg -o deployment-c4.svg
+archinsight query . -c deployment_shop -s deployment.ai -v deployment --format json
+archinsight render . -c deployment_shop -s deployment.ai -v deployment -f svg -o deployment.svg
 \`\`\`
 
 If projected infrastructure edges disappear after a split, first check whether
@@ -42735,7 +43379,7 @@ the extension target, or the file boundary.
 9. Prefer a named import for repeated references and an inline qualifier for a
    one-off relationship or list value.
 10. Validate with \`archinsight link . --format text\`.
-11. Render important C1/C2/C3/C4 views with explicit \`-c\`, \`-s\`, and \`-v\`
+11. Render important C1, C2, C3, C4, and Deployment views with explicit \`-c\`, \`-s\`, and \`-v\`
    options.
 `;
 }
@@ -42755,8 +43399,8 @@ Keep source files in one role:
   \`extend enum of\`, and \`extend presentation\`;
 - context files: \`context <id>\`, imports, logical graph objects,
   relationships, object extensions, and deployment profiles;
-- environment files: \`environment <id>\`, concrete deployments, and
-  infrastructure inventory.
+- environment files: exactly one \`environment <id>\` header followed by its
+  concrete deployments and infrastructure inventory.
 
 Do not mix these three roles in one file. When a model needs custom vocabulary,
 add or edit a framework file first, then use the resulting constructors and
@@ -42910,6 +43554,15 @@ 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 Code Extension Point
+
+\`core_code.ai\` declares the constructorless \`CodeElement\` base type. It is
+the only code-level ontology supplied by core. Project definitions derive
+concrete types from it and provide their constructors, attributes,
+presentations, relationships, and containment slots. Read
+\`references/c4-code.md\` before adding those definitions or using the built-in
+C4 query.
+
 ## Built-in Deployment Infrastructure
 
 \`core_deployment.ai\` provides common infrastructure inventory types:
@@ -42928,8 +43581,19 @@ and project framework files before assuming only core constructors exist.
   \`$to\` or expand the relationship through relevant gateways and other
   first-order infrastructure.
 
-Extend \`Environment\` with slots for these types, then fill each concrete
-\`environment <id>\` with env-local instances.
+Add slots either by extending the shared \`Environment\` type or by defining a
+constructorless subtype. The extension gives every environment the same
+contract. A subtype keeps a contract isolated and is inferred from the slot
+names used by an environment's deployments.
+
+Each environment source has one \`environment <id>\` header. Top-level
+\`deployment\` declarations following that header are owned by the environment,
+and each deployment fills the chosen slot contract with concrete instances.
+
+The \`runsOn\` attribute on \`InfrastructureComponent\` points to one named
+infrastructure instance. The target cannot be anonymous. By contrast,
+\`runsOn compute\` inside a \`DeploymentProfile\` names the \`compute\` slot and
+resolves a concrete target separately for every selected deployment.
 
 ## Reading Type Extensions
 
@@ -42952,6 +43616,18 @@ Interpretation:
 - \`archinsight structure . --format text\` is the quickest way to inspect the
   effective type tree after extensions are applied.
 
+Use a dedicated subtype instead when different environment families need
+different slots:
+
+\`\`\`insight
+define type ApplicationEnvironment of Environment
+    Compute compute
+    NetworkConnection network
+\`\`\`
+
+The two forms are both valid but are not interchangeable: extending the base
+type is global, while defining a subtype introduces an isolated schema.
+
 Use \`extend service checkout_api\` or another constructor form only when you
 intend to extend one graph object instance in a \`context\`. Use \`extend type\`
 when you intend to change the available vocabulary/schema for all instances of
@@ -43084,7 +43760,7 @@ and links.
 ## Reading Projections
 
 Projection definitions describe how deployment/runtime information is projected
-into renderable graph relationships. Use them when C4/deployment diagrams are
+into renderable graph relationships. Use them when deployment diagrams are
 involved or when a query uses projected relationships.
 
 Rules of thumb:
@@ -43122,6 +43798,10 @@ level<TAB>code<TAB>source<TAB>line<TAB>column<TAB>message
 Treat \`ERROR\` as blocking. \`WARNING\` and \`NOTE\` can still be useful design
 feedback.
 
+A successful link proves that sources parse, types and imports resolve, and
+linker constraints hold. It does not prove that a built-in or custom view
+selects the intended semantic graph.
+
 Inspect project structure:
 
 \`\`\`shell
@@ -43129,43 +43809,209 @@ archinsight structure . --format text
 archinsight structure . --format json
 \`\`\`
 
-Render a diagram when a context id is known:
+Inspect the selected graph before rendering whenever a change affects C2, C3,
+C4, Deployment, projections, or query text:
+
+\`\`\`shell
+archinsight query . -c <context-id> -s <source.ai> -v c2 --format json
+archinsight query . -c <context-id> -s <source.ai> -v c3 --format json
+archinsight query . -c <context-id> -s <source.ai> -v c4 --format json
+archinsight query . -c <context-id> -s <source.ai> -v deployment --format json
+\`\`\`
+
+Then render the same context, source, and view:
 
 \`\`\`shell
 archinsight render . -c <context-id> -v c1 -f svg -o diagram.svg
 archinsight render . -c <context-id> -s <source.ai> -v c2 -f svg -o diagram.svg
 archinsight render . -c <context-id> -s <source.ai> -v c3 -f svg -o diagram.svg
 archinsight render . -c <context-id> -s <source.ai> -v c4 -f svg -o diagram.svg
+archinsight render . -c <context-id> -s <source.ai> -v deployment -f svg -o diagram.svg
 \`\`\`
 
 Run a custom query from a file:
 
 \`\`\`shell
 archinsight query . -c <context-id> -s <source.ai> -q query.aiq -f text
+archinsight query . -c <context-id> -s <source.ai> -q query.aiq -f json
 archinsight render . -c <context-id> -s <source.ai> -q query.aiq -f svg -o diagram.svg
 \`\`\`
 
+Use three validation layers:
+
+1. \`link\` for syntax, types, imports, and project diagnostics.
+2. \`query --format json\` for the exact semantic elements, edges, endpoints,
+   origins, and groups selected by the view.
+3. \`render\` for presentation, Graphviz layout, labels, and styling.
+
+When JSON already contains an unexpected edge, investigate query matching,
+\`ROLLUP\`, selectors, and projection origin before editing the model. When JSON
+is correct but SVG is not, investigate rendering or layout. Do not use a clean
+link or a plausible image as a substitute for semantic query inspection.
+
 Useful built-in views:
 
 - \`c1\` for system context.
 - \`c2\` for containers/services in the selected source.
 - \`c3\` for components in the selected source.
-- \`c4\` for deployment-oriented views.
+- \`c4\` for project-defined code elements in the selected source.
+- \`deployment\` for deployment-oriented views.
 - \`no-filter\` for the full context.
 
-C2, C3, C4, and custom queries often depend on the active file. Pass
+C2, C3, C4, Deployment, and custom queries often depend on the active file. Pass
 \`--source <file>\` / \`-s <file>\` whenever the query uses \`$tab\`; otherwise
 the CLI may choose the first source and render a valid but wrong view.
 
 The bundled \`examples\` directory contains several independent model projects,
 not one project to link as a whole. Validate \`layered-architecture.ai\`, the C1,
-C2, and C3 files individually. Validate the three \`c4-deployment*.ai\` files
-together, and validate \`c4-private-gateway\` as its own directory.
+C2, and C3 files individually. Validate \`c4-code\` as its own directory. Validate
+the three \`deployment*.ai\` files together, and validate
+\`deployment-private-gateway\` as its own directory.
 
 If the CLI is missing, do not silently install it. Ask the user to install or
 expose \`@archinsight/cli\`.
 `;
 }
+function genericAnalysisReference() {
+  return `# Analyzing an Insight Project
+
+Use analysis mode to answer architecture questions without modifying the model.
+Start from the linked semantic graph, then use queries to select the relevant
+subgraph. Treat the rendered image as a presentation artifact, not as the
+primary analytical result.
+
+## What the Query Language Is For
+
+Insight queries select nodes and relationships for inspection or rendering.
+The current subset is well suited to:
+
+- inventory by context, source fragment, type, or attribute;
+- direct outgoing and incoming dependencies;
+- logical relationships rolled up to C1, C2, or C3 ownership levels;
+- external-boundary and technology-focused slices;
+- async versus sync relationship slices;
+- logical-to-physical deployment placement and projected wire paths;
+- comparing a broad context graph with a focused built-in or custom view.
+
+It is not a general graph analytics language. It has no aggregation functions,
+computed return columns, variable-length paths, shortest-path operations,
+subqueries, ordering, or pagination. It cannot directly express transitive
+impact, cycle detection, centrality, counts, or the absence of a relationship.
+\`ROLLUP\` climbs containment ownership; it is not transitive dependency
+traversal.
+
+For questions outside that boundary, select a sufficiently broad graph with
+\`--format json\` and analyze that JSON with the agent's ordinary data-processing
+tools. Keep this second step read-only and state clearly which result comes from
+the Insight query and which result was computed from its output.
+
+## Analysis Workflow
+
+1. Run \`archinsight link . --format text\`. Diagnostics are part of the
+   evidence; do not silently analyze a partially linked model as if it were
+   complete.
+2. Run \`archinsight structure . --format json\` to establish contexts, source
+   roles, types, objects, extensions, and qualified identities.
+3. Choose the smallest query that answers the question. Use a built-in view for
+   an architectural level, a focused custom query for one-hop questions, or
+   \`no-filter\` for a broad logical export.
+4. Inspect query JSON before rendering. Distinguish selected outer endpoints,
+   underlying edge endpoints, derived relationships, and projection origins.
+5. If the question needs traversal, aggregation, comparison, or absence checks,
+   compute them over the exported JSON without changing the model or pretending
+   the computation was supported by the query DSL.
+6. Report the scope: context, selected source when \`$tab\` is used, query or
+   built-in view, and whether derived or projected edges were included.
+
+## Inventory a Context
+
+The built-in unfiltered view is the simplest broad logical export:
+
+\`\`\`shell
+archinsight query . -c <context-id> -v no-filter --format json
+\`\`\`
+
+Use the \`elements\` map to inventory qualified identities and types. Use
+\`edges\` for direct relationships selected by the view. Parent-based render
+groups are useful presentation metadata but do not replace element ownership in
+the linked model.
+
+For a typed inventory, narrow the query:
+
+\`\`\`cypher
+MATCH (service:Service)
+WHERE service.context = $context
+RETURN service
+\`\`\`
+
+## Direct Dependency Questions
+
+Outgoing dependencies from one service:
+
+\`\`\`cypher
+MATCH (service:Service {id: 'checkout_api', context: $context})-[dependency:REFERENCES]->(target:Element)
+RETURN service, dependency, target
+\`\`\`
+
+Incoming dependencies use the same left-to-right syntax with the target bound
+on the right:
+
+\`\`\`cypher
+MATCH (caller:Element)-[dependency:REFERENCES]->(service:Service {id: 'checkout_api', context: $context})
+RETURN caller, dependency, service
+\`\`\`
+
+These answer one-hop questions. To find all transitively affected elements,
+export the relevant context graph and traverse its direct \`REFERENCES\` edges
+outside the query language. State whether derived and projected edges were
+excluded or analyzed separately so the same dependency is not counted at
+several architectural levels.
+
+## Analyze a Source Fragment
+
+Use \`$tab\` when the question concerns the semantic fragment rooted in one
+source and its extensions:
+
+\`\`\`cypher
+MATCH (element:Element)
+WHERE element.sourceIdentity = $tab
+OPTIONAL MATCH (element)-[dependency:REFERENCES]->(target:Element)
+RETURN element, dependency, target
+\`\`\`
+
+Run it with \`--source <source.ai>\`. Explain that the result follows semantic
+source identity and can include declarations contributed through \`extend\`;
+it is not a raw inventory of lines physically present in that file.
+
+## Analyze Deployment Realization
+
+Use the built-in Deployment query JSON when the question is how logical architecture is
+realized physically:
+
+\`\`\`shell
+archinsight query . -c <context-id> -s <logical-source.ai> -v deployment --format json
+\`\`\`
+
+For each projected edge, compare outer \`source\` and \`target\` with nested
+\`edge.source\` and \`edge.target\`. Use \`edge.originSource\` and
+\`edge.originTarget\` to associate physical segments with their logical wire.
+Analyze logical wires and projected segments as separate layers; otherwise one
+dependency can appear to be several independent architectural relationships.
+
+## Quality and Impact Checks
+
+The query DSL cannot directly ask for nodes with no incoming edge, nodes with no
+outgoing edge, cycles, counts by type, or transitive consumers. Export a broad
+JSON graph, compute those conditions from qualified ids and direct edges, and
+then return to source declarations for confirmation. A selected view can omit
+objects by design, so absence in C1, C2, C3, C4, or Deployment is not evidence that the
+object is absent from the linked project.
+
+Analysis findings should distinguish verified model facts, query-dependent
+observations, externally computed results, and unresolved interpretation. Do
+not edit the architecture merely to make an analytical query easier.
+`;
+}
 function genericQueriesReference() {
   return `# Insight Query Reference
 
@@ -43177,6 +44023,7 @@ diagram.
 
 \`\`\`shell
 archinsight query . -c <context-id> -s <source.ai> -q query.aiq -f text
+archinsight query . -c <context-id> -s <source.ai> -v deployment --format json
 archinsight render . -c <context-id> -s <source.ai> -q query.aiq -f svg -o diagram.svg
 \`\`\`
 
@@ -43236,8 +44083,8 @@ RETURN service
 \`\`\`
 
 Labels are case-sensitive and match Insight types such as \`System\`,
-\`Container\`, \`Service\`, \`Component\`, \`ExternalSystem\`, and
-\`DeploymentElement\`.
+\`Container\`, \`Service\`, \`Component\`, \`CodeElement\`, \`ExternalSystem\`,
+and \`DeploymentElement\`.
 
 Use properties in patterns for exact matches:
 
@@ -43275,6 +44122,7 @@ Supported filters include:
 \`\`\`cypher
 WHERE node.context = $context
 WHERE node.sourceIdentity = $tab
+WHERE node.deployed = true
 WHERE node IS External
 WHERE NOT node IS DeploymentElement
 WHERE edge.projected = 'true'
@@ -43289,6 +44137,10 @@ Use single quotes for string literals.
 \`CONTAINS\` is case-sensitive. For scalar text it performs substring matching;
 for a list property it tests membership. Match the stored spelling exactly.
 
+\`node.deployed\` is true when an element's deployment resolves to at least one
+\`runsOn\` or \`uses\` infrastructure object. The built-in Deployment view uses it to keep
+undeployed logical elements out of the physical diagram.
+
 ## Relationship Selectors
 
 Relationship selectors are boolean flags inside relationship braces:
@@ -43299,8 +44151,78 @@ OPTIONAL MATCH (node)-[projectedLink {projected}]->(target)
 OPTIONAL MATCH ROLLUP (node)-[rollupLink {derived}]->(target)
 \`\`\`
 
-Use \`{derived}\` for rolled-up edges from child relationships. Use
-\`{projected}\` for deployment/projected edges.
+Use \`{derived}\` for relationships derived from a lower-level authored edge.
+Use \`{projected}\` for relationships created by deployment projection.
+
+\`ROLLUP\` is an operation on the match, not another selector. It walks
+containment ancestry and binds the nearest endpoint compatible with the node
+pattern. A component relationship can therefore be viewed between its
+containers or systems without adding another wire to the model. The
+relationship alias retains the underlying linked edge while its outer query
+\`source\` and \`target\` describe the endpoints selected for this view.
+
+For a projected physical path, \`ROLLUP\` can also use \`originSource\` and
+\`originTarget\` to discover path segments belonging to a logical wire. The
+built-in Deployment query uses this to include an incoming path such as
+\`customer -> CDN -> load balancer -> service\` while keeping every segment's
+real physical endpoints.
+
+Do not infer the model solely from a rolled-up arrow. Inspect query JSON to
+distinguish selected/rendered endpoints from the underlying edge and its
+logical projection origin.
+
+## Query JSON
+
+\`archinsight query --format json\` returns the semantic render graph selected
+by the query. Use it as the machine-readable check before interpreting an SVG.
+The top-level shape is:
+
+- \`context\`: selected context id;
+- \`elements\`: a map keyed by query-visible, context-qualified element id;
+- \`edges\`: selected relationships;
+- \`groups\`: render groups created by \`GROUP BY\`;
+- \`externalElements\`: selected ids drawn outside the internal boundary.
+
+Each edge contains two endpoint pairs:
+
+- outer \`source\` and \`target\` are the endpoints that the selected graph will
+  draw after rollup and grouping;
+- nested \`edge.source\` and \`edge.target\` are the endpoints of the underlying
+  linked or projected edge;
+- nested \`edge.originSource\` and \`edge.originTarget\`, when present, identify
+  the logical wire that produced a projected physical segment.
+
+An abridged response remains ordinary JSON:
+
+\`\`\`json
+{
+  "context": "shop",
+  "elements": {
+    "shop/customer": { "id": "shop/customer", "type": "ExternalActor" },
+    "eu/cloudfront": { "id": "eu/cloudfront", "type": "InfrastructureComponent" }
+  },
+  "edges": [
+    {
+      "source": "shop/customer",
+      "target": "eu/cloudfront",
+      "edge": {
+        "source": "shop/customer",
+        "target": "eu/cloudfront",
+        "originSource": "shop/customer",
+        "originTarget": "shop/web_app",
+        "projected": true
+      }
+    }
+  ],
+  "groups": [],
+  "externalElements": ["shop/customer"]
+}
+\`\`\`
+
+For an unrolled physical deployment segment, the outer and nested endpoints should
+normally agree. A deliberate ownership rollup may make them differ. An edge is
+unexpected only after its outer endpoints, underlying edge, projection origin,
+and query clause have all been checked.
 
 ## Grouping
 
@@ -43336,7 +44258,7 @@ 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
+examples/builtin-views/deployment.aiq
 \`\`\`
 
 C1 usually selects systems in the selected context and rolls lower-level links
@@ -43348,8 +44270,9 @@ relationships, and includes external systems through optional/rollup matches.
 C3 usually starts from \`(container:ContainerElement)-[:CONTAINS]->(component)\`
 and returns component relationships.
 
-C4 usually selects deployment and container nodes from \`$tab\`, uses
-\`OPTIONAL MATCH ROLLUP\`, and returns projected relationships.
+Deployment selects deployment nodes and physically deployed logical nodes from \`$tab\`,
+uses \`OPTIONAL MATCH ROLLUP\`, and returns projected relationships rather than
+their raw logical wires.
 
 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
@@ -43368,9 +44291,9 @@ the filter or grouping deliberately.
 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.
+Use this reference when a built-in C1, C2, C3, C4, or Deployment view is close but not quite right:
+an expected element is hidden, a relationship is missing, an unexpected edge
+appears, infrastructure is too noisy, or the diagram needs a different scope.
 
 ## Start From Built-In Queries
 
@@ -43381,7 +44304,7 @@ 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
+examples/builtin-views/deployment.aiq
 \`\`\`
 
 Before inventing a query from scratch, open the nearest built-in query, copy it
@@ -43389,6 +44312,7 @@ to the project, and make the smallest change.
 
 \`\`\`shell
 archinsight query . -c <context-id> -s <source.ai> -q queries/custom.aiq -f text
+archinsight query . -c <context-id> -s <source.ai> -q queries/custom.aiq -f json
 archinsight render . -c <context-id> -s <source.ai> -q queries/custom.aiq -f svg -o custom.svg
 \`\`\`
 
@@ -43399,9 +44323,11 @@ customization patterns.
 
 Write or adjust a \`.aiq\` query when:
 
-- the built-in view hides a node or edge that exists in \`archinsight link\`;
+- the built-in view hides a node or edge visible in the linked graph through a
+  broader query;
+- the built-in query returns a node or edge outside the intended view scope;
 - the source/tab scope is right but the view intentionally filters out a type;
-- C4 should include actors, vendors, or a special deployment path;
+- Deployment 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\`.
 
@@ -43426,7 +44352,7 @@ When the graph is right but the picture is noisy:
 Do not duplicate infrastructure or invert dependencies only to make one render
 look cleaner.
 
-## Diagnose A Missing Element
+## Diagnose Missing Content
 
 1. Validate the model:
 
@@ -43440,10 +44366,10 @@ archinsight link . --format text
 archinsight structure . --format text
 \`\`\`
 
-3. Run the built-in query text explicitly:
+3. Run the built-in query explicitly and inspect its JSON:
 
 \`\`\`shell
-archinsight query . -c <context-id> -s <source.ai> -q examples/builtin-views/c4.aiq -f text
+archinsight query . -c <context-id> -s <source.ai> -q examples/builtin-views/deployment.aiq -f json
 \`\`\`
 
 4. Check the query filters:
@@ -43451,54 +44377,63 @@ archinsight query . -c <context-id> -s <source.ai> -q examples/builtin-views/c4.
 - \`node.sourceIdentity = $tab\` selects the semantic fragment rooted in the
   selected source, including contributions added to those roots through
   \`extend\` in other files.
-- The built-in C4 node filter includes deployment elements, container elements,
-  and elements whose resolved \`kind\` is \`external\`. Internal actors and other
-  logical element families remain outside the view unless a custom query adds
-  them.
+- The built-in Deployment node filter includes deployment elements and logical
+  container or external elements whose deployment resolves to physical
+  infrastructure. External endpoints without their own placement still enter
+  through projected paths attached to a deployed logical node.
 - \`{projected}\` means only deployment-projected edges are selected.
 - \`{derived}\` means only rolled-up relationships are selected.
 - A relationship property such as \`sourceIdentity: $tab\` is available for a
-  deliberately narrow custom view. The current built-in C4 query does not add
+  deliberately narrow custom view. The current built-in Deployment query does not add
   that edge filter; the selected node scope and semantic tab closure provide
   the boundary.
-- The built-in C4 view also returns target-side incoming projection aliases:
-  \`incomingProjectedLink\`, \`incomingProjectedSource\`,
-  \`incomingProjectedOriginLink\`, and \`incomingProjectedOrigin\`. Keep them when
-  the target system owns an ingress gateway.
+- The built-in Deployment view also returns the target-side incoming projection aliases
+  \`incomingProjectedLink\` and \`incomingProjectedSource\`. The rollup match uses
+  projection origin metadata to find every ingress segment while preserving
+  the real physical endpoints of each segment.
+
+## Diagnose Unexpected Content
+
+Do not start by deleting model declarations when a view contains an unexpected
+node or edge.
+
+1. Run \`archinsight link . --format text\` to separate linker errors from view
+   behavior.
+2. Run the exact built-in or custom query with \`--format json\`.
+3. Find the edge in \`edges\` and compare:
+   - outer \`source\` / \`target\`, which are drawn by the selected graph;
+   - nested \`edge.source\` / \`edge.target\`, which belong to the underlying
+     linked or projected edge;
+   - \`edge.originSource\` / \`edge.originTarget\`, which identify the logical
+     wire behind a projection;
+   - \`edge.projected\` and the clause that returned its alias.
+4. Run the nearest built-in query unchanged. If only the custom query returns
+   the edge, fix the custom query. If the built-in query returns it too, reduce
+   the query to the responsible \`MATCH\` clause and report a query/runtime bug.
+5. Render only after the JSON result is understood. If JSON is correct and SVG
+   is not, investigate the renderer or layout instead of changing the model.
+
+\`ROLLUP\` can intentionally select ancestor endpoints for an ownership-level
+view. That is not a new model wire. A physical deployment segment, however, must retain
+its actual physical endpoints; projection origin metadata is for discovery and
+traceability, not for inventing a direct physical connection.
+
+## Include Internal Actors In Deployment
+
+The built-in Deployment query includes external actors reached by a projected physical
+path. If a deployment diagram also needs internal actors, use the bundled,
+tested customization:
 
-## Include Internal Actors In C4
-
-The built-in C4 query already includes external actors when they enter its
-selected scope, because they satisfy \`node IS External\`. If a deployment
-diagram also needs an internal actor, 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}]->(projectedTarget:Element)
-WHERE projectedTarget IS DeploymentElement
-   OR projectedTarget IS ContainerElement
-   OR projectedTarget IS External
-   OR projectedTarget IS Actor
-OPTIONAL MATCH (node)-[directDeploymentLink]->(directDeploymentTarget:Element)
-WHERE node IS DeploymentElement
-  AND (directDeploymentTarget IS DeploymentElement OR directDeploymentTarget IS External)
-OPTIONAL MATCH (incomingProjectedSource:Element)-[incomingProjectedLink {projected}]->(node)
-WHERE (incomingProjectedSource IS DeploymentElement
-   OR incomingProjectedSource IS ContainerElement
-   OR incomingProjectedSource IS External)
-  AND incomingProjectedSource.id <> node.id
-OPTIONAL MATCH ROLLUP (incomingProjectedOrigin:Element)-[incomingProjectedOriginLink {projected}]->(incomingProjectedSource)
-WHERE (incomingProjectedOrigin IS DeploymentElement
-   OR incomingProjectedOrigin IS ContainerElement
-   OR incomingProjectedOrigin IS External)
-  AND incomingProjectedOrigin.id <> incomingProjectedSource.id
-GROUP BY node.runsOn
-RETURN node, projectedLink, projectedTarget, directDeploymentLink, directDeploymentTarget, incomingProjectedLink, incomingProjectedSource, incomingProjectedOriginLink, incomingProjectedOrigin
+\`\`\`shell
+archinsight query . -c <context-id> -s <source.ai> -q examples/queries/deployment-internal-actors.aiq -f json
 \`\`\`
 
+This query is generated from the exact built-in Deployment source and changes only the
+node, projected-target, and incoming-source predicates to admit \`Actor\`.
+Because the rest comes from the current built-in query, deployment targets,
+incoming paths, and infrastructure-to-infrastructure projected path segments
+stay synchronized with Deployment behavior.
+
 If the actor is declared in another source file, either render from that source
 or relax the \`node.sourceIdentity = $tab\` condition intentionally.
 
@@ -43519,7 +44454,7 @@ This is useful for event-stream, broker, queue, or notification diagrams. Add
 
 ## Hide Deployment Infrastructure
 
-When a C4-oriented source file is too noisy and you only need logical containers
+When a deployment-oriented source file is too noisy and you only need logical containers
 or services, select logical container elements and direct logical relationships:
 
 \`\`\`cypher
@@ -43530,59 +44465,43 @@ GROUP BY node.parent
 RETURN node, link, target
 \`\`\`
 
-This is intentionally closer to C2 than C4. Use it when deployment annotations
+This is intentionally closer to C2 than the Deployment view. Use it when deployment annotations
 exist in the file but the diagram question is still logical.
 
 ## Projected Edges Across Split Files
 
-The current built-in C4 query matches \`{projected}\` edges without an explicit
+The current built-in Deployment query matches \`{projected}\` edges without an explicit
 \`sourceIdentity: $tab\` relationship filter. The query engine expands \`$tab\`
 to the roots declared by the selected source and contributions made to those
 roots through \`extend\`, so a normal multi-file split does not require a looser
 edge selector.
 
 If a project has a custom query copied from an older template, remove the edge
-filter while keeping the node scope:
+filter while keeping the node scope. Start again from the bundled current query
+instead of preserving the rest of the older copy:
 
-\`\`\`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]->(directDeploymentTarget:Element)
-WHERE node IS DeploymentElement
-  AND (directDeploymentTarget IS DeploymentElement OR directDeploymentTarget IS External)
-GROUP BY node.runsOn
-RETURN node, projectedLink, projectedTarget, directDeploymentLink, directDeploymentTarget
+\`\`\`text
+copy examples/builtin-views/deployment.aiq to the project's query directory
+remove sourceIdentity: $tab only from the relationship selector if an old copy has it
+keep node.sourceIdentity = $tab
 \`\`\`
 
-Validate the result with \`archinsight query\`. If a path is still absent, check
-that its logical relationship contributes to a root selected by the tab before
-changing the model or broadening the node scope.
+Validate the result with \`archinsight query ... --format json\`. If a path is
+still absent, check that its logical relationship contributes to a root selected
+by the tab before changing the model or broadening the node scope.
 
 ## Change Grouping
 
-Grouping controls visual clusters. If C4 grouping by \`runsOn\` is not helpful,
-try grouping by parent:
+Grouping controls visual clusters. If Deployment grouping by \`runsOn\` is not helpful,
+copy the complete current \`examples/builtin-views/deployment.aiq\` and change only:
 
 \`\`\`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
 GROUP BY node.parent
-RETURN node, projectedLink, projectedTarget
 \`\`\`
 
 Use \`GROUP BY node.runsOn\` for deployment placement; use \`GROUP BY node.parent\`
 for logical ownership. If you still need target-owned ingress paths, start from
-\`examples/builtin-views/c4.aiq\` and change only the \`GROUP BY\` expression so
+\`examples/builtin-views/deployment.aiq\` and change only the \`GROUP BY\` expression so
 the incoming projection aliases stay in the \`RETURN\`.
 
 ## Working Rule
@@ -43853,7 +44772,53 @@ system storefront
                     description = Consumes checkout completion events
 `;
 }
-function genericC4DeploymentFrameworkExample() {
+function genericC4CodeExampleFiles() {
+  return [
+    {
+      path: "examples/c4-code/definitions.ai",
+      content: `define type Module of CodeElement
+    constructor module
+
+    required Text name
+    Text responsibility
+    List of Wire links
+    List of CodeElement children
+
+extend type Component
+    List of CodeElement _
+`
+    },
+    {
+      path: "examples/c4-code/model.ai",
+      content: `context code_sample
+
+system application
+    name = Application
+
+    service checkout
+        name = Checkout
+
+        component order_processing
+            name = Order processing
+            responsibility = Coordinates checkout
+            module controller
+                name = Checkout controller
+                responsibility = Accepts checkout commands
+                links:
+                    -> domain
+
+            module domain
+                name = Checkout domain
+                responsibility = Applies checkout rules
+                children:
+                    module validation
+                        name = Order validation
+                        responsibility = Validates checkout input
+`
+    }
+  ];
+}
+function genericDeploymentFrameworkExample() {
   return `define type ApplicationEnvironment of Environment
     ServiceProvider cloud
     Compute compute
@@ -43879,7 +44844,7 @@ define type Monitoring of InfrastructureComponent
     required InfrastructureComponent display
 `;
 }
-function genericC4DeploymentInfrastructureExample() {
+function genericDeploymentInfrastructureExample() {
   return `environment eu
     name = Europe
 
@@ -43951,7 +44916,7 @@ deployment production
                 target $this connectTo target display
 `;
 }
-function genericC4DeploymentExample() {
+function genericDeploymentExample() {
   return `context deployment_shop
     name = Deployment Shop
 
@@ -44006,10 +44971,10 @@ system storefront
                     uses egress
 `;
 }
-function genericC4PrivateGatewayExampleFiles() {
+function genericDeploymentPrivateGatewayExampleFiles() {
   return [
     {
-      path: "examples/c4-private-gateway/deployment-framework.ai",
+      path: "examples/deployment-private-gateway/deployment-framework.ai",
       content: `define type PrivateGateway of NetworkConnection
     constructor privateGateway
 
@@ -44023,7 +44988,7 @@ define type PrivateGatewayEnvironment of Environment
 `
     },
     {
-      path: "examples/c4-private-gateway/source-infra.ai",
+      path: "examples/deployment-private-gateway/source-infra.ai",
       content: `environment source_env
     name = Source Environment
 
@@ -44038,7 +45003,7 @@ deployment production
 `
     },
     {
-      path: "examples/c4-private-gateway/target-infra.ai",
+      path: "examples/deployment-private-gateway/target-infra.ai",
       content: `environment target_env
     name = Target Environment
 
@@ -44055,7 +45020,7 @@ deployment production
 `
     },
     {
-      path: "examples/c4-private-gateway/source-system.ai",
+      path: "examples/deployment-private-gateway/source-system.ai",
       content: `context services
 
 import target from context services
@@ -44087,7 +45052,7 @@ system source_system
 `
     },
     {
-      path: "examples/c4-private-gateway/target-system.ai",
+      path: "examples/deployment-private-gateway/target-system.ai",
       content: `context services
 
 deploymentProfile target_profile
@@ -44106,7 +45071,7 @@ system target_system
 `
     },
     {
-      path: "examples/c4-private-gateway/external.ai",
+      path: "examples/deployment-private-gateway/external.ai",
       content: `context external
 
 external system payment