@archinsight/cli 3.0.0-snapshot.5 → 3.0.0-snapshot.7

package/build/index.js

@@ -57,7 +57,7 @@ var require_archy = __commonJS({
 
 // src/index.ts
 var import_archy = __toESM(require_archy(), 1);
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { instance } from "@viz-js/viz";
 
@@ -34184,6 +34184,7 @@ function linkProject(request) {
           sourceIdentity: edge.sourceName,
           fromId: edge.source,
           toId: target.id,
+          projectedAttributes: materialized.edge.attributes,
           ...materialized.edge.annotations === void 0 ? {} : { annotations: materialized.edge.annotations }
         });
         pendingProjections.push({
@@ -34191,6 +34192,7 @@ function linkProject(request) {
           fromId: edge.source,
           toId: target.id,
           attributes: edgeAttributes,
+          projectedAttributes: materialized.edge.attributes,
           ...materialized.edge.annotations === void 0 ? {} : { annotations: materialized.edge.annotations }
         });
       }
@@ -34220,7 +34222,7 @@ function linkProject(request) {
     });
   }
   for (const projection of pendingProjections) {
-    addProjectedEdges(linkedEdges, projection.sourceIdentity, projection.fromId, projection.toId, projection.attributes, linkedElementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, void 0, projection.annotations);
+    addProjectedEdges(linkedEdges, projection.sourceIdentity, projection.fromId, projection.toId, projection.attributes, linkedElementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, void 0, projection.annotations, projection.projectedAttributes);
   }
   const slotDomainTypes = typeSystem.slotDomainTypes();
   for (const element of elements) {
@@ -35248,7 +35250,14 @@ function resolveAttributes(owner, ownerType, attributes2, referenceAttributePosi
         });
         continue;
       }
-      result[name] = [...result[name] ?? [], { id: resolved.id, element: resolved }];
+      result[name] = [...result[name] ?? [], {
+        id: resolved.id,
+        element: resolved,
+        line: value.line,
+        column: value.column,
+        ...value.endLine === void 0 ? {} : { endLine: value.endLine },
+        ...value.endColumn === void 0 ? {} : { endColumn: value.endColumn }
+      }];
     }
   }
   return result;
@@ -35284,7 +35293,7 @@ function flattenAttributes(scalarAttributes, attributes2) {
     ...Object.fromEntries(Object.entries(attributes2).map(([name, values]) => [name, values.map((value) => value.id)]))
   };
 }
-function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes2, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = [], visitedProjectionElements = /* @__PURE__ */ new Set()) {
+function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes2, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = [], projectedAttributes, visitedProjectionElements = /* @__PURE__ */ new Set()) {
   for (const values of Object.values(attributes2)) {
     for (const value of values) {
       if (value.element === void 0) {
@@ -35301,8 +35310,24 @@ function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes
       if (isDirectSlotReferenceSelfProjection(value.element, fromId, toId)) {
         continue;
       }
-      for (const rule3 of typeSystem.projectionRules(value.element.type)) {
-        addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, value.element, rule3, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2);
+      const rules = typeSystem.projectionRules(value.element.type);
+      if (fromId === toId && rules.some(projectionRuleUsesTo)) {
+        const position3 = value.line === void 0 || value.column === void 0 ? value.element : {
+          line: value.line,
+          column: value.column,
+          ...value.endLine === void 0 ? {} : { endLine: value.endLine },
+          ...value.endColumn === void 0 ? {} : { endColumn: value.endColumn }
+        };
+        diagnostics.push({
+          code: "PROJECTION_TARGET_REQUIRED",
+          message: `Projection for '${value.element.type}' uses '$to' and must be attached to a relationship, not to element '${fromId}'`,
+          sourceName: sourceIdentity,
+          ...diagnosticPosition2(position3)
+        });
+        continue;
+      }
+      for (const rule3 of rules) {
+        addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, value.element, rule3, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2, projectedAttributes);
       }
       addProjectedEdges(
         linkedEdges,
@@ -35317,12 +35342,13 @@ function addProjectedEdges(linkedEdges, sourceIdentity, fromId, toId, attributes
         diagnostics,
         projectionScope,
         annotations2,
+        void 0,
         visitedProjectionElements
       );
     }
   }
 }
-function addProjectedEdgesForValues(linkedEdges, sourceIdentity, fromId, toId, values, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = []) {
+function addProjectedEdgesForValues(linkedEdges, sourceIdentity, fromId, toId, values, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = [], projectedAttributes) {
   addProjectedEdges(
     linkedEdges,
     sourceIdentity,
@@ -35335,7 +35361,8 @@ function addProjectedEdgesForValues(linkedEdges, sourceIdentity, fromId, toId, v
     typeSystem,
     diagnostics,
     projectionScope,
-    annotations2
+    annotations2,
+    projectedAttributes
   );
 }
 function addEdgeScopes(scopesByCarrierId, attributes2, scope) {
@@ -35352,15 +35379,16 @@ function addEdgeScopes(scopesByCarrierId, attributes2, scope) {
 function isDirectSlotReferenceSelfProjection(element, fromId, toId) {
   return fromId === toId && element.parent === fromId && element.scalarAttributes.parentType !== void 0 && element.scalarAttributes.attributeName !== void 0;
 }
-function addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, projectionElement, rule3, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = []) {
+function addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, projectionElement, rule3, elementsById, resolvedElementAttributes, ownerIndependentProjectionKeys, typeSystem, diagnostics, projectionScope, annotations2 = [], projectedAttributes) {
   const sources = projectionTerm(rule3.source, fromId, toId, projectionElement, elementsById, resolvedElementAttributes, diagnostics);
   const targets = projectionTerm(rule3.target, fromId, toId, projectionElement, elementsById, resolvedElementAttributes, diagnostics);
+  const carriedAttributes = rule3.source.kind === "from" ? projectedAttributes : void 0;
   for (const source of sources) {
     for (const target of targets) {
       if (!projectionRuleUsesOwner(rule3)) {
         const key = `${projectionElement.id}\0${source}\0${rule3.operator}\0${target}`;
         if (ownerIndependentProjectionKeys.has(key)) {
-          mergeProjectedEdgeAnnotations(linkedEdges, source, rule3.operator, target, annotations2);
+          mergeProjectedEdge(linkedEdges, source, rule3.operator, target, annotations2, carriedAttributes);
           continue;
         }
         ownerIndependentProjectionKeys.add(key);
@@ -35375,6 +35403,7 @@ function addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, project
         if (edge !== void 0) {
           linkedEdges[existingIndex] = {
             ...edge,
+            attributes: mergeAttributeValues(carriedAttributes, edge.attributes),
             annotations: uniqueAnnotations([...edge.annotations ?? [], ...annotations2])
           };
         }
@@ -35388,7 +35417,7 @@ function addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, project
         operator: rule3.operator,
         type,
         sourceIdentity,
-        attributes: {},
+        attributes: carriedAttributes ?? {},
         ...listAttributesProperty(typeSystem, type),
         projected: true,
         ...projectionScope === void 0 ? {} : { projectionScope },
@@ -35397,8 +35426,8 @@ function addProjectedRuleEdge(linkedEdges, sourceIdentity, fromId, toId, project
     }
   }
 }
-function mergeProjectedEdgeAnnotations(linkedEdges, source, operator, target, annotations2) {
-  if (annotations2.length === 0) {
+function mergeProjectedEdge(linkedEdges, source, operator, target, annotations2, attributes2) {
+  if (annotations2.length === 0 && (attributes2 === void 0 || Object.keys(attributes2).length === 0)) {
     return;
   }
   const index = linkedEdges.findIndex((edge2) => edge2.projected === true && edge2.source === source && edge2.operator === operator && edge2.target === target);
@@ -35411,9 +35440,19 @@ function mergeProjectedEdgeAnnotations(linkedEdges, source, operator, target, an
   }
   linkedEdges[index] = {
     ...edge,
+    attributes: mergeAttributeValues(attributes2, edge.attributes),
     annotations: uniqueAnnotations([...edge.annotations ?? [], ...annotations2])
   };
 }
+function mergeAttributeValues(base, override) {
+  if (base === void 0 || Object.keys(base).length === 0) {
+    return override;
+  }
+  if (Object.keys(override).length === 0) {
+    return base;
+  }
+  return { ...base, ...override };
+}
 function uniqueAnnotations(annotations2) {
   const seen = /* @__PURE__ */ new Set();
   const result = [];
@@ -35438,6 +35477,12 @@ function referenceAttributesProperty(attributes2) {
 function projectionRuleUsesOwner(rule3) {
   return projectionTermUsesOwner(rule3.source) || projectionTermUsesOwner(rule3.target);
 }
+function projectionRuleUsesTo(rule3) {
+  return projectionTermUsesTo(rule3.source) || projectionTermUsesTo(rule3.target);
+}
+function projectionTermUsesTo(term) {
+  return term.kind === "to";
+}
 function projectionTermUsesOwner(term) {
   return term.kind === "from" || term.kind === "to" || term.kind === "slot";
 }
@@ -36029,7 +36074,8 @@ function applyDeploymentUsesCarrier(carrier, parent, context) {
       context.typeSystem,
       context.diagnostics,
       projectionScope,
-      annotations2
+      annotations2,
+      scope.projectedAttributes
     );
   }
 }
@@ -37802,7 +37848,7 @@ var QueryParser = class {
 };
 
 // src/version.ts
-var version = "3.0.0-snapshot.5";
+var version = "3.0.0-snapshot.7";
 
 // src/index.ts
 var hiddenStructureTypes = /* @__PURE__ */ new Set(["List", "Nothing", "Text", "text"]);
@@ -37995,11 +38041,24 @@ async function runSkillInit(args, skillPackage) {
   const projectRoot = path.resolve(projectPath(args));
   const usesDefaultOutput = args.output === void 0;
   const outputRoot = path.resolve(projectRoot, args.output ?? skillPackage.defaultOutput);
+  if (args.force && await exists(outputRoot)) {
+    assertSafeSkillOutputRoot(projectRoot, outputRoot);
+    await rm(outputRoot, { recursive: true, force: true });
+  }
   for (const file of skillPackage.files) {
     await writeGeneratedFile(path.join(outputRoot, file.path), file.content, args.force);
   }
   process.stdout.write(skillPackageSuccess(projectRoot, outputRoot, skillPackage, usesDefaultOutput));
 }
+function assertSafeSkillOutputRoot(projectRoot, outputRoot) {
+  if (outputRoot === path.parse(outputRoot).root || outputRoot === process.cwd() || outputRoot === projectRoot) {
+    throw new CliError(`Refusing to delete unsafe skill output directory '${outputRoot}'. Choose a dedicated --out directory.`);
+  }
+  const projectRelativeToOutput = path.relative(outputRoot, projectRoot);
+  if (projectRelativeToOutput !== "" && !projectRelativeToOutput.startsWith("..") && !path.isAbsolute(projectRelativeToOutput)) {
+    throw new CliError(`Refusing to delete skill output directory '${outputRoot}' because it contains the project root.`);
+  }
+}
 async function loadProject(input) {
   const root = path.resolve(input);
   const sources = await readSources(root);
@@ -38452,7 +38511,7 @@ Options:
   -o, --out <file>         Write output to file instead of stdout; for skill init, write the guide directory.
   -t, --theme <theme>      Render theme, default: light.
       --target <target>    Skill target: generic, codex, or claude.
-      --force              Replace existing generated skill files.
+      --force              Delete and recreate the generated skill directory.
   -V, --version            Print version.
   -h, --help               Show help.
 
@@ -38539,6 +38598,10 @@ function sharedSkillFiles() {
       path: "references/c4-deployment.md",
       content: genericC4DeploymentReference()
     },
+    {
+      path: "references/scaling.md",
+      content: genericScalingReference()
+    },
     {
       path: "references/project-structure.md",
       content: genericProjectStructureReference()
@@ -38555,6 +38618,10 @@ function sharedSkillFiles() {
       path: "references/queries.md",
       content: genericQueriesReference()
     },
+    {
+      path: "references/query-recipes.md",
+      content: genericQueryRecipesReference()
+    },
     {
       path: "examples/layered-architecture.ai",
       content: genericLayeredArchitectureExample()
@@ -38583,6 +38650,26 @@ function sharedSkillFiles() {
       path: "examples/c2-containers.aiq",
       content: genericC2QueryExample()
     },
+    {
+      path: "examples/builtin-views/no-filter.aiq",
+      content: noFilterQuery
+    },
+    {
+      path: "examples/builtin-views/c1.aiq",
+      content: c1Query
+    },
+    {
+      path: "examples/builtin-views/c2.aiq",
+      content: c2Query
+    },
+    {
+      path: "examples/builtin-views/c3.aiq",
+      content: c3Query
+    },
+    {
+      path: "examples/builtin-views/c4.aiq",
+      content: c4Query
+    },
     ...coreSkillFiles()
   ];
 }
@@ -38645,8 +38732,18 @@ If \`archinsight\` is not available, ask the user to install or expose
 2. Preserve indentation and the project's existing naming style.
 3. Model architecture from the outside inward: context, external actors/systems,
    systems, containers/services, components, and deployment details.
-4. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
-5. Validate every Insight change with \`archinsight link . --format text\`.
+4. 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.
+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/framework files separate from model files that declare
+   \`context <id>\`.
+9. Validate every Insight change with \`archinsight link . --format text\`.
 
 ## References
 
@@ -38664,12 +38761,16 @@ If \`archinsight\` is not available, ask the user to install or expose
 - Read \`references/c4-deployment.md\` when adding or repairing deployment/C4
   models, infrastructure inventories, environment-scoped infrastructure, or
   projection rules.
+- Read \`references/scaling.md\` when splitting a repository into reusable
+  framework, environment, profile, system, or deployment-view files.
 - Read \`references/project-structure.md\` before searching for declarations,
   planning imports, or making broad edits.
 - Read \`references/core.md\` and \`.core/*.ai\` when checking built-in types,
   attributes, presentations, or projections.
 - Read \`references/queries.md\` when writing custom diagram queries or \`.aiq\`
   files.
+- Read \`references/query-recipes.md\` when a built-in view hides an expected
+  element/edge or needs customization.
 - Read \`references/validation.md\` before running checks, structure inspection,
   or rendering.
 - Use \`examples/layered-architecture.ai\` as a compact valid model.
@@ -38706,12 +38807,16 @@ Treat this \`SKILL.md\` as the entrypoint. Load reference files only when needed
 - 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.
 
@@ -38738,11 +38843,21 @@ If \`archinsight\` is not available, ask the user to install or expose
 2. Preserve indentation and the project's existing naming style.
 3. Model architecture from the outside inward: context, external actors/systems,
    systems, containers/services, components, and deployment details.
-4. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
-5. Use \`archinsight structure . --format text\` before broad edits when the
+4. 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.
+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/framework files separate from model files that declare
+   \`context <id>\`.
+9. Use \`archinsight structure . --format text\` before broad edits when the
    project shape is unclear.
-6. Validate every Insight change with \`archinsight link . --format text\`.
-7. If validation fails, fix the first real syntax/type/linking error before
+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.
 
 ## References
@@ -38761,12 +38876,16 @@ If \`archinsight\` is not available, ask the user to install or expose
 - 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.
@@ -38804,12 +38923,16 @@ they are needed:
 - 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.
 
@@ -38836,12 +38959,22 @@ install or expose \`@archinsight/cli\` before changing \`.ai\` files.
 2. Preserve indentation and the project's existing naming style.
 3. Model architecture from the outside inward: context, external actors/systems,
    systems, containers/services, components, and deployment details.
-4. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
-5. Use \`archinsight structure . --format text\` to inspect the current model
+4. 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.
+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/framework files separate from model files that declare
+   \`context <id>\`.
+9. Use \`archinsight structure . --format text\` to inspect the current model
    before broad edits when the CLI is available.
-6. Validate every Insight change with \`archinsight link . --format text\` when
+10. Validate every Insight change with \`archinsight link . --format text\` when
    shell access is available; otherwise ask the user to run validation.
-7. If validation fails, fix the first real syntax/type/linking error before
+11. If validation fails, fix the first real syntax/type/linking error before
    adding more model content.
 
 ## Communication
@@ -38879,12 +39012,16 @@ sections of Insight unless the existing layering is already understood.
 - 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.
@@ -38906,6 +39043,40 @@ function genericModelingReference() {
 Insight syntax is small; most mistakes are modeling mistakes. Decide the view
 question before changing files.
 
+## Separate Definitions From Model Sources
+
+Keep language/framework definitions separate from graph model files.
+
+- Definition/framework files contain \`define type\`, \`define operator\`,
+  \`define presentation\`, \`extend type\`, \`extend enum of\`, and
+  \`extend presentation\`.
+- Model files declare \`context <id>\` and create graph objects with
+  constructors such as \`system\`, \`service\`, \`component\`, \`environment\`,
+  or \`deploymentProfile\`.
+
+Do not mix definition declarations and \`context\` declarations in one source
+file. Put shared vocabulary in a framework file, then put concrete contexts,
+systems, environments, profiles, and links in model files. This keeps schema
+changes reviewable and avoids source-level syntax failures.
+
+## Model Source Granularity
+
+Default to one primary owned system per model source file: the system you are
+about to detail with containers, services, components, and deployment
+relationships. This keeps the selected source file useful as a C2/C3/C4 view
+scope and avoids accidental mega-files.
+
+Do not create one file per external actor or external system. Shared external
+dependencies are usually better modeled once in a reusable external context, or
+in a few external contexts grouped by meaning such as \`external_platforms\`,
+\`partners\`, or \`regulators\`. Import those shared declarations from system
+files that need them.
+
+If a user asks for deeper splitting, use \`extend <object>\` files for the
+detail being extracted. For example, keep the main service file readable and put
+large per-service component sets in a small utility subdirectory for that
+context.
+
 ## Projections Are Bottom-Up
 
 Built-in C1/C2/C3/C4 views are selected from the linked model. They are not
@@ -38969,23 +39140,50 @@ type hierarchy:
 If a nested declaration fails type checking, fix the type/ownership model rather
 than forcing a link or inventing a wrapper element.
 
-## Keep Infrastructure in the Right View
+## Choose Infrastructure Depth Per System
+
+Do not force every project into C4/deployment on the first pass. Most modeling
+work can proceed through C1-C3 without asking about deployment depth. When the
+task first touches infrastructure, runtime placement, regions, compute, brokers,
+gateways, storage, or deployment, ask the user or infer from the repository
+whether the affected system needs a pragmatic mixed C2 view or a clean
+C4/deployment model.
+
+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.
 
-Do not transcribe infrastructure into C2 just because another diagram drew it
-there. Databases, queues, secret stores, compute nodes, gateways, and runtime
-placement are usually deployment/C4 concerns unless the project defines them as
-part of the selected view.
+Clean C4 keeps C2 logical and moves physical realization into deployment
+profiles, environments, inventory slots, and projection rules. This is more work
+up front, but it supports many-to-many deployment: one logical service can run
+in several environments whose infrastructure differs by region, provider, or
+organizational boundary.
 
-Use deployment types and projection queries when physical realization matters.
+This choice is per-system, not global. A critical system can use clean C4 while
+peripheral systems stay pragmatic in C2. Starting cheap is acceptable, but know
+that upgrading mixed C2 infrastructure into clean C4 is a migration, not just an
+extra attribute.
 
 ## Eventing
 
 Use \`~>\` for asynchronous relationships. Model one async wire per meaningful
 topic or event flow between real producer and consumer elements.
 
+For pub/sub, make the dependency consumer-owned:
+
+- The producer/source declares the event topic as part of its contract, but does
+  not maintain a manual list of subscribers.
+- The consumer declares \`~> producer\` with \`via = <topic>\`, because the
+  consumer depends on the producer's event contract.
+- To answer "who depends on this event?", query the graph for incoming async
+  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
-broker is deployment infrastructure, model it in deployment/C4. If the producer
-or consumer is not known, leave a gap and report it instead of fabricating an
+chosen style is clean C4 and the broker is deployment infrastructure, model it
+in deployment/C4. If the chosen style is pragmatic mixed C2, a broker-like node
+can be acceptable, but document that the view mixes levels. If the producer or
+consumer is not known, leave a gap and report it instead of fabricating an
 element.
 
 ## No Fabricated Elements
@@ -39069,6 +39267,11 @@ Definition files are different from model files. They declare vocabulary:
 \`extend enum of\`, and \`extend presentation\`. Model files usually start with
 \`context <id>\` and then create graph object instances with constructors.
 
+Do not mix these source forms in one file. A framework/definitions file should
+contain only vocabulary/schema declarations. A model file should declare a
+\`context <id>\` and graph object instances. If both are needed, create two
+files and validate the whole project.
+
 ## Type Definitions and Extensions
 
 Use \`define type\` to create a new graph/value type. Use \`extend type\` to add
@@ -39126,10 +39329,10 @@ links:
         technology = HTTPS, JSON
         call = POST /checkout
         description = Places an order
-    ~> analytics
+    ~> order_events
         technology = Kafka
         via = orders.created
-        description = Publishes order events
+        description = Consumes order events
 \`\`\`
 
 \`call\` is singular and belongs to synchronous \`->\` links. \`via\` belongs to
@@ -39179,22 +39382,79 @@ Use \`extend type\` / \`extend presentation\` when patching existing vocabulary.
 Repeating \`define presentation X\` for an existing presentation is a diagnostic
 in current Archinsight.
 
+## Comments and Notes
+
+Use \`#\` for ordinary comments when you want to leave guidance for humans or
+agents without changing the model:
+
+\`\`\`insight
+# This file owns the checkout bounded context.
+context checkout
+
+system checkout_platform
+    # Keep logical services here; deployment inventory belongs in C4 files.
+    name = Checkout Platform
+\`\`\`
+
+A \`#\` after an element or relationship line is an inline note. Notes are
+stored in the linked graph and can be rendered as note nodes near the element or
+edge:
+
+\`\`\`insight
+context checkout
+
+system checkout_platform
+    name = Checkout Platform
+
+    container api # Public API owned by the checkout team
+        name = Checkout API
+        links:
+            -> payment_gateway # PCI-sensitive request path
+                technology = HTTPS
+                call = POST /payments
+
+external system payment_gateway
+    name = Payment gateway
+\`\`\`
+
+Use comments for authoring hints that should stay invisible in diagrams. Use
+notes for architecture remarks that should travel with the model and help
+readers understand a specific element or relationship.
+
 ## Annotations
 
-Annotations decorate the next declaration or link:
+Annotations decorate the next declaration or relationship. Put each annotation
+on its own line immediately before the target:
 
 \`\`\`insight
-@planned
-external system warehouse
-    name = Warehouse
+context fulfillment
 
-links:
-    @deprecated
-    ~> legacy_erp
+system fulfillment_platform
+    name = Fulfillment Platform
+
+    @planned
+    container fulfillment_adapter
+        name = Fulfillment adapter
+        links:
+            @deprecated(replace after ERP migration)
+            ~> legacy_erp # scheduled for removal
+
+external system legacy_erp
+    name = Legacy ERP
 \`\`\`
 
-Use presentation definitions for durable visual styling. Avoid adding new
-Graphviz attributes directly unless the project already uses that convention.
+Available annotations:
+
+- \`@planned\` marks an element or relationship as planned or not fully
+  implemented yet. The default Graphviz renderer highlights it in green.
+- \`@deprecated\` marks an element or relationship as legacy or scheduled for
+  removal. Add optional text in parentheses when the replacement or reason is
+  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
+or deprecated. Annotations cannot decorate assignments; use a comment above the
+assignment when you only need a local authoring hint.
 
 ## Presentation Syntax
 
@@ -39515,11 +39775,13 @@ at context level. Prefer capability language over endpoint trivia.
 Use \`~>\` for meaningful asynchronous context flows:
 
 \`\`\`insight
-links:
-    ~> analytics_platform
-        technology = Kafka
-        via = order.completed
-        description = Publishes completed order events
+external system analytics_platform
+    name = Analytics Platform
+    links:
+        ~> storefront
+            technology = Kafka
+            via = order.completed
+            description = Consumes completed order events from Storefront
 \`\`\`
 
 ## What Not To Put In C1
@@ -39568,6 +39830,22 @@ the selected source file, so a C2 file should usually contain the selected
 \`system <id>\` declaration or an \`extend system <id>\` block with its
 containers/services.
 
+## C2 Purity vs Pragmatic Infrastructure
+
+The clean C2 answer is logical: deployable containers/services and how they
+collaborate. In that mode, databases, brokers, gateways, vaults, compute, and
+regions belong to C4/deployment.
+
+Archinsight does not force that choice. For a quick or single-environment model,
+it is acceptable to put simple infrastructure-like runtime nodes into C2 when
+the user wants speed over strict layer separation. Be explicit about the
+tradeoff: the C2 view becomes mixed, C4 is not really modeled for that system,
+and many-to-many deployment across different environments will not be available
+until the model is migrated to clean C4.
+
+Choose this per system. Do not make the whole repository clean or mixed just
+because one system needs that style.
+
 ## C2 Workflow
 
 1. Run \`archinsight structure . --format text\` to find the exact system id,
@@ -39691,21 +39969,33 @@ Import the real declaration when it is shared.
 
 ## Async and Eventing Pattern
 
-Use \`~>\` for meaningful asynchronous relationships:
+Use \`~>\` for meaningful asynchronous dependencies. For pub/sub, declare the
+wire on the consumer, pointing at the producer/source whose topic contract it
+depends on:
 
 \`\`\`insight
-service checkout_api
-    name = Checkout API
+external system analytics_platform
+    name = Analytics Platform
+    technology = Kafka consumer
     links:
-        ~> analytics_platform
+        ~> checkout_api
             technology = Kafka
             via = checkout.completed
-            description = Publishes completed checkout events
+            description = Consumes completed checkout events
+
+service checkout_api
+    name = Checkout API
+    description = Publishes checkout.completed as an event contract
 \`\`\`
 
-Do not add a broker node just to make an event diagram look familiar. A broker
-is usually deployment/C4 infrastructure unless the project defines it as a
-runtime system or service in the selected view.
+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
+it as a runtime system or service in the selected view. In pragmatic mixed C2,
+adding a broker can be acceptable for a quick view, but it means the diagram is
+no longer strictly logical C2.
 
 ## C2 Link Details
 
@@ -39726,8 +40016,9 @@ details at C2 only when they clarify the architecture; otherwise use a plain
 ## What Not To Put In C2
 
 - Components, classes, handlers, repositories, or UI widgets.
-- Deployment nodes, pods, regions, network gateways, or secret stores unless the
-  project models them as C2 runtime systems.
+- Deployment nodes, pods, regions, network gateways, or secret stores in clean
+  C2. Include them only when the user intentionally wants pragmatic mixed C2 or
+  the project models them as C2 runtime systems.
 - Database tables and internal schemas.
 - One-off scripts or build-time tools unless they are real runtime units.
 - Duplicate links already represented at a lower C3 level unless the C2 view is
@@ -39736,7 +40027,8 @@ details at C2 only when they clarify the architecture; otherwise use a plain
 ## Common C2 Mistakes
 
 - Adding C2 nodes directly under \`context\` instead of under a \`system\`.
-- Modeling infrastructure that belongs to C4/deployment.
+- Modeling infrastructure in C2 without deciding that the system is using the
+  pragmatic mixed-C2 style.
 - Mixing C2 container/service links with C3 component links in the same source
   file without a clear view goal.
 - Forgetting \`--source <c2-file.ai>\` when rendering C2.
@@ -39909,10 +40201,6 @@ extend service inventory_api
         links:
             -> inventory_policy
             -> reservation_repository
-            ~> inventory_events
-                technology = Kafka
-                via = inventory.reserved
-                description = Publishes successful reservation events
 
     component inventory_policy
         name = Inventory policy
@@ -39924,15 +40212,21 @@ extend service inventory_api
         technology = SQL
         responsibility = Stores reservation state and idempotency keys
 
-    component inventory_events
-        name = Inventory events
-        technology = Kafka producer
-        responsibility = Publishes inventory domain events for downstream systems
+    component stock_projection
+        name = Stock projection
+        technology = Kafka consumer
+        responsibility = Maintains a stock read model from reservation events
+        links:
+            ~> reservation_service
+                technology = Kafka
+                via = inventory.reserved
+                description = Consumes successful reservation events
 \`\`\`
 
 Use \`->\` for synchronous calls and \`~>\` for asynchronous flows. Use singular
 \`call\` for the synchronous operation and \`via\` for the asynchronous topic,
-queue, or channel.
+queue, or channel. For pub/sub, put the async link on the consumer and point it
+at the producer/source whose event contract it consumes.
 
 ## Imported Boundary Pattern
 
@@ -40011,9 +40305,9 @@ Use async details for events:
 
 \`\`\`insight
 links:
-    ~> inventory_events
+    ~> reservation_service
         via = inventory.reserved
-        description = Publishes reservation completion
+        description = Consumes reservation completion events
 \`\`\`
 
 Do not add a broker as a component unless the broker is actually part of the
@@ -40056,10 +40350,13 @@ projection rules.
 ## Contents
 
 - What C4 Answers
+- Before You Use C4
 - Mental Model
 - C4 Workflow
+- C4 Decision Checklist
 - Environment Inventory
 - Why Infrastructure Is Per Environment
+- Graph Model vs Diagram Scope
 - Attaching Deployment To C1-C3 Elements
 - usesProfile, environmentsFrom, runsOn, and uses
 - Deployment Archetypes
@@ -40081,6 +40378,31 @@ C4 is not just another decomposition level. C1-C3 mostly describe logical
 architecture. C4 maps logical elements and links onto environment-local
 infrastructure inventory.
 
+## Before You Use C4
+
+C4/deployment is optional. Do not push the user into environments, projection
+rules, and infrastructure inventory when they only need a quick logical/runtime
+view.
+
+If the work has reached infrastructure, runtime placement, regions, compute, or
+deployment, ask or infer the intended style for the current system:
+
+- Pragmatic mixed C2: put simple infrastructure-like runtime nodes such as a
+  database, broker, gateway, or vault near the services in C2. This is fast and
+  easier for simple or single-environment systems, but it mixes abstraction
+  levels and does not produce a real C4 model.
+- Clean C4: keep C2 logical and describe physical realization through
+  \`Environment\` slots, deployment profiles, inventory, \`runsOn\`, \`uses\`,
+  and projection rules. This takes more design work, but supports region/env
+  differences, many-to-many deployment, and organization-specific runtime
+  complexity.
+
+The choice is per-system. Model a critical system with clean C4 and keep a
+peripheral system pragmatic in C2 if that matches the user's needs. If a system
+starts as mixed C2 and later needs multi-env deployment, expect a migration:
+infrastructure nodes must move into environment inventory and links must gain
+deployment/projection semantics.
+
 ## Mental Model
 
 There are three layers:
@@ -40148,6 +40470,23 @@ environment prod
 8. Validate with \`archinsight link . --format text\`.
 9. Render with \`archinsight render . -c <context-id> -s <c4-file.ai> -v c4 -f svg -o c4.svg\`.
 
+## C4 Decision Checklist
+
+Use this before adding a \`deployment:\` block:
+
+- Placement/grouping? Put \`runsOn compute\` on the deployed element.
+- Stateful or sidecar-like dependency? Put \`uses storage\`, \`uses observability\`,
+  or similar element-level infrastructure on the deployed element.
+- Traffic path to a target? Put \`uses network\`, \`uses publicGateway\`, or any
+  infrastructure whose projection mentions \`$to\` on the relationship under
+  \`links:\`, not on the container/service.
+- Pub/sub path? Make the async wire consumer-owned: the consumer declares
+  \`~> producer\` with \`via = <topic>\`, then attach \`uses broker\` to that wire
+  when modeling clean C4 broker infrastructure.
+- Picture too noisy? Keep the graph model correct and change source scope or
+  write a custom query. Fan-in to a shared node is normal graph reality, not a
+  modeling error by itself.
+
 ## Environment Inventory
 
 Define infrastructure vocabulary in a definition file:
@@ -40220,6 +40559,12 @@ environment prod
 specific \`prod\` environment. Another environment can fill the same slots with
 different concrete infrastructure.
 
+Object ids are still unique within a context, even when the instances live in
+different environment slots. When the exact id is not important, use anonymous
+\`_\` instances inside each environment. When you need stable ids, make them
+environment-specific, such as \`envoy_prod\` and \`envoy_staging\`, instead of
+reusing \`envoy_public\` in several environments.
+
 ## Why Infrastructure Is Per Environment
 
 Infrastructure must be per environment because deployment is many-to-many:
@@ -40236,6 +40581,14 @@ If infrastructure were modeled as global nodes, the model could not say:
 "Checkout API runs on EKS in production, Cloud Run in staging, and uses a
 different database in each environment" without duplicating logical services.
 
+## Graph Model vs Diagram Scope
+
+The linked model is a graph; a diagram is only one scoped query over that graph.
+Fan-in to one broker, gateway, load balancer, or producer is often the correct
+physical model. If the picture explodes, do not rewrite the model just to make
+the image tidy. Narrow the selected source file, add a custom \`.aiq\` query,
+group differently, or aggregate the view.
+
 ## Attaching Deployment To C1-C3 Elements
 
 \`deployment\` is available on systems, containers/services, components, and
@@ -40250,7 +40603,27 @@ Prefer C2 containers/services for most deployment mapping:
 Use C1 deployment only when the whole system is deployed as one unit. Use C3
 deployment when a component is independently deployed or has a distinct physical
 path. Use wire deployment when a specific logical relationship travels through
-infrastructure such as a public gateway, private gateway, broker, or egress path.
+infrastructure such as a public gateway, network connection, broker, or egress
+path.
+
+## Element-Level vs Wire-Level Infrastructure
+
+Attach infrastructure to an element when the projection only needs the deployed
+element itself:
+
+- \`runsOn compute\`: placement/grouping.
+- \`uses storage\`: the element depends on stateful infrastructure.
+- \`uses observability\`: monitoring sidecars or collectors around the element.
+
+Attach infrastructure to a wire when the projection needs a real target:
+
+- \`uses publicGateway\`: expands a caller-to-service path through ingress.
+- \`uses network\`: keeps a direct source-to-target network path on C4.
+- \`uses broker\`: both producer and consumer physically connect to the broker.
+
+Rule of thumb: if the infrastructure type's \`project:\` block mentions \`$to\`,
+use it on a relationship under \`links:\`. Using it on an element is invalid
+because an element deployment has no separate target endpoint.
 
 ## usesProfile, environmentsFrom, runsOn, and uses
 
@@ -40367,7 +40740,6 @@ deploymentProfile global_service
         global_edge
 
     runsOn compute
-    uses publicGateway
 
 deploymentProfile regional_service
     environments:
@@ -40384,6 +40756,11 @@ container web_app
     name = Web app
     deployment:
         usesProfile global_service
+    links:
+        -> checkout_api
+            deployment:
+                environmentsFrom global_service
+                uses publicGateway
 
 service checkout_api
     name = Checkout API
@@ -40392,18 +40769,19 @@ service checkout_api
         uses storage
 \`\`\`
 
-The profile supplies the common environment scope, placement, and standard
+The profile supplies the common environment scope, placement, and element-level
 infrastructure. Additional local \`uses\` entries extend the profile for that
 specific element. In the example, \`checkout_api\` inherits regional compute and
 observability from \`regional_service\`, then adds its own \`uses storage\`
-because this service owns persistent state.
+because this service owns persistent state. The \`web_app -> checkout_api\` wire uses
+\`environmentsFrom global_service\` to reuse the environment list while attaching
+the path-only \`publicGateway\` projection to the relationship.
 
-Use separate profiles when the default infrastructure differs. For example,
-\`public_regional_service\` can include both \`uses observability\` and
-\`uses publicGateway\`, while \`regional_worker\` may use the same environments,
-compute, and observability but omit public ingress. Put path-only infrastructure
-such as \`network\` on the wire deployment when it represents a specific
-service-to-service path.
+Use separate profiles when the element-level defaults differ. For example,
+\`regional_service\` can include \`runsOn compute\` and \`uses observability\`,
+while \`regional_stateful_service\` can also include \`uses storage\`. Keep
+path-only infrastructure such as \`publicGateway\`, \`network\`, or \`broker\`
+on the wire deployment where the source and target are known.
 
 When an element should reuse only the environments from an archetype, use
 \`environmentsFrom <profile>\` instead of \`usesProfile <profile>\` and then add
@@ -40467,6 +40845,10 @@ queries commonly select projected deployment edges; a plain logical wire without
 deployment projection may be correct in C2/C3 but absent from the deployment
 layer.
 
+If validation reports \`PROJECTION_TARGET_REQUIRED\`, you attached a projection
+that uses \`$to\` to an element. Move that \`uses ...\` entry to the relevant
+wire and reuse the element's environment scope with \`environmentsFrom\`.
+
 Projection terms:
 
 - \`$from\` is the logical source of the deployment use.
@@ -40551,7 +40933,6 @@ deploymentProfile public_regional_service
 
     runsOn compute
     uses observability
-    uses publicGateway
 
 service checkout_api
     name = Checkout API
@@ -40604,7 +40985,8 @@ logical service projects into both environments without duplicating
 - Logical components invented only to represent physical routing.
 - C3 internals unless they are independently deployed.
 - Cloud resources with no relationship to a deployment question.
-- A broker/gateway/load balancer in C2 just because it appears in deployment.
+- A broker/gateway/load balancer in C2 just because it appears in deployment,
+  unless the system intentionally uses the pragmatic mixed-C2 style.
 
 ## Common C4 Mistakes
 
@@ -40612,7 +40994,13 @@ logical service projects into both environments without duplicating
   slots for them.
 - Creating \`infrastructureComponent\` nodes at context level when they should
   live in an \`environment\` inventory slot.
+- Reusing the same concrete infrastructure id in several environments. Use
+  anonymous \`_\` instances or environment-specific ids.
 - Using \`usesProfile\` on a wire when only \`environmentsFrom\` is intended.
+- Attaching \`uses publicGateway\`, \`uses network\`, or another \`$to\`-based
+  path projection to a container/service. Move it to the specific wire.
+- Modeling pub/sub as a producer-owned subscriber list. Consumers should declare
+  \`~> producer\` with \`via = <topic>\`; use queries to list consumers.
 - Forgetting \`--source <c4-file.ai>\` when rendering C4.
 - Expecting \`runsOn\` to draw traffic; use \`project:\` rules and \`uses\` for
   traffic/path projections.
@@ -40630,6 +41018,272 @@ Use \`examples/c4-deployment-framework.ai\` and \`examples/c4-deployment.ai\` as
 a compact valid C4 model when syntax is unclear.
 `;
 }
+function genericScalingReference() {
+  return `# Scaling an Archinsight Repository
+
+Use this reference when a project grows beyond one or two files and you need to
+reuse definitions, environments, deployment profiles, or systems without
+duplicating them.
+
+## Repository Shape
+
+Prefer one shared framework per repository:
+
+- one definitions/framework area for \`extend type Environment\`, custom
+  infrastructure types, presentation tweaks, projection-capable infrastructure,
+  and reusable deployment profiles;
+- source files grouped by context directories when the repository is large;
+- model files that usually focus on one primary owned system being detailed;
+- one or more inventory files for concrete \`environment <id>\` instances and
+  their env-local infrastructure;
+- shared external contexts for external actors and systems reused by many
+  systems;
+- focused deployment-view files that attach deployment profiles and per-view
+  traffic paths.
+
+Do not copy the same \`extend type Environment\`, infra type definitions, or
+\`deploymentProfile\` blocks into every system file. Define the vocabulary and
+reusable archetypes once, import or reference them where needed, and validate the
+whole project.
+
+## Framework Once, Use Everywhere
+
+A typical deployment framework file contains only shared vocabulary: type
+definitions, type extensions, projection rules, and presentation overrides. Do
+not mix \`define type\` / \`extend type\` declarations and \`context\`
+declarations in the same source file.
+
+\`\`\`insight
+define type PublicGateway of InfrastructureComponent
+    constructor publicGateway
+    required InfrastructureComponent cdn
+    required InfrastructureComponent loadBalancer
+
+    project:
+        $from -> cdn
+        cdn -> loadBalancer
+        loadBalancer -> $this
+        $this -> $to
+
+extend type Environment
+    Compute compute
+    Storage storage
+    Broker broker
+    PublicGateway publicGateway
+    NetworkConnection network
+\`\`\`
+
+Concrete inventory/profile files then declare contexts, environments, and
+profiles:
+
+\`\`\`insight
+context infra
+    name = Shared Infrastructure
+
+environment prod_eu
+    name = Production EU
+    compute:
+        compute ecs
+            name = ECS
+            technology = AWS ECS
+    broker:
+        broker kafka
+            name = Kafka
+            technology = MSK
+            address = kafka.prod.eu.internal
+
+deploymentProfile regional_service
+    environments:
+        prod_eu
+
+    runsOn compute
+\`\`\`
+
+System files should reuse these definitions instead of recreating \`compute\`,
+\`broker\`, or profile declarations locally.
+
+## System Files and External Contexts
+
+The default model file is centered on one owned system:
+
+\`\`\`text
+commerce/
+    checkout.ai
+    catalog.ai
+    fulfillment.ai
+external/
+    platforms.ai
+    regulators.ai
+\`\`\`
+
+\`commerce/checkout.ai\` would declare \`context commerce\`, the
+\`system checkout\` focal object, and the containers/services/components needed
+to explain checkout. \`commerce/catalog.ai\` would do the same for catalog.
+
+Shared external actors and systems should not be copied into every system file.
+Put them in one external context, or a few semantically grouped external
+contexts:
+
+\`\`\`insight
+context external_platforms
+
+external system stripe
+    name = Stripe
+
+external system sendgrid
+    name = SendGrid
+\`\`\`
+
+Then import them where needed:
+
+\`\`\`insight
+context commerce
+
+import stripe from context external_platforms
+
+system checkout
+    links:
+        -> stripe from external_platforms
+\`\`\`
+
+Avoid making a separate file for every external actor or vendor unless the
+external dependency itself has substantial reusable structure. A small number of
+well-named external contexts gives all repository systems one shared vocabulary
+for outside dependencies.
+
+When a system file becomes too large, split details by extending the focal
+object in utility subdirectories:
+
+\`\`\`text
+commerce/
+    checkout.ai
+    checkout-components/
+        pricing.ai
+        payment.ai
+        inventory.ai
+\`\`\`
+
+Those files should repeat the same \`context commerce\`, explicitly import the
+object being extended when it lives in another source file, and use
+\`extend service checkout_api\`, \`extend container web_app\`, or another object
+extension to add focused details.
+
+## Same-Context Cross-File Imports
+
+Insight resolves unqualified ids in this order: declarations in the same source
+file, explicit imports in the same source file, then it reports an error if the
+same id exists only in another source file of the same context.
+
+That means splitting one context across files still requires imports:
+
+\`\`\`insight
+context services
+
+deploymentProfile eu_service
+\`\`\`
+
+\`\`\`insight
+context services
+
+import eu_service from context services
+
+system checkout
+    name = Checkout
+    deployment:
+        usesProfile eu_service
+\`\`\`
+
+This is intentional. If a file is extracted, removed, or not included in the
+project, the linker should fail with an explicit identifier/import diagnostic
+instead of silently binding to whatever remains in the context.
+
+## Inline from Context
+
+When a relationship target is declared outside the current source file, prefer
+an explicit context qualifier on the link target:
+
+\`\`\`insight
+context commerce
+
+import payments from context external_systems
+
+system checkout
+    name = Checkout
+    links:
+        -> payments from external_systems
+            technology = HTTPS
+            call = POST /payments
+\`\`\`
+
+The \`import <id> from context <context-id>\` line documents the dependency and
+makes the id available for attributes such as profiles and environment slots.
+The inline \`from <context-id>\` on a link target states which context owns the
+linked element. Use the same pattern for same-context cross-file links when the
+source has been split and ambiguity matters:
+
+\`\`\`insight
+context services
+
+import inventory_api from context services
+
+system checkout_api
+    links:
+        -> inventory_api from services
+            technology = HTTPS
+            call = GET /inventory
+\`\`\`
+
+This explicitness is useful during refactors: if the source file holding
+\`inventory_api\` disappears, validation points at the missing declaration
+instead of creating a hidden dependency on file layout.
+
+## C4 Multi-File Pattern
+
+For C4, keep these responsibilities separate:
+
+- framework file: type extensions, infra constructors, presentation/projection
+  definitions;
+- inventory/profile file: concrete environments and reusable deployment
+  profiles;
+- deployment-view file: the relationships whose deployment path you want to
+  render for one selected view.
+
+When rendering C4 with \`-s <source.ai>\`, remember that source/tab scoping is
+part of the view. Put the view-driving logical relationships in the selected
+source file, or render from the source file that owns those relationships. Keep
+imported framework and inventory reusable, but validate the rendered C4 output
+after moving traffic relationships across files:
+
+\`\`\`shell
+archinsight link . --format text
+archinsight render . -c deployment_shop -s c4-deployment.ai -v c4 -f svg -o deployment-c4.svg
+\`\`\`
+
+If projected infrastructure edges disappear after a split, first check whether
+the selected \`-s\` file still contains the source logical relationship or an
+intended imported deployment-view relationship. Do not fix that by duplicating
+infrastructure nodes; fix the source selection or the file boundary.
+
+## Practical Workflow
+
+1. Run \`archinsight structure . --format text\`.
+2. Identify contexts, source files, and declaration ids before editing.
+3. Move shared vocabulary into one framework file.
+4. Group model files by context directory when the repository is large.
+5. Keep each ordinary system file focused on one owned system being detailed.
+6. Put external actors/systems in shared external contexts, not one file per
+   external element.
+7. Move reusable environments and deployment profiles into inventory/profile
+   files.
+8. Add explicit imports for every cross-file dependency, including same-context
+   dependencies.
+9. Add inline \`from <context-id>\` on relationship targets that live outside
+   the current source file.
+10. Validate with \`archinsight link . --format text\`.
+11. Render important C1/C2/C3/C4 views with explicit \`-c\`, \`-s\`, and \`-v\`
+   options.
+`;
+}
 function genericProjectStructureReference() {
   return `# Project Structure Workflow
 
@@ -40637,6 +41291,37 @@ Use \`archinsight structure\` before broad edits, imports, or declaration lookup
 Do not start with raw grep when you need to know what the linked project
 contains.
 
+## Source File Classes
+
+Keep source files in one role:
+
+- definition/framework files: \`define type\`, \`define operator\`,
+  \`define presentation\`, \`extend type\`, \`extend enum of\`, and
+  \`extend presentation\`;
+- model files: \`context <id>\`, imports, graph object declarations,
+  relationships, environments, and deployment profiles.
+
+Do not mix definition/framework declarations with \`context <id>\` in one file.
+When a model needs custom vocabulary, add or edit a framework file first, then
+use the resulting constructors and attributes from model files.
+
+## Directory and File Granularity
+
+For larger repositories, group model files by context directory. Inside a
+context directory, default to one primary owned system per ordinary model file:
+the system that will be detailed by containers, services, components, links, and
+deployment information.
+
+External actors and systems are different. Put reusable outside dependencies in
+one external context or a few semantically grouped external contexts. Do not
+create a separate file for every external actor or vendor unless that external
+dependency has real internal structure to model.
+
+If a system needs further splitting, create a utility subdirectory for focused
+\`extend <object>\` files, such as per-service component files. Import the
+extended object explicitly when it is declared in another source file. Keep the
+main system file as the readable entry point.
+
 ## Commands
 
 Human-readable overview:
@@ -40684,6 +41369,33 @@ links:
     -> payments from external_systems
 \`\`\`
 
+Imports are also required when a declaration lives in another source file of the
+same context:
+
+\`\`\`insight
+context services
+
+import eu_service from context services
+
+system checkout_api
+    deployment:
+        usesProfile eu_service
+\`\`\`
+
+The explicit import is intentional. If the source file that declared
+\`eu_service\` is removed or excluded, validation should fail with a clear
+missing import/identifier diagnostic instead of depending on hidden file layout.
+
+For links, \`from <context-id>\` on the target is an inline context qualifier:
+
+\`\`\`insight
+links:
+    -> inventory_api from services
+\`\`\`
+
+Use it when the relationship target is owned by another context or another
+source file whose context ownership should remain visible at the call site.
+
 Do not guess context ids from filenames. Filenames, context ids, and element ids
 can differ.
 
@@ -41141,6 +41853,16 @@ diagram needs stable layout.
 
 ## Built-In View Patterns
 
+Exact built-in query sources are bundled in:
+
+\`\`\`text
+examples/builtin-views/no-filter.aiq
+examples/builtin-views/c1.aiq
+examples/builtin-views/c2.aiq
+examples/builtin-views/c3.aiq
+examples/builtin-views/c4.aiq
+\`\`\`
+
 C1 usually selects systems in the selected context and rolls lower-level links
 up to system-level relationships.
 
@@ -41153,6 +41875,10 @@ and returns component relationships.
 C4 usually selects deployment and container nodes from \`$tab\`, uses
 \`OPTIONAL MATCH ROLLUP\`, and returns projected relationships.
 
+When a built-in view is close but hides the wrong thing, read
+\`references/query-recipes.md\`, copy the nearest built-in \`.aiq\`, and change
+the filter or grouping deliberately.
+
 ## Authoring Rules
 
 - Start from the view question: context, containers, components, or deployment.
@@ -41163,6 +41889,207 @@ C4 usually selects deployment and container nodes from \`$tab\`, uses
 - Keep custom queries in \`.aiq\` files when they are reused.
 `;
 }
+function genericQueryRecipesReference() {
+  return `# Query Recipes and Built-In View Customization
+
+Use this reference when a built-in C1/C2/C3/C4 view is close but not quite right:
+an expected element is hidden, a relationship is missing, infrastructure is too
+noisy, or the diagram needs a different scope.
+
+## Start From Built-In Queries
+
+The generated skill includes exact built-in view queries:
+
+\`\`\`text
+examples/builtin-views/no-filter.aiq
+examples/builtin-views/c1.aiq
+examples/builtin-views/c2.aiq
+examples/builtin-views/c3.aiq
+examples/builtin-views/c4.aiq
+\`\`\`
+
+Before inventing a query from scratch, open the nearest built-in query, copy it
+to the project, and make the smallest change.
+
+\`\`\`shell
+archinsight query . -c <context-id> -s <source.ai> -q queries/custom.aiq -f text
+archinsight render . -c <context-id> -s <source.ai> -q queries/custom.aiq -f svg -o custom.svg
+\`\`\`
+
+Use \`references/queries.md\` for syntax details. Use this file for common
+customization patterns.
+
+## When To Customize
+
+Write or adjust a \`.aiq\` query when:
+
+- the built-in view hides a node or edge that exists in \`archinsight link\`;
+- the source/tab scope is right but the view intentionally filters out a type;
+- C4 should include actors, vendors, or a special deployment path;
+- the diagram should show only one layer, one flow, or one relationship class;
+- grouping needs to change, such as grouping by parent instead of \`runsOn\`.
+
+Do not compensate for a view filter by duplicating model elements. First inspect
+the built-in query and decide whether the model or the query owns the behavior.
+
+## Graph Is Not The Picture
+
+The linked model can have correct fan-in to one broker, gateway, load balancer,
+producer, or shared runtime node. A crowded diagram means the current view is too
+broad or not aggregated enough; it does not automatically mean the model is
+wrong.
+
+When the graph is right but the picture is noisy:
+
+- narrow \`-s <source.ai>\` to the file that owns the view;
+- copy the nearest \`examples/builtin-views/*.aiq\` query;
+- filter to the layer, flow, or relationship class the user asked for;
+- change \`GROUP BY\` to cluster by parent, runtime placement, or another useful
+  attribute.
+
+Do not duplicate infrastructure or invert dependencies only to make one render
+look cleaner.
+
+## Diagnose A Missing Element
+
+1. Validate the model:
+
+\`\`\`shell
+archinsight link . --format text
+\`\`\`
+
+2. Inspect declarations and source identities:
+
+\`\`\`shell
+archinsight structure . --format text
+\`\`\`
+
+3. Run the built-in query text explicitly:
+
+\`\`\`shell
+archinsight query . -c <context-id> -s <source.ai> -q examples/builtin-views/c4.aiq -f text
+\`\`\`
+
+4. Check the query filters:
+
+- \`node.sourceIdentity = $tab\` means the node must be declared in the selected
+  source file.
+- \`node IS DeploymentElement\` hides actors and ordinary logical elements.
+- \`{projected}\` means only derived deployment projection edges are selected.
+- \`{derived}\` means only rolled-up relationships are selected.
+- \`sourceIdentity: $tab\` on an edge means the relationship/projection must come
+  from the selected source.
+
+## Include External Actors In C4
+
+The built-in C4 query focuses on deployment/container nodes. If a deployment
+diagram needs the external actor that starts the traffic path, copy
+\`examples/builtin-views/c4.aiq\` and widen the node and projected target filters:
+
+\`\`\`cypher
+MATCH (node:Element)
+WHERE node.sourceIdentity = $tab
+  AND (node IS DeploymentElement OR node IS ContainerElement OR node IS Actor)
+OPTIONAL MATCH ROLLUP (node)-[projectedLink {projected, sourceIdentity: $tab}]->(projectedTarget:Element)
+WHERE projectedTarget IS DeploymentElement
+   OR projectedTarget IS ContainerElement
+   OR projectedTarget IS External
+   OR projectedTarget IS Actor
+OPTIONAL MATCH (node)-[directDeploymentLink {sourceIdentity: $tab}]->(directDeploymentTarget:Element)
+WHERE node IS DeploymentElement
+  AND (directDeploymentTarget IS DeploymentElement OR directDeploymentTarget IS External)
+GROUP BY node.runsOn
+RETURN node, projectedLink, projectedTarget, directDeploymentLink, directDeploymentTarget
+\`\`\`
+
+If the actor is declared in another source file, either render from that source
+or relax the \`node.sourceIdentity = $tab\` condition intentionally.
+
+## Show Only Async Flows
+
+Use edge attributes when the question is about relationship kind:
+
+\`\`\`cypher
+MATCH (source:Element)-[link]->(target:Element)
+WHERE source.context = $context
+  AND link.model = 'async'
+GROUP BY source.parent
+RETURN source, link, target
+\`\`\`
+
+This is useful for event-stream, broker, queue, or notification diagrams. Add
+\`source.sourceIdentity = $tab\` when the query should stay scoped to one file.
+
+## Hide Deployment Infrastructure
+
+When a C4-oriented source file is too noisy and you only need logical containers
+or services, select logical container elements and direct logical relationships:
+
+\`\`\`cypher
+MATCH (node:ContainerElement)
+WHERE node.sourceIdentity = $tab
+OPTIONAL MATCH (node)-[link]->(target:ContainerElement)
+GROUP BY node.parent
+RETURN node, link, target
+\`\`\`
+
+This is intentionally closer to C2 than C4. Use it when deployment annotations
+exist in the file but the diagram question is still logical.
+
+## Show Projected Edges Across Split Files
+
+The built-in C4 query restricts projected edges to \`sourceIdentity: $tab\`. That
+is usually correct for a focused deployment-view source file, but it can hide
+projected edges when traffic relationships were split across files.
+
+Copy \`examples/builtin-views/c4.aiq\` and relax only the projected edge selector:
+
+\`\`\`cypher
+MATCH (node:Element)
+WHERE node.sourceIdentity = $tab
+  AND (node IS DeploymentElement OR node IS ContainerElement)
+OPTIONAL MATCH ROLLUP (node)-[projectedLink {projected}]->(projectedTarget:Element)
+WHERE projectedTarget IS DeploymentElement
+   OR projectedTarget IS ContainerElement
+   OR projectedTarget IS External
+OPTIONAL MATCH (node)-[directDeploymentLink {sourceIdentity: $tab}]->(directDeploymentTarget:Element)
+WHERE node IS DeploymentElement
+  AND (directDeploymentTarget IS DeploymentElement OR directDeploymentTarget IS External)
+GROUP BY node.runsOn
+RETURN node, projectedLink, projectedTarget, directDeploymentLink, directDeploymentTarget
+\`\`\`
+
+Use this deliberately. Removing the source filter can bring in projections from
+other view files, so validate the result with \`archinsight query\` before
+rendering.
+
+## Change Grouping
+
+Grouping controls visual clusters. If C4 grouping by \`runsOn\` is not helpful,
+try grouping by parent:
+
+\`\`\`cypher
+MATCH (node:Element)
+WHERE node.sourceIdentity = $tab
+  AND (node IS DeploymentElement OR node IS ContainerElement)
+OPTIONAL MATCH ROLLUP (node)-[projectedLink {projected, sourceIdentity: $tab}]->(projectedTarget:Element)
+WHERE projectedTarget IS DeploymentElement
+   OR projectedTarget IS ContainerElement
+   OR projectedTarget IS External
+GROUP BY node.parent
+RETURN node, projectedLink, projectedTarget
+\`\`\`
+
+Use \`GROUP BY node.runsOn\` for deployment placement; use \`GROUP BY node.parent\`
+for logical ownership.
+
+## Working Rule
+
+If a diagram looks wrong but \`archinsight link\` is clean, inspect the selected
+source, built-in query, and returned aliases before changing the model. Many
+display issues are query scope issues, not schema or linker bugs.
+`;
+}
 function genericLayeredArchitectureExample() {
   return `context shop
     name = Shop Platform
@@ -41346,6 +42273,11 @@ external system payment_provider
 external system analytics_platform
     name = Analytics Platform
     technology = Kafka consumer
+    links:
+        ~> checkout_api
+            technology = Kafka
+            via = checkout.completed
+            description = Consumes completed checkout events
 
 system storefront
     name = Storefront
@@ -41376,12 +42308,6 @@ system storefront
         name = Checkout API
         technology = Kotlin, PostgreSQL
         description = Prices carts, creates orders, and coordinates payment
-        links:
-            ~> analytics_platform
-                technology = Kafka
-                via = checkout.completed
-                description = Publishes completed checkout events
-
         component checkout_controller
             name = Checkout controller
             technology = REST controller
@@ -41398,10 +42324,6 @@ system storefront
                     call = authorize(paymentCommand)
                     description = Requests payment authorization
                 -> order_repository
-                ~> checkout_events
-                    technology = Kafka
-                    via = checkout.completed
-                    description = Publishes completed checkout events
 
         component payment_gateway
             name = Payment gateway
@@ -41418,10 +42340,15 @@ system storefront
             technology = SQL
             responsibility = Stores order state and checkout audit records
 
-        component checkout_events
-            name = Checkout events
-            technology = Kafka producer
-            responsibility = Publishes checkout lifecycle events for downstream consumers
+        component checkout_projection
+            name = Checkout projection
+            technology = Kafka consumer
+            responsibility = Maintains an internal checkout read model from events
+            links:
+                ~> checkout_service
+                    technology = Kafka
+                    via = checkout.completed
+                    description = Consumes checkout completion events
 `;
 }
 function genericC4DeploymentFrameworkExample() {
@@ -41490,7 +42417,6 @@ deploymentProfile public_regional_service
 
     runsOn compute
     uses observability
-    uses publicGateway
 
 environment prod
     name = Production
@@ -41619,11 +42545,25 @@ system storefront
         deployment:
             usesProfile regional_service
             uses storage
-            uses broker
         links:
             -> payment_provider
                 technology = HTTPS
                 call = POST /payments/authorizations
+
+    service order_worker
+        name = Order Worker
+        technology = Kotlin
+        description = Processes order events asynchronously
+        deployment:
+            usesProfile regional_service
+        links:
+            ~> checkout_api
+                technology = Kafka
+                via = orders.events
+                description = Consumes order events emitted by Checkout API
+                deployment:
+                    environmentsFrom regional_service
+                    uses broker
 `;
 }
 function genericC2QueryExample() {