@archinsight/cli 3.0.0-snapshot.1 → 3.0.0-snapshot.2

package/README.md

@@ -62,12 +62,15 @@ The generic target writes a runtime-neutral guide:
     references/
         syntax.md
         layered-architecture.md
+        queries.md
         validation.md
     examples/
         layered-architecture.ai
+        c2-containers.aiq
 ```
 
-Codex and Claude targets package the same Insight reference as skill folders:
+Codex and Claude targets package the same Insight reference directly into the
+native skill folders:
 
 ```shell
 archinsight skill init --target codex
@@ -75,21 +78,26 @@ archinsight skill init --target claude
 ```
 
 ```text
-.archinsight/skills/codex/archinsight/
+.codex/skills/archinsight/
     SKILL.md
     agents/openai.yaml
     references/
     examples/
 
-.archinsight/skills/claude/archinsight/
+.claude/skills/archinsight/
     SKILL.md
     references/
     examples/
 ```
 
+After generating a Codex or Claude skill into the default location, restart the
+agent session so the skill is discovered. Pass `--out <dir>` to write the same
+package somewhere else.
+
 The guide tells agents to treat `archinsight` as the validation source of truth,
-avoid guessing Insight syntax from other architecture DSLs, and describe systems
-layer by layer from context to containers, components, and deployment details.
+avoid guessing Insight syntax from other architecture DSLs, describe systems
+layer by layer from context to containers, components, and deployment details,
+and write custom `.aiq` diagram queries with the supported Cypher-style subset.
 
 ## Output Contract
 

package/build/index.js

@@ -37460,7 +37460,7 @@ var QueryParser = class {
 };
 
 // src/version.ts
-var version = "3.0.0-snapshot.1";
+var version = "3.0.0-snapshot.2";
 
 // src/index.ts
 var hiddenStructureTypes = /* @__PURE__ */ new Set(["List", "Nothing", "Text", "text"]);
@@ -37651,11 +37651,12 @@ async function runSkill(args) {
 }
 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);
   for (const file of skillPackage.files) {
     await writeGeneratedFile(path.join(outputRoot, file.path), file.content, args.force);
   }
-  process.stdout.write(skillPackageSuccess(projectRoot, outputRoot, skillPackage));
+  process.stdout.write(skillPackageSuccess(projectRoot, outputRoot, skillPackage, usesDefaultOutput));
 }
 async function loadProject(input) {
   const root = path.resolve(input);
@@ -37731,11 +37732,11 @@ async function sourceFiles(directory) {
   const entries = await readdir(directory, { withFileTypes: true });
   const result = [];
   for (const entry of entries) {
-    if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".archinsight" || entry.name === "build") {
-      continue;
-    }
     const entryPath = path.join(directory, entry.name);
     if (entry.isDirectory()) {
+      if (isIgnoredSourceDirectory(entry.name)) {
+        continue;
+      }
       result.push(...await sourceFiles(entryPath));
     } else if (entry.isFile() && entry.name.endsWith(".ai")) {
       result.push(entryPath);
@@ -37743,6 +37744,9 @@ async function sourceFiles(directory) {
   }
   return result.sort((left, right) => left.localeCompare(right));
 }
+function isIgnoredSourceDirectory(name) {
+  return name.startsWith(".") || name === "node_modules" || name === "build" || name === "dist";
+}
 async function renderSvg(dot) {
   const viz = await instance();
   const result = viz.render(dot, { format: "svg", engine: "dot" });
@@ -38115,6 +38119,7 @@ function genericSkillPackage() {
     target: "generic",
     defaultOutput: ".archinsight/agent",
     entrypoint: "archinsight.md",
+    installedByDefault: false,
     files: [
       {
         path: "archinsight.md",
@@ -38127,8 +38132,9 @@ function genericSkillPackage() {
 function codexSkillPackage() {
   return {
     target: "codex",
-    defaultOutput: ".archinsight/skills/codex/archinsight",
+    defaultOutput: ".codex/skills/archinsight",
     entrypoint: "SKILL.md",
+    installedByDefault: true,
     files: [
       {
         path: "SKILL.md",
@@ -38145,8 +38151,9 @@ function codexSkillPackage() {
 function claudeSkillPackage() {
   return {
     target: "claude",
-    defaultOutput: ".archinsight/skills/claude/archinsight",
+    defaultOutput: ".claude/skills/archinsight",
     entrypoint: "SKILL.md",
+    installedByDefault: true,
     files: [
       {
         path: "SKILL.md",
@@ -38170,27 +38177,39 @@ function sharedSkillFiles() {
       path: "references/validation.md",
       content: genericValidationReference()
     },
+    {
+      path: "references/queries.md",
+      content: genericQueriesReference()
+    },
     {
       path: "examples/layered-architecture.ai",
       content: genericLayeredArchitectureExample()
+    },
+    {
+      path: "examples/c2-containers.aiq",
+      content: genericC2QueryExample()
     }
   ];
 }
-function skillPackageSuccess(projectRoot, outputRoot, skillPackage) {
+function skillPackageSuccess(projectRoot, outputRoot, skillPackage, usesDefaultOutput) {
   const lines = [
     `Generated ${skillPackage.target} Archinsight agent guide: ${displayPath(process.cwd(), outputRoot)}`,
-    "",
-    "Next steps:"
+    ""
   ];
   if (skillPackage.target === "generic") {
+    lines.push("Next steps:");
     lines.push(`  1. Share ${displayPath(projectRoot, path.join(outputRoot, skillPackage.entrypoint))} with your AI agent.`);
     lines.push("  2. Ask the agent to validate Insight edits with: archinsight link . --format text");
     lines.push("  3. Keep project-specific conventions near the generated guide or pass them in the prompt.");
+  } else if (skillPackage.installedByDefault && usesDefaultOutput) {
+    lines.push(`Notice: restart the ${skillPackage.target} session so the Archinsight skill is discovered.`);
   } else if (skillPackage.target === "codex") {
+    lines.push("Next steps:");
     lines.push(`  1. Install or copy ${displayPath(projectRoot, outputRoot)} as the archinsight skill in your Codex skills directory.`);
     lines.push("  2. Invoke it explicitly as $archinsight when editing Insight .ai models.");
     lines.push("  3. Ask Codex to validate Insight edits with: archinsight link . --format text");
   } else {
+    lines.push("Next steps:");
     lines.push(`  1. Import or copy ${displayPath(projectRoot, outputRoot)} into your Claude skill runtime.`);
     lines.push("  2. Ask Claude to use the Archinsight skill before editing Insight .ai models.");
     lines.push("  3. Validate Insight edits with: archinsight link . --format text");
@@ -38232,6 +38251,8 @@ If \`archinsight\` is not available, ask the user to install or expose
 - Read \`references/syntax.md\` before writing unfamiliar Insight syntax.
 - Read \`references/layered-architecture.md\` when decomposing a system across
   C1/C2/C3/C4-style layers.
+- Read \`references/queries.md\` when writing custom diagram queries or \`.aiq\`
+  files.
 - Read \`references/validation.md\` before running checks, structure inspection,
   or rendering.
 - Use \`examples/layered-architecture.ai\` as a compact valid model.
@@ -38257,6 +38278,8 @@ Treat this \`SKILL.md\` as the entrypoint. Load reference files only when needed
 - Read \`references/syntax.md\` before writing unfamiliar Insight syntax.
 - Read \`references/layered-architecture.md\` before decomposing a system across
   C1/C2/C3/C4-style layers.
+- Read \`references/queries.md\` before writing custom diagram queries or \`.aiq\`
+  files.
 - Read \`references/validation.md\` before running checks, structure inspection,
   or rendering commands.
 
@@ -38295,6 +38318,8 @@ If \`archinsight\` is not available, ask the user to install or expose
 - Read \`references/syntax.md\` before writing unfamiliar Insight syntax.
 - Read \`references/layered-architecture.md\` when decomposing a system across
   C1/C2/C3/C4-style layers.
+- Read \`references/queries.md\` when writing custom diagram queries or \`.aiq\`
+  files.
 - Read \`references/validation.md\` before running checks, structure inspection,
   or rendering.
 - Use \`examples/layered-architecture.ai\` as a compact valid model.
@@ -38321,6 +38346,8 @@ they are needed:
 - Read \`references/syntax.md\` before writing unfamiliar Insight syntax.
 - Read \`references/layered-architecture.md\` before decomposing a system across
   C1/C2/C3/C4-style layers.
+- Read \`references/queries.md\` before writing custom diagram queries or \`.aiq\`
+  files.
 - Read \`references/validation.md\` before asking the user to run validation,
   structure inspection, or rendering commands.
 
@@ -38379,6 +38406,8 @@ sections of Insight unless the existing layering is already understood.
 - Read \`references/syntax.md\` before writing unfamiliar Insight syntax.
 - Read \`references/layered-architecture.md\` when decomposing a system across
   C1/C2/C3/C4-style layers.
+- Read \`references/queries.md\` when writing custom diagram queries or \`.aiq\`
+  files.
 - Read \`references/validation.md\` before running checks, structure inspection,
   or rendering.
 - Use \`examples/layered-architecture.ai\` as a compact valid model.
@@ -38672,6 +38701,13 @@ archinsight render . -c <context-id> -v c1 -f svg -o diagram.svg
 archinsight render . -c <context-id> -v c2 -f svg -o diagram.svg
 \`\`\`
 
+Run a custom query from a file:
+
+\`\`\`shell
+archinsight query . -c <context-id> -s <source.ai> -q query.aiq -f text
+archinsight render . -c <context-id> -s <source.ai> -q query.aiq -f svg -o diagram.svg
+\`\`\`
+
 Useful built-in views:
 
 - \`c1\` for system context.
@@ -38686,6 +38722,173 @@ If the CLI is missing, do not silently install it. Ask the user to install or
 expose \`@archinsight/cli\`.
 `;
 }
+function genericQueriesReference() {
+  return `# Insight Query Reference
+
+Insight diagram queries use a small Cypher-style subset evaluated in memory.
+Use queries to select which linked model elements and relationships appear in a
+diagram.
+
+## CLI Shape
+
+\`\`\`shell
+archinsight query . -c <context-id> -s <source.ai> -q query.aiq -f text
+archinsight render . -c <context-id> -s <source.ai> -q query.aiq -f svg -o diagram.svg
+\`\`\`
+
+The scope variables are:
+
+- \`$context\` - selected context id from \`--context\`.
+- \`$tab\` - selected source identity from \`--source\` / \`--tab\`.
+
+Pass \`--source\` when a query uses \`$tab\`.
+
+## Query Shape
+
+Supported clauses:
+
+\`\`\`cypher
+MATCH ...
+OPTIONAL MATCH ...
+WHERE ...
+GROUP BY ...
+RETURN ...
+\`\`\`
+
+\`MATCH\` clauses come first. \`GROUP BY\` is optional and appears before
+\`RETURN\`. \`RETURN\` must list the aliases that should be rendered.
+
+## Node Patterns
+
+Select all nodes:
+
+\`\`\`cypher
+MATCH (element)
+WHERE element.context = $context
+RETURN element
+\`\`\`
+
+Select by type label:
+
+\`\`\`cypher
+MATCH (service:Service)
+WHERE service.context = $context
+RETURN service
+\`\`\`
+
+Labels are case-sensitive and match Insight types such as \`System\`,
+\`Container\`, \`Service\`, \`Component\`, \`ExternalSystem\`, and
+\`DeploymentElement\`.
+
+Use properties in patterns for exact matches:
+
+\`\`\`cypher
+MATCH (service:Service {id: 'checkout_api', context: $context})
+RETURN service
+\`\`\`
+
+## Relationships
+
+Select real relationships:
+
+\`\`\`cypher
+MATCH (source)-[link]->(target)
+WHERE source.context = $context
+RETURN source, link, target
+\`\`\`
+
+Use \`OPTIONAL MATCH\` when nodes should still appear even if a relationship is
+missing:
+
+\`\`\`cypher
+MATCH (container:ContainerElement)
+WHERE container.sourceIdentity = $tab
+OPTIONAL MATCH (container)-[link]->(target)
+RETURN container, link, target
+\`\`\`
+
+Relationship aliases must be returned for edges to render.
+
+## Filtering
+
+Supported filters include:
+
+\`\`\`cypher
+WHERE node.context = $context
+WHERE node.sourceIdentity = $tab
+WHERE node IS External
+WHERE NOT node IS DeploymentElement
+WHERE edge.projected = 'true'
+WHERE node.id IN ['api', 'web_app']
+WHERE node.technology CONTAINS 'PostgreSQL'
+WHERE node.type <> 'Context'
+WHERE node.context = $context AND NOT node IS External
+\`\`\`
+
+Use single quotes for string literals.
+
+## Relationship Selectors
+
+Relationship selectors are boolean flags inside relationship braces:
+
+\`\`\`cypher
+OPTIONAL MATCH (node)-[derivedLink {derived}]->(target)
+OPTIONAL MATCH (node)-[projectedLink {projected}]->(target)
+OPTIONAL MATCH ROLLUP (node)-[rollupLink {derived}]->(target)
+\`\`\`
+
+Use \`{derived}\` for rolled-up edges from child relationships. Use
+\`{projected}\` for deployment/projected edges.
+
+## Grouping
+
+\`GROUP BY\` controls diagram clusters. Group by parent for C2/C3 style views:
+
+\`\`\`cypher
+MATCH (container:ContainerElement)
+WHERE container.sourceIdentity = $tab
+OPTIONAL MATCH (container)-[link]->(target)
+GROUP BY container.parent
+RETURN container, link, target
+\`\`\`
+
+For deployment views, grouping by a typed reference attribute is valid:
+
+\`\`\`cypher
+MATCH (node:Element)
+WHERE node.sourceIdentity = $tab
+OPTIONAL MATCH ROLLUP (node)-[projectedLink {projected, sourceIdentity: $tab}]->(target)
+GROUP BY node.runsOn
+RETURN node, projectedLink, target
+\`\`\`
+
+Do not rely on implicit Graphviz clustering. Put grouping in the query when the
+diagram needs stable layout.
+
+## Built-In View Patterns
+
+C1 usually selects systems in the selected context and rolls lower-level links
+up to system-level relationships.
+
+C2 usually selects \`ContainerElement\` nodes in \`$tab\`, returns direct internal
+relationships, and includes external systems through optional/rollup matches.
+
+C3 usually starts from \`(container:ContainerElement)-[:CONTAINS]->(component)\`
+and returns component relationships.
+
+C4 usually selects deployment and container nodes from \`$tab\`, uses
+\`OPTIONAL MATCH ROLLUP\`, and returns projected relationships.
+
+## Authoring Rules
+
+- Start from the view question: context, containers, components, or deployment.
+- Use domain variable names: \`system\`, \`container\`, \`component\`, \`externalSystem\`.
+- Return every node and relationship alias needed for rendering.
+- Add \`GROUP BY\` deliberately for diagrams with clusters.
+- Validate query files with \`archinsight query\` before rendering.
+- Keep custom queries in \`.aiq\` files when they are reused.
+`;
+}
 function genericLayeredArchitectureExample() {
   return `context shop
     name = Shop Platform
@@ -38738,6 +38941,18 @@ system storefront
             responsibility = Calls the payment provider and normalizes errors
 `;
 }
+function genericC2QueryExample() {
+  return `MATCH (container:ContainerElement)
+WHERE container.sourceIdentity = $tab
+OPTIONAL MATCH (container)-[internalLink]->(targetContainer:ContainerElement)
+OPTIONAL MATCH (container)-[outboundLink]->(externalSystem:SystemElement)
+WHERE externalSystem IS External
+OPTIONAL MATCH (sourceSystem:SystemElement)-[inboundLink]->(container)
+WHERE sourceSystem IS External
+GROUP BY container.parent
+RETURN container, internalLink, targetContainer, outboundLink, externalSystem, inboundLink, sourceSystem
+`;
+}
 var CliError = class extends Error {
 };
 main().catch((error) => {

package/package.json

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