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

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,49 @@ 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
+        validation.md
+    examples/
+        layered-architecture.ai
+```
+
+Codex and Claude targets package the same Insight reference as skill folders:
+
+```shell
+archinsight skill init --target codex
+archinsight skill init --target claude
+```
+
+```text
+.archinsight/skills/codex/archinsight/
+    SKILL.md
+    agents/openai.yaml
+    references/
+    examples/
+
+.archinsight/skills/claude/archinsight/
+    SKILL.md
+    references/
+    examples/
+```
+
+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.
+
 ## 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.1";
 
 // 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,31 @@ 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 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));
+}
 async function loadProject(input) {
   const root = path.resolve(input);
   const sources = await readSources(root);
@@ -37703,7 +37731,7 @@ 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") {
+    if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".archinsight" || entry.name === "build") {
       continue;
     }
     const entryPath = path.join(directory, entry.name);
@@ -37896,6 +37924,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 +37955,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 +37976,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 +37985,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 +38007,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 +38020,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 +38074,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 +38089,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 +38099,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 +38110,634 @@ 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",
+    files: [
+      {
+        path: "archinsight.md",
+        content: genericSkillGuide()
+      },
+      ...sharedSkillFiles()
+    ]
+  };
+}
+function codexSkillPackage() {
+  return {
+    target: "codex",
+    defaultOutput: ".archinsight/skills/codex/archinsight",
+    entrypoint: "SKILL.md",
+    files: [
+      {
+        path: "SKILL.md",
+        content: codexSkillGuide()
+      },
+      {
+        path: "agents/openai.yaml",
+        content: codexOpenAiYaml()
+      },
+      ...sharedSkillFiles()
+    ]
+  };
+}
+function claudeSkillPackage() {
+  return {
+    target: "claude",
+    defaultOutput: ".archinsight/skills/claude/archinsight",
+    entrypoint: "SKILL.md",
+    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: "examples/layered-architecture.ai",
+      content: genericLayeredArchitectureExample()
+    }
+  ];
+}
+function skillPackageSuccess(projectRoot, outputRoot, skillPackage) {
+  const lines = [
+    `Generated ${skillPackage.target} Archinsight agent guide: ${displayPath(process.cwd(), outputRoot)}`,
+    "",
+    "Next steps:"
+  ];
+  if (skillPackage.target === "generic") {
+    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.target === "codex") {
+    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(`  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/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/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/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/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/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
+\`\`\`
+
+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 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
+`;
+}
 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.1",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {