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

package/README.md

@@ -13,6 +13,7 @@ archinsight link [project-dir] [--format text|json] [--out file]
 archinsight structure [project-dir] [--format text|json] [--out file]
 archinsight query [project-dir] -c <context> [-s <source>] [-v c1|c2|c3|c4|no-filter] [-q query.aiq] [-f text|json] [-o file]
 archinsight render [project-dir] -c <context> [-s <source>] [-v c1|c2|c3|c4|no-filter] [-q query.aiq] [-f dot|svg|json] [-o file]
+archinsight skill init [project-dir] [--target generic|codex|claude] [--out dir] [--force]
 ```
 
 `project-dir` defaults to the current directory.
@@ -27,6 +28,8 @@ archinsight render [project-dir] -c <context> [-s <source>] [-v c1|c2|c3|c4|no-f
 - `-f, --format <format>` - command output format.
 - `-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.
 - `-V, --version` - print version.
 - `-h, --help` - print help.
 
@@ -45,6 +48,57 @@ Render DOT for a context using the C2 built-in query:
 node archinsight-cli/build/index.js render examples -c demo -s main.ai -v c2 -f dot
 ```
 
+Generate a portable AI-agent guide for an Insight project:
+
+```shell
+archinsight skill init --target generic
+```
+
+The generic target writes a runtime-neutral guide:
+
+```text
+.archinsight/agent/
+    archinsight.md
+    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 directly into the
+native skill folders:
+
+```shell
+archinsight skill init --target codex
+archinsight skill init --target claude
+```
+
+```text
+.codex/skills/archinsight/
+    SKILL.md
+    agents/openai.yaml
+    references/
+    examples/
+
+.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, 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
 
 Payload output goes to stdout unless `--out` is supplied.

package/build/index.js

@@ -37460,7 +37460,7 @@ var QueryParser = class {
 };
 
 // src/version.ts
-var version = "3.0.0-snapshot.0";
+var version = "3.0.0-snapshot.2";
 
 // src/index.ts
 var hiddenStructureTypes = /* @__PURE__ */ new Set(["List", "Nothing", "Text", "text"]);
@@ -37547,6 +37547,9 @@ async function main() {
     case "structure":
       await runStructure(args);
       return;
+    case "skill":
+      await runSkill(args);
+      return;
   }
 }
 async function runLink(args) {
@@ -37629,6 +37632,32 @@ async function runStructure(args) {
   }
   await writeOutput(args.output, formatStructure(structure));
 }
+async function runSkill(args) {
+  if (args.skillAction !== "init") {
+    throw new CliError("Usage: archinsight skill init [project-dir] [--target generic|codex|claude] [--out dir] [--force]");
+  }
+  const target = skillTarget(args.target);
+  switch (target) {
+    case "generic":
+      await runSkillInit(args, genericSkillPackage());
+      return;
+    case "codex":
+      await runSkillInit(args, codexSkillPackage());
+      return;
+    case "claude":
+      await runSkillInit(args, claudeSkillPackage());
+      return;
+  }
+}
+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, usesDefaultOutput));
+}
 async function loadProject(input) {
   const root = path.resolve(input);
   const sources = await readSources(root);
@@ -37703,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 === "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);
@@ -37715,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" });
@@ -37896,6 +37928,24 @@ async function writeOutput(file, content) {
   await mkdir(path.dirname(path.resolve(file)), { recursive: true });
   await writeFile(file, content);
 }
+async function writeGeneratedFile(file, content, force) {
+  if (!force && await exists(file)) {
+    throw new CliError(`Refusing to overwrite '${file}'. Pass --force to replace generated agent files.`);
+  }
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, content);
+}
+async function exists(file) {
+  try {
+    await stat(file);
+    return true;
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
 function parseArgs(argv) {
   const options = {};
   const positional = [];
@@ -37909,6 +37959,10 @@ function parseArgs(argv) {
       options.version = true;
       continue;
     }
+    if (arg === "--force") {
+      options.force = true;
+      continue;
+    }
     const key = optionKey(arg);
     if (key !== void 0) {
       const value = argv[index + 1];
@@ -37926,7 +37980,8 @@ function parseArgs(argv) {
   }
   return {
     command: command(positional[0]),
-    input: positional[1],
+    skillAction: skillAction(positional[0], positional[1]),
+    input: inputPath(positional),
     context: stringOption(options.context),
     tab: stringOption(options.tab),
     view: viewOption(options.view),
@@ -37934,8 +37989,10 @@ function parseArgs(argv) {
     output: stringOption(options.output),
     format: stringOption(options.format),
     theme: stringOption(options.theme),
+    target: stringOption(options.target),
     help: options.help === true,
-    version: options.version === true
+    version: options.version === true,
+    force: options.force === true
   };
 }
 function optionKey(arg) {
@@ -37954,11 +38011,12 @@ function optionKey(arg) {
     "--format": "format",
     "-f": "format",
     "--theme": "theme",
-    "-t": "theme"
+    "-t": "theme",
+    "--target": "target"
   }[arg];
 }
 function command(value) {
-  if (value === "link" || value === "render" || value === "query" || value === "structure") {
+  if (value === "link" || value === "render" || value === "query" || value === "structure" || value === "skill") {
     return value;
   }
   if (value === void 0) {
@@ -37966,6 +38024,30 @@ function command(value) {
   }
   throw new CliError(`Unknown command '${value}'`);
 }
+function skillAction(commandValue, value) {
+  if (commandValue !== "skill") {
+    return void 0;
+  }
+  if (value === "init") {
+    return value;
+  }
+  if (value === void 0) {
+    return void 0;
+  }
+  throw new CliError(`Unknown skill command '${value}'`);
+}
+function inputPath(positional) {
+  return positional[0] === "skill" ? positional[2] : positional[1];
+}
+function skillTarget(value) {
+  if (value === void 0 || value === "generic") {
+    return "generic";
+  }
+  if (value === "codex" || value === "claude") {
+    return value;
+  }
+  throw new CliError(`Unknown skill target '${value}'`);
+}
 function viewOption(value) {
   if (value === void 0) {
     return void 0;
@@ -37996,6 +38078,13 @@ function renderFormat(value, fallback) {
 function stringOption(value) {
   return typeof value === "string" ? value : void 0;
 }
+function displayPath(from, target) {
+  const relative = path.relative(from, target);
+  if (relative === "") {
+    return ".";
+  }
+  return relative.startsWith("..") || path.isAbsolute(relative) ? target : relative;
+}
 function helpText() {
   return `Archinsight CLI ${version}
 
@@ -38004,6 +38093,7 @@ Usage:
   archinsight render [project-dir] -c <context> [-s <source>] [-v c1|c2|c3|c4|no-filter] [-q query.aiq] [-f dot|svg|json] [-o file]
   archinsight query [project-dir] -c <context> [-s <source>] [-v c1|c2|c3|c4|no-filter] [-q query.aiq] [-f text|json] [-o file]
   archinsight structure [project-dir] [--format text|json] [--out file]
+  archinsight skill init [project-dir] [--target generic|codex|claude] [--out dir] [--force]
 
 Options:
   project-dir             Project directory to scan recursively, default: current directory.
@@ -38013,8 +38103,10 @@ Options:
   -v, --view <name>        Built-in view: c1, c2, c3, c4, no-filter.
   -q, --query <file>       Query file; overrides --view.
   -f, --format <format>    Output format.
-  -o, --out <file>         Write output to file instead of stdout.
+  -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.
   -V, --version            Print version.
   -h, --help               Show help.
 
@@ -38022,6 +38114,845 @@ Diagnostics text format is TSV:
   level<TAB>code<TAB>source<TAB>line<TAB>column<TAB>message
 `;
 }
+function genericSkillPackage() {
+  return {
+    target: "generic",
+    defaultOutput: ".archinsight/agent",
+    entrypoint: "archinsight.md",
+    installedByDefault: false,
+    files: [
+      {
+        path: "archinsight.md",
+        content: genericSkillGuide()
+      },
+      ...sharedSkillFiles()
+    ]
+  };
+}
+function codexSkillPackage() {
+  return {
+    target: "codex",
+    defaultOutput: ".codex/skills/archinsight",
+    entrypoint: "SKILL.md",
+    installedByDefault: true,
+    files: [
+      {
+        path: "SKILL.md",
+        content: codexSkillGuide()
+      },
+      {
+        path: "agents/openai.yaml",
+        content: codexOpenAiYaml()
+      },
+      ...sharedSkillFiles()
+    ]
+  };
+}
+function claudeSkillPackage() {
+  return {
+    target: "claude",
+    defaultOutput: ".claude/skills/archinsight",
+    entrypoint: "SKILL.md",
+    installedByDefault: true,
+    files: [
+      {
+        path: "SKILL.md",
+        content: claudeSkillGuide()
+      },
+      ...sharedSkillFiles()
+    ]
+  };
+}
+function sharedSkillFiles() {
+  return [
+    {
+      path: "references/syntax.md",
+      content: genericSyntaxReference()
+    },
+    {
+      path: "references/layered-architecture.md",
+      content: genericLayeredArchitectureReference()
+    },
+    {
+      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, usesDefaultOutput) {
+  const lines = [
+    `Generated ${skillPackage.target} Archinsight agent guide: ${displayPath(process.cwd(), outputRoot)}`,
+    ""
+  ];
+  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");
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function genericSkillGuide() {
+  return `# Archinsight Agent Guide
+
+Use this guide when creating or editing Insight \`.ai\` architecture models.
+
+Insight is its own typed architecture-as-code language. Do not infer its syntax
+from YAML, Mermaid, PlantUML, Structurizr, or C4 DSL.
+
+## Required Tool
+
+Use the Archinsight CLI as the validation source of truth:
+
+\`\`\`shell
+archinsight --help
+archinsight link . --format text
+\`\`\`
+
+If \`archinsight\` is not available, ask the user to install or expose
+\`@archinsight/cli\` before changing \`.ai\` files.
+
+## Workflow
+
+1. Read the existing \`.ai\` files before editing.
+2. Preserve indentation and the project's existing naming style.
+3. Model architecture from the outside inward: context, external actors/systems,
+   systems, containers/services, components, and deployment details.
+4. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
+5. Validate every Insight change with \`archinsight link . --format text\`.
+
+## References
+
+- 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.
+`;
+}
+function codexSkillGuide() {
+  return `---
+name: archinsight
+description: Create, edit, validate, inspect, and render Archinsight Insight architecture-as-code models. Use when working with .ai Insight files, C4-style architecture models, system/container/component diagrams, deployment projections, or when the user asks to model software architecture with Archinsight.
+---
+
+# Archinsight
+
+Use this skill when creating or editing Insight \`.ai\` architecture models.
+
+Insight is its own typed architecture-as-code language. Do not infer its syntax
+from YAML, Mermaid, PlantUML, Structurizr, or C4 DSL.
+
+## Codex Usage Notes
+
+Treat this \`SKILL.md\` as the entrypoint. Load reference files only when needed:
+
+- 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.
+
+Use Codex shell access to validate changes when available. Do not silently
+install global npm packages or change machine configuration. If \`archinsight\`
+is missing, ask the user whether they want to install or expose
+\`@archinsight/cli\`.
+
+## Required Tool
+
+Use the Archinsight CLI as the validation source of truth:
+
+\`\`\`shell
+archinsight --help
+archinsight link . --format text
+\`\`\`
+
+If \`archinsight\` is not available, ask the user to install or expose
+\`@archinsight/cli\` before changing \`.ai\` files.
+
+## Workflow
+
+1. Read the existing \`.ai\` files before editing.
+2. Preserve indentation and the project's existing naming style.
+3. Model architecture from the outside inward: context, external actors/systems,
+   systems, containers/services, components, and deployment details.
+4. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
+5. 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
+   adding more model content.
+
+## References
+
+- 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.
+`;
+}
+function claudeSkillGuide() {
+  return `---
+name: archinsight
+description: Create, edit, validate, inspect, and render Archinsight Insight architecture-as-code models. Use when working with .ai Insight files, C4-style architecture models, system/container/component diagrams, deployment projections, or when the user asks to model software architecture with Archinsight.
+---
+
+# Archinsight
+
+Use this skill when creating or editing Insight \`.ai\` architecture models.
+
+Insight is its own typed architecture-as-code language. Do not infer its syntax
+from YAML, Mermaid, PlantUML, Structurizr, or C4 DSL.
+
+## Claude Usage Notes
+
+Treat this \`SKILL.md\` as the entrypoint. Load the reference files only when
+they are needed:
+
+- 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.
+
+When Claude has direct shell access, run validation yourself. When Claude is
+embedded in an editor without shell access, ask the user to run the exact command
+and paste the output. Do not silently install npm packages or change machine
+configuration.
+
+## Required Tool
+
+Use the Archinsight CLI as the validation source of truth:
+
+\`\`\`shell
+archinsight --help
+archinsight link . --format text
+\`\`\`
+
+If \`archinsight\` is not available in Claude's environment, ask the user to
+install or expose \`@archinsight/cli\` before changing \`.ai\` files.
+
+## Workflow
+
+1. Read the existing \`.ai\` files before editing.
+2. Preserve indentation and the project's existing naming style.
+3. Model architecture from the outside inward: context, external actors/systems,
+   systems, containers/services, components, and deployment details.
+4. Prefer small, focused files connected by \`context\`, \`import\`, and \`extend\`.
+5. 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
+   shell access is available; otherwise ask the user to run validation.
+7. If validation fails, fix the first real syntax/type/linking error before
+   adding more model content.
+
+## Communication
+
+When shell access is unavailable, give the user short copy-pasteable commands:
+
+\`\`\`shell
+archinsight link . --format text
+archinsight structure . --format text
+\`\`\`
+
+If rendering is needed, ask for the context id and source file when they are not
+obvious:
+
+\`\`\`shell
+archinsight render . -c <context-id> -s <source.ai> -v c2 -f svg -o diagram.svg
+\`\`\`
+
+Report diagnostics by source, line, column, and message. Avoid rewriting large
+sections of Insight unless the existing layering is already understood.
+
+## References
+
+- Read \`references/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.
+`;
+}
+function codexOpenAiYaml() {
+  return `interface:
+  display_name: "Archinsight"
+  short_description: "Work with Insight architecture models"
+  default_prompt: "Use $archinsight to model or validate Insight architecture-as-code files."
+
+policy:
+  allow_implicit_invocation: true
+`;
+}
+function genericSyntaxReference() {
+  return `# Insight Syntax Reference
+
+## Files and Contexts
+
+Every model starts with a context:
+
+\`\`\`insight
+context ecommerce
+    name = E-commerce Platform
+\`\`\`
+
+Use indentation to define ownership. Children belong to the nearest less-indented
+parent.
+
+## Common Elements
+
+Use built-in constructors for C4-style architecture:
+
+\`\`\`insight
+external actor customer
+    name = Customer
+    technology = Web browser
+
+system storefront
+    name = Storefront
+    technology = SvelteKit, TypeScript
+
+    container web_app
+        name = Web app
+        technology = SvelteKit
+
+    service catalog_api
+        name = Catalog API
+        technology = Node.js, PostgreSQL
+\`\`\`
+
+Useful built-ins include:
+
+- \`context\` for a bounded architecture model.
+- \`external actor\` and \`external system\` for dependencies outside the owned system.
+- \`system\` for major systems in a context.
+- \`container\` for deployable or executable units.
+- \`service\` for backend/container services.
+- \`component\` for internals of a selected container or service.
+
+## Attributes
+
+Attributes are named and typed:
+
+\`\`\`insight
+name = Checkout API
+technology = Kotlin, PostgreSQL
+description = Handles cart pricing, order placement, and payment orchestration
+\`\`\`
+
+Long text can continue on indented following lines:
+
+\`\`\`insight
+description = Handles checkout orchestration and keeps payment provider details
+    outside the storefront.
+\`\`\`
+
+## Relationships
+
+Put relationships under \`links:\`.
+
+\`\`\`insight
+links:
+    -> checkout_api
+        technology = HTTPS, JSON
+        description = Places an order
+    ~> analytics
+        technology = Kafka
+        description = Publishes order events
+\`\`\`
+
+Use \`from <context-id>\` when linking to an imported element from another
+context:
+
+\`\`\`insight
+import payments from context external_systems
+
+links:
+    -> payments from external_systems
+\`\`\`
+
+## Imports and Extensions
+
+Split larger models across files by repeating the context id and extending
+existing elements:
+
+\`\`\`insight
+context ecommerce
+
+extend service checkout_api
+    component payment_adapter
+        name = Payment adapter
+        technology = HTTP client
+\`\`\`
+
+Use imports for elements from another context:
+
+\`\`\`insight
+import stripe from context external_systems
+\`\`\`
+
+## Annotations
+
+Annotations decorate the next declaration or link:
+
+\`\`\`insight
+@planned
+external system warehouse
+    name = Warehouse
+
+links:
+    @deprecated
+    ~> legacy_erp
+\`\`\`
+
+Use presentation definitions for durable visual styling. Avoid adding new
+Graphviz attributes directly unless the project already uses that convention.
+
+## Custom Types
+
+Projects can extend the language with typed vocabulary:
+
+\`\`\`insight
+define type Broker of InfrastructureComponent
+    constructor broker
+\`\`\`
+
+When adding custom types, follow the existing framework files and validate
+immediately. Do not invent constructors without checking whether the project
+already defines the needed type.
+`;
+}
+function genericLayeredArchitectureReference() {
+  return `# Modeling Architecture by Layers
+
+Describe architecture from broad intent to implementation detail. Keep every
+layer useful on its own.
+
+## C1: System Context
+
+Start with the context, people, owned systems, and external dependencies.
+
+\`\`\`insight
+context ecommerce
+    name = E-commerce Platform
+
+external actor customer
+    name = Customer
+    technology = Web browser
+    links:
+        -> storefront
+
+external system payment_provider
+    name = Payment Provider
+    technology = HTTPS API
+
+system storefront
+    name = Storefront
+    technology = Web app
+\`\`\`
+
+At this layer, avoid implementation details. Explain who uses the system and
+which external systems matter.
+
+## C2: Containers and Services
+
+Nest deployable units under the owned system:
+
+\`\`\`insight
+system storefront
+    name = Storefront
+
+    container web_app
+        name = Web app
+        technology = SvelteKit, TypeScript
+        links:
+            -> checkout_api
+
+    service checkout_api
+        name = Checkout API
+        technology = Node.js, PostgreSQL
+        links:
+            -> payment_provider from ecommerce
+\`\`\`
+
+Use \`container\` for applications or deployable units. Use \`service\` for
+backend services. Add links that explain runtime collaboration.
+
+## C3: Components
+
+Put component details in a separate file with \`extend\` when the service becomes
+interesting enough to decompose:
+
+\`\`\`insight
+context ecommerce
+
+extend service checkout_api
+    component order_controller
+        name = Order controller
+        technology = REST
+        responsibility = Accepts checkout requests and returns order status
+        links:
+            -> payment_client
+
+    component payment_client
+        name = Payment client
+        technology = HTTP client
+        responsibility = Calls the external payment provider
+\`\`\`
+
+Components should describe responsibilities, not every class or function.
+
+## C4 and Deployment
+
+Use deployment profiles and infrastructure types when physical realization is
+important:
+
+\`\`\`insight
+deploymentProfile production
+    environments:
+        eu
+
+environment eu
+    name = Europe
+\`\`\`
+
+Attach deployment details to systems, containers, services, or links only when
+they clarify real runtime paths.
+
+## Layering Rules
+
+- Model stable concepts first; avoid coding transient implementation details.
+- Keep identifiers short, lowercase, and stable.
+- Prefer \`name\` for display names and ids for references.
+- Use \`description\` for why a thing exists.
+- Use \`technology\` for concrete technical choices.
+- Use \`responsibility\` for components.
+- Split files by layer or subsystem once a file becomes hard to scan.
+- Validate after each layer before adding the next.
+`;
+}
+function genericValidationReference() {
+  return `# Validation and Inspection
+
+Run validation after every Insight edit:
+
+\`\`\`shell
+archinsight link . --format text
+\`\`\`
+
+The text output is TSV:
+
+\`\`\`text
+level<TAB>code<TAB>source<TAB>line<TAB>column<TAB>message
+\`\`\`
+
+Treat \`ERROR\` as blocking. \`WARNING\` and \`NOTE\` can still be useful design
+feedback.
+
+Inspect project structure:
+
+\`\`\`shell
+archinsight structure . --format text
+\`\`\`
+
+Render a diagram when a context id is known:
+
+\`\`\`shell
+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.
+- \`c2\` for containers/services in the selected source.
+- \`c3\` for components in the selected source.
+- \`c4\` for deployment-oriented views.
+- \`no-filter\` for the full context.
+
+When a render command depends on the active file, pass \`--source <file>\`.
+
+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
+
+external actor shopper
+    name = Shopper
+    technology = Browser
+    description = Browses products and places orders
+    links:
+        -> storefront
+
+external system payment_provider
+    name = Payment Provider
+    technology = HTTPS API
+    description = Authorizes card payments
+
+system storefront
+    name = Storefront
+    technology = Web application
+    description = Customer-facing commerce experience
+
+    container web_app
+        name = Web app
+        technology = SvelteKit, TypeScript
+        description = Renders product pages and checkout screens
+        links:
+            -> checkout_api
+                technology = HTTPS, JSON
+                description = Starts checkout and shows order status
+
+    service checkout_api
+        name = Checkout API
+        technology = Node.js, PostgreSQL
+        description = Prices carts, creates orders, and coordinates payment
+        links:
+            -> payment_provider
+                technology = HTTPS, JSON
+                description = Requests payment authorization
+
+        component order_controller
+            name = Order controller
+            technology = REST
+            responsibility = Accepts checkout requests and returns order status
+            links:
+                -> payment_client
+
+        component payment_client
+            name = Payment client
+            technology = HTTP client
+            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.0",
+  "version": "3.0.0-snapshot.2",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {