likec4 1.59.3 → 1.60.0

package/skills/likec4-dsl/references/bridge-leanix-drawio.md

@@ -0,0 +1,42 @@
+# LeanIX bridge, Draw.io profile, and agent boundaries
+
+This reference is for tasks that touch **LeanIX**, **Draw.io export**, or **bridge artifacts**. It complements `cli.md` and the main skill rules.
+
+## Canonical source of truth
+
+- **LikeC4 DSL** (`.c4` / `.likec4`) is canonical. The bridge derives LeanIX-shaped inventory and Draw.io annotations from the resolved model.
+- **Agent Skills** teach DSL syntax and CLI contracts; they **do not** replace running `likec4 gen leanix …`, `likec4 sync leanix …`, or `likec4 export drawio --profile leanix`.
+
+## CLI commands (first-class)
+
+From the project root (see `@likec4/leanix-bridge` README for details):
+
+| Goal                              | Command                                                                  |
+| --------------------------------- | ------------------------------------------------------------------------ |
+| Manifest + dry-run + report       | `likec4 gen leanix dry-run -o out/bridge`                                |
+| Sync workflow (dry-run / plan)    | `likec4 sync leanix --dry-run -o out/bridge`                             |
+| Apply sync to LeanIX API          | `likec4 sync leanix --apply -o out/bridge` (requires `LEANIX_API_TOKEN`) |
+| Draw.io with bridge-managed cells | `likec4 export drawio --profile leanix -o ./diagrams`                    |
+
+**Draw.io default profile** (`default`): no `bridgeManaged` / `likec4Id` in styles.
+
+**Draw.io LeanIX profile** (`leanix`): adds `bridgeManaged=true`, `likec4Id`, `likec4Kind`, `likec4ViewId`, optional `likec4ProjectId` on vertices; `likec4RelationId` on edges — for round-trip and LeanIX alignment.
+
+Other useful flags: `likec4 export drawio --roundtrip` (embed layout in DSL comments), `--all-in-one`, `--uncompressed`.
+
+## Round-trip mental model
+
+1. **Export** Draw.io with `--profile leanix` so cells carry stable LikeC4 identities.
+2. **Parse** Draw.io back to DSL (`likec4` / generators): `likec4Id` on vertices and `likec4RelationId` on edges preserve FQN and relationship identity where the parser supports them (see `packages/generators` Draw.io tests).
+3. **After LeanIX sync**, `manifestToDrawioLeanixMapping(manifest)` maps `likec4Id` ↔ LeanIX fact sheet / relation ids for re-export or tooling.
+
+Do not invent bridge JSON shapes; generate them via the CLI or `@likec4/leanix-bridge` APIs documented in the package README.
+
+## Mapping config (YAML / JSON)
+
+Custom **LeanIX mapping** merges over defaults (`factSheetTypes`, `relationTypes`, `metadataToFields`). Invalid shapes (arrays instead of objects, non-string values, unknown top-level keys) are rejected with explicit errors when the config is normalized via `mergeWithDefault` / validation in `@likec4/leanix-bridge`.
+
+## MCP vs bridge
+
+- **MCP** (`likec4 mcp`, `@likec4/mcp`) exposes **read/query** tools over the LikeC4 workspace model (elements, views, relationships). It does **not** replace `likec4 gen leanix` or `likec4 sync leanix`.
+- For LeanIX artifacts, Draw.io leanix profile, or manifest dry-run, use the **CLI** (or programmatic `@likec4/leanix-bridge`) as documented above.

package/skills/likec4-dsl/references/cli.md

@@ -0,0 +1,139 @@
+# CLI Reference
+
+`likec4` is npm package that provides a CLI tool for working with LikeC4 models.
+Only essential commands/parameters are listed here, for full documentation use `likec4 help`, `likec4 <command> --help`.
+Examples use `bunx` to run the CLI, but you should use workspace's package manager (e.g. `bun`, `pnpm`, `npm`).
+If workspace is not a npm project, use `bunx` (if available) -> `pnpx` (if available) -> `npx` as a fallback.
+
+If workspace already has `likec4` as a dependency, check its version from package.json, make sure it is at least 1.53.0. Pin the version `bunx likec4@1.53.0 ...` otherwise.
+
+## Common Commands and Frequent Mistakes
+
+### ✅ Correct commands (use these)
+
+| Task              | Correct Command                                                       |
+| ----------------- | --------------------------------------------------------------------- |
+| Validate files    | `bunx likec4 validate --json --no-layout --file <file> [project-dir]` |
+| Start dev server  | `bunx likec4 serve [project-dir]`                                     |
+| Export PNG        | `bunx likec4 export png -o ./images [project-dir]`                    |
+| Build static site | `bunx likec4 build -o ./dist [project-dir]`                           |
+| List icons        | `bunx likec4 list-icons` or `bunx likec4 list-icons --group tech`     |
+
+### ❌ Common mistakes (avoid these)
+
+| Incorrect                                  | Why it fails                              | Correct                                  |
+| ------------------------------------------ | ----------------------------------------- | ---------------------------------------- |
+| `bunx likec4 check ...`                    | Command doesn't exist                     | Use `bunx likec4 validate ...`           |
+| `bunx likec4 lint ...`                     | Command doesn't exist                     | Use `bunx likec4 validate ...`           |
+| `bunx likec4 verify ...`                   | Command doesn't exist                     | Use `bunx likec4 validate ...`           |
+| `bunx likec4 export png --out-dir ./images` | Unknown flag (`--out-dir`)                | Use `-o ./images` or `--outdir ./images` |
+
+## `serve` (aliases: `start`, `dev`)
+
+Starts local server with live reload to preview diagrams (default port is 5173).
+
+```bash
+bunx likec4 serve [project-dir]
+bunx likec4 serve --port 3000 [project-dir]
+```
+
+When started, you can show the diagram to user in the browser by following the URL displayed in the console.
+To navigate to specific view, use the URL path `/view/<view-id>`.
+
+## `build` (alias: `bundle`)
+
+Build a static website for deployment.
+
+```bash
+bunx likec4 build -o ./dist [project-dir]
+```
+
+## `export`
+
+Export diagrams to various formats.
+
+```bash
+# PNG (requires Playwright)
+bunx likec4 export png -o ./images [project-dir]
+bunx likec4 export png --theme dark --flat -f "overview*" -o ./images [project-dir]
+
+# JSON model
+bunx likec4 export json -o model.json --pretty --skip-layout [project-dir]
+
+# DrawIO
+bunx likec4 export drawio --all-in-one -o ./diagrams [project-dir]
+```
+
+**export png** options: `--outdir` (`-o`), `--theme` [light|dark], `--flat`, `--filter` (`-f`, glob patterns), `--seq` (sequence layout for dynamic views), `--timeout` (default 15s)
+**export json** options: `--outfile` (`-o`, default "likec4.json"), `--pretty`, `--skip-layout`
+**export drawio** options: `--outdir` (`-o`), `--all-in-one`, `--roundtrip`, `--uncompressed`, `--profile` [default|leanix]
+
+### LeanIX bridge and Draw.io (LeanIX profile)
+
+Use these when the task is **LeanIX inventory**, **bridge artifacts**, or **Draw.io with stable bridge-managed ids** — not for generic DSL editing alone.
+
+| Task                                           | Command                                                                  |
+| ---------------------------------------------- | ------------------------------------------------------------------------ |
+| Manifest + LeanIX dry-run + report             | `bunx likec4 gen leanix dry-run -o out/bridge [project-dir]`             |
+| Sync workflow (review / apply)                 | `bunx likec4 sync leanix --dry-run -o out/bridge [project-dir]` / `bunx likec4 sync leanix --apply -o out/bridge [project-dir]` |
+| Draw.io with `likec4Id`, `bridgeManaged`, etc. | `bunx likec4 export drawio --profile leanix -o ./diagrams [project-dir]` |
+
+Full boundaries, round-trip notes, and MCP vs bridge: **`references/bridge-leanix-drawio.md`**.
+
+## `codegen` (aliases: `gen`, `generate`)
+
+Generate code artifacts from the model.
+
+```bash
+# TypeScript model (typed, with all views and elements)
+bunx likec4 gen model -o likec4-model.ts [project-dir]
+
+# React component
+bunx likec4 gen react -o dist/likec4-views.mjs [project-dir]
+
+# Web component JS bundle
+bunx likec4 gen webcomponent -o likec4.js -w c4 [project-dir]
+
+# Diagram formats
+bunx likec4 gen mermaid -o ./out      # .mmd files
+bunx likec4 gen plantuml -o ./out     # .puml files
+bunx likec4 gen d2 -o ./out           # .d2 files
+bunx likec4 gen dot -o ./out          # .dot files (Graphviz)
+```
+
+Shared options: `--outfile`/`--outdir` (`-o`), `--project` (`-p`), `--use-dot`
+
+## `mcp`
+
+Start MCP (Model Context Protocol) server for AI tool integration.
+
+```bash
+bunx likec4 mcp [workspace]                # stdio transport (default)
+bunx likec4 mcp --http [workspace]         # HTTP transport on port 33335
+bunx likec4 mcp -p 1234 [workspace]        # HTTP transport on custom port
+```
+
+Options: `--stdio` (default), `--http`, `--port` (`-p`, default 33335), `--use-dot`
+
+## `list-icons`
+
+List all available built-in icons. Fast, no workspace initialization needed.
+
+```bash
+bunx likec4 list-icons                        # all icons, one group:name per line
+bunx likec4 list-icons --format json          # grouped JSON object
+bunx likec4 list-icons --group aws            # only AWS icons
+bunx likec4 list-icons --group tech -f json   # tech icons as JSON
+```
+
+Options: `--format` (`-f`, `text` default or `json`), `--group` (`-g`, one of: `aws`, `azure`, `gcp`, `tech`, `bootstrap`)
+
+Icon groups: `aws` (~307 icons), `azure` (~614), `gcp` (~216), `tech` (~2000), `bootstrap` (~2051).
+
+## `format`
+
+Format LikeC4 source files in-place.
+
+```bash
+bunx likec4 format [workspace]
+```

package/skills/likec4-dsl/references/configuration.md

@@ -0,0 +1,266 @@
+# Project Configuration Reference
+
+LikeC4 projects are defined by a config file. The file's location determines project scope — all `.c4` files in the directory (and subdirectories) belong to that project.
+
+## Config File Names
+
+LikeC4 recognizes (in any order):
+
+| Format     | File names                                               |
+| ---------- | -------------------------------------------------------- |
+| JSON/JSON5 | `.likec4rc`, `.likec4.config.json`, `likec4.config.json` |
+| JavaScript | `likec4.config.js`, `likec4.config.mjs`                  |
+| TypeScript | `likec4.config.ts`, `likec4.config.mts`                  |
+
+## JSON Config Schema
+
+Always include `$schema` for validation and autocomplete:
+
+```json
+{
+  "$schema": "https://likec4.dev/schemas/config.json",
+  "name": "my-project"
+}
+```
+
+## All Options
+
+### `name` (required)
+
+Unique project identifier. Must not be `"default"`. Cannot contain `.`, `@`, or `#`.
+
+```json
+{ "name": "cloud-platform" }
+```
+
+### `title`
+
+Human-readable project title.
+
+```json
+{ "name": "cloud-platform", "title": "Cloud Platform Architecture" }
+```
+
+### `metadata`
+
+Arbitrary key-value pairs for custom project information.
+
+```json
+{
+  "metadata": {
+    "owner": "platform-team",
+    "domain": "payments",
+    "version": "2.0"
+  }
+}
+```
+
+### `contactPerson`
+
+Person involved in creating or maintaining the project.
+
+```json
+{ "contactPerson": "Jane Doe" }
+```
+
+### `include`
+
+Reference external directories containing `.c4` files.
+
+```json
+{
+  "include": {
+    "paths": ["../shared", "../common/specs"],
+    "maxDepth": 5,
+    "fileThreshold": 50
+  }
+}
+```
+
+| Property        | Type       | Default    | Description                            |
+| --------------- | ---------- | ---------- | -------------------------------------- |
+| `paths`         | `string[]` | (required) | Relative directory paths to scan       |
+| `maxDepth`      | `number`   | `3`        | Directory scan depth (1–20)            |
+| `fileThreshold` | `number`   | `30`       | Warn if loaded file count exceeds this |
+
+### `exclude`
+
+Glob patterns (picomatch) to exclude files. Default: `["**/node_modules/**"]`.
+
+```json
+{ "exclude": ["**/node_modules/**", "**/generated/**"] }
+```
+
+### `inferTechnologyFromIcon`
+
+Auto-derive `technology` from icon name when not set explicitly. Applies to `aws:`, `azure:`, `gcp:`, `tech:` icons. Default: `true`.
+
+```json
+{ "inferTechnologyFromIcon": false }
+```
+
+### `implicitViews`
+
+Auto-generate scoped views for elements without explicit views, enabling drill-down navigation. Default: `false`.
+
+```json
+{ "implicitViews": true }
+```
+
+### `imageAliases`
+
+Shortcuts for image directory paths. Default alias `@` points to `./images`.
+
+```json
+{
+  "imageAliases": {
+    "@": "./images",
+    "@shared": "../../shared-images"
+  }
+}
+```
+
+### `manualLayouts`
+
+Configure where manual layout data is stored.
+
+```json
+{
+  "manualLayouts": {
+    "outDir": ".likec4"
+  }
+}
+```
+
+`outDir` is relative to the config file location. Default: `".likec4"`.
+
+### `styles`
+
+Theme customization and default styling.
+
+```json
+{
+  "styles": {
+    "theme": {
+      "colors": {
+        "primary": "#FF6B6B",
+        "secondary": "rgba(37,99,235,1)"
+      }
+    },
+    "defaults": {
+      "border": "dashed",
+      "opacity": 100,
+      "size": "md",
+      "relationship": {
+        "color": "gray",
+        "line": "dashed"
+      },
+      "view": {
+        "routing": "ortho"
+      }
+    }
+  }
+}
+```
+
+Set `styles.defaults.view.routing` to `spline` for curved relationships or `ortho` for right-angle bends. The default is `spline`. A view's `routing` property or `autoLayout` routing parameter overrides this project default. See [Edge routing](./views.md#edge-routing) for precedence and limitations.
+
+### `extends`
+
+Inherit styles from other config files (JSON only). Single path or array.
+
+```json
+{ "extends": "../shared/likec4.config.json" }
+{ "extends": ["../shared/base.json", "../shared/theme.json"] }
+```
+
+### `landingPage`
+
+Configure the landing page of the generated site.
+
+Redirect to index view:
+
+```json
+{ "landingPage": { "redirect": true } }
+```
+
+Show only specific views:
+
+```json
+{ "landingPage": { "include": ["overview", "cloud-detail"] } }
+```
+
+Hide specific views:
+
+```json
+{ "landingPage": { "exclude": ["internal-debug"] } }
+```
+
+### `generators` (TypeScript/JS config only)
+
+Custom generators that produce output from the model.
+
+```typescript
+import { defineConfig } from 'likec4'
+
+export default defineConfig({
+  name: 'my-project',
+  generators: {
+    'my-gen': async ({ likec4model, ctx }) => {
+      const elements = likec4model.elements()
+      await ctx.write({
+        path: 'output.json',
+        content: JSON.stringify(elements, null, 2),
+      })
+    },
+  },
+})
+```
+
+Run with: `likec4 gen my-gen`
+
+## Multi-Project Setup
+
+Each config file in the workspace defines a separate project. Files belong to the project of the nearest config file in the directory hierarchy.
+
+```
+workspace/
+├─ project-a/
+│  ├─ likec4.config.json    ← project "a"
+│  ├─ model.c4
+│  └─ views.c4
+├─ project-b/
+│  ├─ likec4.config.json    ← project "b"
+│  └─ model.c4
+└─ shared/
+   └─ common.c4             ← included via "include.paths"
+```
+
+Use `include.paths` to share `.c4` files across projects.
+
+## Minimal Starter Config
+
+```json
+{
+  "$schema": "https://likec4.dev/schemas/config.json",
+  "name": "my-project",
+  "title": "My Architecture"
+}
+```
+
+**Important:** Always include `"$schema"` (recommended) — it enables IDE autocomplete and validation for your config file.
+
+### Common Mistake: Missing $schema
+
+```json
+// ❌ Missing $schema — no IDE validation/autocomplete
+{
+  "name": "my-project"
+}
+
+// ✅ Correct — with schema for IDE support
+{
+  "$schema": "https://likec4.dev/schemas/config.json",
+  "name": "my-project"
+}
+```

package/skills/likec4-dsl/references/deployment.md

@@ -0,0 +1,160 @@
+# Deployment (LikeC4 DSL)
+
+The `deployment` block maps logical model elements to physical infrastructure nodes using `instanceOf`. It uses `deploymentNode` kinds from the specification.
+
+**Key rules:**
+
+- Deployment inherits ALL relationships from the logical model automatically.
+- Additional deployment-level relationships can be defined inline (same syntax as in model).
+- Use named instances (`id = instanceOf ELEMENT`) when multiple instances of the same element exist within the same deployment node.
+- Anonymous `instanceOf ELEMENT` (no name) is fine when there is only one instance per node.
+- In deployment-view filters, instance tags are cumulative with logical element tags.
+- In deployment-view filters, instance metadata replaces logical element metadata when present; otherwise logical metadata is the fallback.
+
+## Syntax
+
+```likec4
+deployment {
+  IDENTIFIER = DEPLOYMENT_KIND {
+    TAGS
+    PROPERTIES
+
+    // Anonymous instance — fine when there is only one instance per node
+    instanceOf ELEMENT_ID
+
+    // Named instance — required when same element appears multiple times in the same node
+    IDENTIFIER = instanceOf ELEMENT_ID {
+      TAGS
+      PROPERTIES
+    }
+  }
+}
+```
+
+## Basic Example
+
+```likec4
+specification {
+  element webapp
+  deploymentNode vm
+}
+model {
+  webapp myapp
+}
+deployment {
+  vm vm1 {
+    instanceOf myapp           // anonymous: single instance
+  }
+  vm vm2 {
+    // Named: two replicas of the same logical element in one node
+    instance1 = instanceOf myapp
+    instance2 = instanceOf myapp
+  }
+}
+```
+
+## Multi-Environment Pattern
+
+```likec4
+specification {
+  deploymentNode environment { notation "Environment"; style { color gray } }
+  deploymentNode zone         { notation "Network Zone" }
+  deploymentNode vm
+}
+
+deployment {
+  environment prod {
+    zone AppTier {
+      vm appVm {
+        primary   = instanceOf cloud.api
+        secondary = instanceOf cloud.api  // named: two replicas
+      }
+    }
+    zone DataTier {
+      vm dbVm { instanceOf cloud.db }
+    }
+  }
+  environment staging {
+    vm stagingApp { instanceOf cloud.api }
+    vm stagingDb  { instanceOf cloud.db }
+  }
+}
+```
+
+## Deployment Relationships
+
+Additional relationships can be defined between deployment nodes or named instances:
+
+```likec4
+deployment {
+  environment prod {
+    zone AppTier {
+      vm appVm {
+        primary = instanceOf cloud.api
+      }
+    }
+    zone DataTier {
+      vm dbVm { instanceOf cloud.db }
+    }
+    // Deployment-level relationship not in the logical model
+    AppTier -> DataTier "internal traffic" { technology "TCP/5432" }
+    // Bidirectional, `-[kind]<->` is also supported
+    AppTier <-> DataTier "replicates"
+  }
+}
+```
+
+## Deployment View Filtering
+
+Deployment views use normal `where` filters, with deployment-aware endpoint values:
+
+- Deployment instance tags = logical element tags + instance tags.
+- Deployment instance kind = logical element kind.
+- Deployment instance metadata replaces logical metadata as a whole when present, otherwise logical metadata is the fallback.
+- Nested children of a deployed instance use the logical child tags, kind, and metadata.
+- Deployment node tags, kind, and metadata come from the deployment model.
+- Tags are not inherited from parent deployment nodes.
+
+Relationship endpoint filters use those same rules:
+
+```likec4
+views {
+  deployment view prod {
+    include * -> *
+    exclude * -> *
+      where target.metadata.zone is "restricted"
+  }
+}
+```
+
+Use unqualified `metadata.*` for the relationship's own metadata; use `source.metadata.*` or `target.metadata.*` for endpoint metadata.
+
+## Deployment View Navigation
+
+Element `with { navigateTo VIEW_ID }` overrides are supported for deployment nodes and instances:
+
+```likec4
+views {
+  deployment view prod {
+    include server with {
+      navigateTo server_deployment
+    }
+  }
+  deployment view server_deployment {
+    include server.*
+  }
+}
+```
+
+The target must be an existing view. Overrides are view-local, support selectors and `where` filters,
+and the last matching navigation override wins. Other element `with` properties remain unsupported;
+use local `style` rules for deployment-view styling.
+
+## Named vs. Anonymous: When It Matters
+
+| Scenario                                        | Use                                           |
+| ----------------------------------------------- | --------------------------------------------- |
+| Single instance of element in node              | Anonymous: `instanceOf cloud.api`             |
+| Multiple instances of same element in same node | Named: `primary = instanceOf cloud.api`       |
+| Strict eval requires named instance identifier  | Named: `IDENTIFIER = instanceOf ELEMENT`      |
+| Deployment view needs to distinguish replicas   | Named: each gets a unique node in the diagram |