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

package/README.md

@@ -30,7 +30,7 @@ archinsight skill init [project-dir] [--target generic|codex|claude] [--out dir]
 - `-o, --out <file>` - write payload output to a file instead of stdout.
 - `-t, --theme <theme>` - render theme; defaults to `light`.
 - `--target <target>` - skill target for `skill init`: `generic`, `codex`, or `claude`.
-- `--force` - replace existing generated skill files.
+- `--force` - delete and recreate the generated skill directory before writing.
 - `-V, --version` - print version.
 - `-h, --help` - print help.
 
@@ -67,9 +67,11 @@ The generic target writes a runtime-neutral guide:
         c2-containers.md
         c3-components.md
         c4-deployment.md
+        scaling.md
         project-structure.md
         core.md
         queries.md
+        query-recipes.md
         validation.md
     .core/
         *.ai
@@ -80,6 +82,12 @@ The generic target writes a runtime-neutral guide:
         c4-deployment-framework.ai
         c4-deployment.ai
         c2-containers.aiq
+        builtin-views/
+            no-filter.aiq
+            c1.aiq
+            c2.aiq
+            c3.aiq
+            c4.aiq
 ```
 
 Codex and Claude targets package the same Insight reference directly into the

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.6";
 
 // 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,13 @@ If \`archinsight\` is not available, ask the user to install or expose
 2. Preserve indentation and the project's existing naming style.
 3. Model architecture from the outside inward: context, external actors/systems,
    systems, containers/services, components, and deployment details.
-4. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
-5. Validate every Insight change with \`archinsight link . --format text\`.
+4. When the task touches infrastructure, runtime placement, regions, or
+   deployment, decide per system whether pragmatic mixed C2 or clean
+   C4/deployment is appropriate.
+5. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
+6. Keep definition/framework files separate from model files that declare
+   \`context <id>\`.
+7. Validate every Insight change with \`archinsight link . --format text\`.
 
 ## References
 
@@ -38664,12 +38756,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 +38802,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 +38838,16 @@ If \`archinsight\` is not available, ask the user to install or expose
 2. Preserve indentation and the project's existing naming style.
 3. Model architecture from the outside inward: context, external actors/systems,
    systems, containers/services, components, and deployment details.
-4. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
-5. Use \`archinsight structure . --format text\` before broad edits when the
+4. When the task touches infrastructure, runtime placement, regions, or
+   deployment, decide per system whether pragmatic mixed C2 or clean
+   C4/deployment is appropriate.
+5. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
+6. Keep definition/framework files separate from model files that declare
+   \`context <id>\`.
+7. Use \`archinsight structure . --format text\` before broad edits when the
    project shape is unclear.
-6. Validate every Insight change with \`archinsight link . --format text\`.
-7. If validation fails, fix the first real syntax/type/linking error before
+8. Validate every Insight change with \`archinsight link . --format text\`.
+9. If validation fails, fix the first real syntax/type/linking error before
    adding more model content.
 
 ## References
@@ -38761,12 +38866,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 +38913,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 +38949,17 @@ install or expose \`@archinsight/cli\` before changing \`.ai\` files.
 2. Preserve indentation and the project's existing naming style.
 3. Model architecture from the outside inward: context, external actors/systems,
    systems, containers/services, components, and deployment details.
-4. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
-5. Use \`archinsight structure . --format text\` to inspect the current model
+4. When the task touches infrastructure, runtime placement, regions, or
+   deployment, decide per system whether pragmatic mixed C2 or clean
+   C4/deployment is appropriate.
+5. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
+6. Keep definition/framework files separate from model files that declare
+   \`context <id>\`.
+7. Use \`archinsight structure . --format text\` to inspect the current model
    before broad edits when the CLI is available.
-6. Validate every Insight change with \`archinsight link . --format text\` when
+8. Validate every Insight change with \`archinsight link . --format text\` when
    shell access is available; otherwise ask the user to run validation.
-7. If validation fails, fix the first real syntax/type/linking error before
+9. If validation fails, fix the first real syntax/type/linking error before
    adding more model content.
 
 ## Communication
@@ -38879,12 +38997,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 +39028,40 @@ function genericModelingReference() {
 Insight syntax is small; most mistakes are modeling mistakes. Decide the view
 question before changing files.
 
+## Separate Definitions From Model Sources
+
+Keep language/framework definitions separate from graph model files.
+
+- Definition/framework files contain \`define type\`, \`define operator\`,
+  \`define presentation\`, \`extend type\`, \`extend enum of\`, and
+  \`extend presentation\`.
+- Model files declare \`context <id>\` and create graph objects with
+  constructors such as \`system\`, \`service\`, \`component\`, \`environment\`,
+  or \`deploymentProfile\`.
+
+Do not mix definition declarations and \`context\` declarations in one source
+file. Put shared vocabulary in a framework file, then put concrete contexts,
+systems, environments, profiles, and links in model files. This keeps schema
+changes reviewable and avoids source-level syntax failures.
+
+## Model Source Granularity
+
+Default to one primary owned system per model source file: the system you are
+about to detail with containers, services, components, and deployment
+relationships. This keeps the selected source file useful as a C2/C3/C4 view
+scope and avoids accidental mega-files.
+
+Do not create one file per external actor or external system. Shared external
+dependencies are usually better modeled once in a reusable external context, or
+in a few external contexts grouped by meaning such as \`external_platforms\`,
+\`partners\`, or \`regulators\`. Import those shared declarations from system
+files that need them.
+
+If a user asks for deeper splitting, use \`extend <object>\` files for the
+detail being extracted. For example, keep the main service file readable and put
+large per-service component sets in a small utility subdirectory for that
+context.
+
 ## Projections Are Bottom-Up
 
 Built-in C1/C2/C3/C4 views are selected from the linked model. They are not
@@ -38969,14 +39125,30 @@ type hierarchy:
 If a nested declaration fails type checking, fix the type/ownership model rather
 than forcing a link or inventing a wrapper element.
 
-## Keep Infrastructure in the Right View
+## Choose Infrastructure Depth Per System
 
-Do not 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.
+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.
 
-Use deployment types and projection queries when physical realization matters.
+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.
+
+Clean C4 keeps C2 logical and moves physical realization into deployment
+profiles, environments, inventory slots, and projection rules. This is more work
+up front, but it supports many-to-many deployment: one logical service can run
+in several environments whose infrastructure differs by region, provider, or
+organizational boundary.
+
+This choice is per-system, not global. A critical system can use clean C4 while
+peripheral systems stay pragmatic in C2. Starting cheap is acceptable, but know
+that upgrading mixed C2 infrastructure into clean C4 is a migration, not just an
+extra attribute.
 
 ## Eventing
 
@@ -38984,8 +39156,10 @@ Use \`~>\` for asynchronous relationships. Model one async wire per meaningful
 topic or event flow between real producer and consumer elements.
 
 Do not invent a broker node just to make the diagram look familiar. If the
-broker is deployment infrastructure, model it in deployment/C4. If the producer
-or consumer is not known, leave a gap and report it instead of fabricating an
+chosen style is clean C4 and the broker is deployment infrastructure, model it
+in deployment/C4. If the chosen style is pragmatic mixed C2, a broker-like node
+can be acceptable, but document that the view mixes levels. If the producer or
+consumer is not known, leave a gap and report it instead of fabricating an
 element.
 
 ## No Fabricated Elements
@@ -39069,6 +39243,11 @@ Definition files are different from model files. They declare vocabulary:
 \`extend enum of\`, and \`extend presentation\`. Model files usually start with
 \`context <id>\` and then create graph object instances with constructors.
 
+Do not mix these source forms in one file. A framework/definitions file should
+contain only vocabulary/schema declarations. A model file should declare a
+\`context <id>\` and graph object instances. If both are needed, create two
+files and validate the whole project.
+
 ## Type Definitions and Extensions
 
 Use \`define type\` to create a new graph/value type. Use \`extend type\` to add
@@ -39568,6 +39747,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,
@@ -39703,9 +39898,11 @@ service checkout_api
             description = Publishes completed checkout events
 \`\`\`
 
-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 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 +39923,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 +39934,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.
@@ -40056,6 +40255,7 @@ projection rules.
 ## Contents
 
 - What C4 Answers
+- Before You Use C4
 - Mental Model
 - C4 Workflow
 - Environment Inventory
@@ -40081,6 +40281,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:
@@ -40250,7 +40475,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 +40612,6 @@ deploymentProfile global_service
         global_edge
 
     runsOn compute
-    uses publicGateway
 
 deploymentProfile regional_service
     environments:
@@ -40384,6 +40628,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 +40641,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 +40717,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 +40805,6 @@ deploymentProfile public_regional_service
 
     runsOn compute
     uses observability
-    uses publicGateway
 
 service checkout_api
     name = Checkout API
@@ -40604,7 +40857,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
 
@@ -40630,6 +40884,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 +41157,37 @@ Use \`archinsight structure\` before broad edits, imports, or declaration lookup
 Do not start with raw grep when you need to know what the linked project
 contains.
 
+## Source File Classes
+
+Keep source files in one role:
+
+- definition/framework files: \`define type\`, \`define operator\`,
+  \`define presentation\`, \`extend type\`, \`extend enum of\`, and
+  \`extend presentation\`;
+- model files: \`context <id>\`, imports, graph object declarations,
+  relationships, environments, and deployment profiles.
+
+Do not mix definition/framework declarations with \`context <id>\` in one file.
+When a model needs custom vocabulary, add or edit a framework file first, then
+use the resulting constructors and attributes from model files.
+
+## Directory and File Granularity
+
+For larger repositories, group model files by context directory. Inside a
+context directory, default to one primary owned system per ordinary model file:
+the system that will be detailed by containers, services, components, links, and
+deployment information.
+
+External actors and systems are different. Put reusable outside dependencies in
+one external context or a few semantically grouped external contexts. Do not
+create a separate file for every external actor or vendor unless that external
+dependency has real internal structure to model.
+
+If a system needs further splitting, create a utility subdirectory for focused
+\`extend <object>\` files, such as per-service component files. Import the
+extended object explicitly when it is declared in another source file. Keep the
+main system file as the readable entry point.
+
 ## Commands
 
 Human-readable overview:
@@ -40684,6 +41235,33 @@ links:
     -> payments from external_systems
 \`\`\`
 
+Imports are also required when a declaration lives in another source file of the
+same context:
+
+\`\`\`insight
+context services
+
+import eu_service from context services
+
+system checkout_api
+    deployment:
+        usesProfile eu_service
+\`\`\`
+
+The explicit import is intentional. If the source file that declared
+\`eu_service\` is removed or excluded, validation should fail with a clear
+missing import/identifier diagnostic instead of depending on hidden file layout.
+
+For links, \`from <context-id>\` on the target is an inline context qualifier:
+
+\`\`\`insight
+links:
+    -> inventory_api from services
+\`\`\`
+
+Use it when the relationship target is owned by another context or another
+source file whose context ownership should remain visible at the call site.
+
 Do not guess context ids from filenames. Filenames, context ids, and element ids
 can differ.
 
@@ -41141,6 +41719,16 @@ diagram needs stable layout.
 
 ## Built-In View Patterns
 
+Exact built-in query sources are bundled in:
+
+\`\`\`text
+examples/builtin-views/no-filter.aiq
+examples/builtin-views/c1.aiq
+examples/builtin-views/c2.aiq
+examples/builtin-views/c3.aiq
+examples/builtin-views/c4.aiq
+\`\`\`
+
 C1 usually selects systems in the selected context and rolls lower-level links
 up to system-level relationships.
 
@@ -41153,6 +41741,10 @@ and returns component relationships.
 C4 usually selects deployment and container nodes from \`$tab\`, uses
 \`OPTIONAL MATCH ROLLUP\`, and returns projected relationships.
 
+When a built-in view is close but hides the wrong thing, read
+\`references/query-recipes.md\`, copy the nearest built-in \`.aiq\`, and change
+the filter or grouping deliberately.
+
 ## Authoring Rules
 
 - Start from the view question: context, containers, components, or deployment.
@@ -41163,6 +41755,189 @@ C4 usually selects deployment and container nodes from \`$tab\`, uses
 - Keep custom queries in \`.aiq\` files when they are reused.
 `;
 }
+function genericQueryRecipesReference() {
+  return `# Query Recipes and Built-In View Customization
+
+Use this reference when a built-in C1/C2/C3/C4 view is close but not quite right:
+an expected element is hidden, a relationship is missing, infrastructure is too
+noisy, or the diagram needs a different scope.
+
+## Start From Built-In Queries
+
+The generated skill includes exact built-in view queries:
+
+\`\`\`text
+examples/builtin-views/no-filter.aiq
+examples/builtin-views/c1.aiq
+examples/builtin-views/c2.aiq
+examples/builtin-views/c3.aiq
+examples/builtin-views/c4.aiq
+\`\`\`
+
+Before inventing a query from scratch, open the nearest built-in query, copy it
+to the project, and make the smallest change.
+
+\`\`\`shell
+archinsight query . -c <context-id> -s <source.ai> -q queries/custom.aiq -f text
+archinsight render . -c <context-id> -s <source.ai> -q queries/custom.aiq -f svg -o custom.svg
+\`\`\`
+
+Use \`references/queries.md\` for syntax details. Use this file for common
+customization patterns.
+
+## When To Customize
+
+Write or adjust a \`.aiq\` query when:
+
+- the built-in view hides a node or edge that exists in \`archinsight link\`;
+- the source/tab scope is right but the view intentionally filters out a type;
+- C4 should include actors, vendors, or a special deployment path;
+- the diagram should show only one layer, one flow, or one relationship class;
+- grouping needs to change, such as grouping by parent instead of \`runsOn\`.
+
+Do not compensate for a view filter by duplicating model elements. First inspect
+the built-in query and decide whether the model or the query owns the behavior.
+
+## Diagnose A Missing Element
+
+1. Validate the model:
+
+\`\`\`shell
+archinsight link . --format text
+\`\`\`
+
+2. Inspect declarations and source identities:
+
+\`\`\`shell
+archinsight structure . --format text
+\`\`\`
+
+3. Run the built-in query text explicitly:
+
+\`\`\`shell
+archinsight query . -c <context-id> -s <source.ai> -q examples/builtin-views/c4.aiq -f text
+\`\`\`
+
+4. Check the query filters:
+
+- \`node.sourceIdentity = $tab\` means the node must be declared in the selected
+  source file.
+- \`node IS DeploymentElement\` hides actors and ordinary logical elements.
+- \`{projected}\` means only derived deployment projection edges are selected.
+- \`{derived}\` means only rolled-up relationships are selected.
+- \`sourceIdentity: $tab\` on an edge means the relationship/projection must come
+  from the selected source.
+
+## Include External Actors In C4
+
+The built-in C4 query focuses on deployment/container nodes. If a deployment
+diagram needs the external actor that starts the traffic path, copy
+\`examples/builtin-views/c4.aiq\` and widen the node and projected target filters:
+
+\`\`\`cypher
+MATCH (node:Element)
+WHERE node.sourceIdentity = $tab
+  AND (node IS DeploymentElement OR node IS ContainerElement OR node IS Actor)
+OPTIONAL MATCH ROLLUP (node)-[projectedLink {projected, sourceIdentity: $tab}]->(projectedTarget:Element)
+WHERE projectedTarget IS DeploymentElement
+   OR projectedTarget IS ContainerElement
+   OR projectedTarget IS External
+   OR projectedTarget IS Actor
+OPTIONAL MATCH (node)-[directDeploymentLink {sourceIdentity: $tab}]->(directDeploymentTarget:Element)
+WHERE node IS DeploymentElement
+  AND (directDeploymentTarget IS DeploymentElement OR directDeploymentTarget IS External)
+GROUP BY node.runsOn
+RETURN node, projectedLink, projectedTarget, directDeploymentLink, directDeploymentTarget
+\`\`\`
+
+If the actor is declared in another source file, either render from that source
+or relax the \`node.sourceIdentity = $tab\` condition intentionally.
+
+## Show Only Async Flows
+
+Use edge attributes when the question is about relationship kind:
+
+\`\`\`cypher
+MATCH (source:Element)-[link]->(target:Element)
+WHERE source.context = $context
+  AND link.model = 'async'
+GROUP BY source.parent
+RETURN source, link, target
+\`\`\`
+
+This is useful for event-stream, broker, queue, or notification diagrams. Add
+\`source.sourceIdentity = $tab\` when the query should stay scoped to one file.
+
+## Hide Deployment Infrastructure
+
+When a C4-oriented source file is too noisy and you only need logical containers
+or services, select logical container elements and direct logical relationships:
+
+\`\`\`cypher
+MATCH (node:ContainerElement)
+WHERE node.sourceIdentity = $tab
+OPTIONAL MATCH (node)-[link]->(target:ContainerElement)
+GROUP BY node.parent
+RETURN node, link, target
+\`\`\`
+
+This is intentionally closer to C2 than C4. Use it when deployment annotations
+exist in the file but the diagram question is still logical.
+
+## Show Projected Edges Across Split Files
+
+The built-in C4 query restricts projected edges to \`sourceIdentity: $tab\`. That
+is usually correct for a focused deployment-view source file, but it can hide
+projected edges when traffic relationships were split across files.
+
+Copy \`examples/builtin-views/c4.aiq\` and relax only the projected edge selector:
+
+\`\`\`cypher
+MATCH (node:Element)
+WHERE node.sourceIdentity = $tab
+  AND (node IS DeploymentElement OR node IS ContainerElement)
+OPTIONAL MATCH ROLLUP (node)-[projectedLink {projected}]->(projectedTarget:Element)
+WHERE projectedTarget IS DeploymentElement
+   OR projectedTarget IS ContainerElement
+   OR projectedTarget IS External
+OPTIONAL MATCH (node)-[directDeploymentLink {sourceIdentity: $tab}]->(directDeploymentTarget:Element)
+WHERE node IS DeploymentElement
+  AND (directDeploymentTarget IS DeploymentElement OR directDeploymentTarget IS External)
+GROUP BY node.runsOn
+RETURN node, projectedLink, projectedTarget, directDeploymentLink, directDeploymentTarget
+\`\`\`
+
+Use this deliberately. Removing the source filter can bring in projections from
+other view files, so validate the result with \`archinsight query\` before
+rendering.
+
+## Change Grouping
+
+Grouping controls visual clusters. If C4 grouping by \`runsOn\` is not helpful,
+try grouping by parent:
+
+\`\`\`cypher
+MATCH (node:Element)
+WHERE node.sourceIdentity = $tab
+  AND (node IS DeploymentElement OR node IS ContainerElement)
+OPTIONAL MATCH ROLLUP (node)-[projectedLink {projected, sourceIdentity: $tab}]->(projectedTarget:Element)
+WHERE projectedTarget IS DeploymentElement
+   OR projectedTarget IS ContainerElement
+   OR projectedTarget IS External
+GROUP BY node.parent
+RETURN node, projectedLink, projectedTarget
+\`\`\`
+
+Use \`GROUP BY node.runsOn\` for deployment placement; use \`GROUP BY node.parent\`
+for logical ownership.
+
+## Working Rule
+
+If a diagram looks wrong but \`archinsight link\` is clean, inspect the selected
+source, built-in query, and returned aliases before changing the model. Many
+display issues are query scope issues, not schema or linker bugs.
+`;
+}
 function genericLayeredArchitectureExample() {
   return `context shop
     name = Shop Platform
@@ -41490,7 +42265,6 @@ deploymentProfile public_regional_service
 
     runsOn compute
     uses observability
-    uses publicGateway
 
 environment prod
     name = Production
@@ -41619,11 +42393,24 @@ system storefront
         deployment:
             usesProfile regional_service
             uses storage
-            uses broker
         links:
+            ~> order_worker
+                technology = Kafka
+                via = orders.events
+                deployment:
+                    environmentsFrom regional_service
+                    uses broker
+
             -> payment_provider
                 technology = HTTPS
                 call = POST /payments/authorizations
+
+    service order_worker
+        name = Order Worker
+        technology = Kotlin
+        description = Processes order events asynchronously
+        deployment:
+            usesProfile regional_service
 `;
 }
 function genericC2QueryExample() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archinsight/cli",
-  "version": "3.0.0-snapshot.5",
+  "version": "3.0.0-snapshot.6",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {