likec4 1.60.0 → 1.61.0

package/react/rolldown-runtime-CfRud99p.js

@@ -0,0 +1 @@
+var e=Object.create,t=Object.defineProperty,__name=(e,n)=>t(e,`name`,{value:n,configurable:!0}),n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,__commonJSMin=(e,t)=>()=>(t||(e((t={exports:{}}).exports,t,t.exports),e=null),t.exports),__copyProps=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},__toESM=(n,r,o)=>(o=n==null?{}:e(i(n)),__copyProps(r||!n||!n.__esModule||!a.call(n,`default`)?t(o,`default`,{value:n,enumerable:!0}):o,n));export{__name as n,__toESM as r,__commonJSMin as t};

package/skills/likec4-dsl/SKILL.md

@@ -10,10 +10,10 @@ Architecture-as-code tool. Describe systems in `.c4`/`.likec4` files and LikeC4
 ## Rules
 
 1. **Projects** - it is possible to have multiple likec4 projects in a workspace, project is determined by presence of a config file (`.likec4rc`, `likec4.config.{ts,js,json}`). LikeC4 files belong to the project of the nearest config file in the directory hierarchy.
-2. **Top-level statements** — only `import`, `specification`, `model`, `deployment`, `views`, `global` are allowed. Blocks can repeat, but at least one per file must be present.
+2. **Top-level statements** — only `import`, `specification`, `model`, `deployment`, `views`, `global`, `diff` are allowed. Blocks can repeat, but at least one per file must be present.
 3. **Multi-file merge** — Top-level blocks across files are merged. For example, `model { ... }` blocks present in multiple files, parsed separately, and then merged into a single model.
 4. **Strings** — `'single'`, `"double"` — all support multi-line. Escape quotes with backslash: `\'` or `\"`. In a `title`, escape `\/` to include a literal `/` without it being read as a view-folder separator.
-5. **Markdown** — properties like `summary`/`description`/`notes` can contain Markdown. Use triple quotes `'''` or `"""`. Begin a new line after opening quotes and indent Markdown content for better formatting and syntax highlighting.
+5. **Markdown** — properties like `summary`/`description`/`notes` can contain Markdown. Use triple quotes `'''` or `"""`. Begin a new line after opening quotes and indent Markdown content for better formatting and syntax highlighting. Markdown can link to elements and views: `[[cloud.api]]`, `[[cloud.api|API]]`, `[[view:index]]` (see "Element links in Markdown" below).
 6. **Comments** — `// single line` and `/* multi-line */` comments supported anywhere.
 7. **Identifier** — letters, digits, hyphens, underscores only. No dots (dots are FQN separators). Can't start with a digit. Examples: `customer`, `payment-service`, `frontendApp`, `queue-1`. **Critical:** `payment-api` is valid; `payment.api` is NOT an identifier (dots separate FQN hierarchy). See `references/identifier-validity.md`.
 8. **FQN** — Fully Qualified Name (FQN) is a dot-separated path to an element, MUST be unique within the project. Examples: `customer`, `saas.backend.payment-service.paymentsApi`, `infra.eu.zone1.node1`.
@@ -95,6 +95,7 @@ For strict command/snippet prompts, keep a compact loop:
 - deployment naming requirement satisfied
 - relationship matcher specificity (`kind`, `title` when needed)
 - dynamic view exactness: return arrows, chain form, single parallel block when requested, flow-control block placement (`alt` branches, no nested `parallel`, try/catch/finally order)
+- Markdown links: `[[fqn]]` only inside `'''`/`"""`, full FQN that exists in the model, `\\|` as label separator inside tables
 
 3. **Finalize** by fixing in place (no extra alternatives unless explicitly requested).
 
@@ -119,6 +120,7 @@ pnpm dlx likec4 validate --json --no-layout --file <edited-file> <project-dir>
 - `--json` — structured output (stdout), logging goes to stderr
 - `--no-layout` — skip layout drift checks (faster, only syntax+semantic)
 - `--file <path>` — use with `--json` to scope results to the edited files. Without `--json`, text output still prints all diagnostics. Repeat once per edited source file.
+- `--max-warnings <n>` — fail (`valid: false`, exit code 1) when there are more than `n` warnings; `0` fails on any warning. Without it, warnings never fail validation.
 - `<project-dir>` — path to the project directory
 - There is **no** `likec4 check` command; use `likec4 validate`.
 
@@ -139,11 +141,15 @@ Example output:
       "range": { "start": { "line": 5, "character": 2 }, "end": { "line": 5, "character": 20 } }
     }
   ],
+  "warnings": [], // same shape as errors
+  "maxWarnings": null, // value of --max-warnings, null when not given
   "stats": {
     "totalFiles": 100, // Total number of files in the project
     "totalErrors": 500, // Total number of errors in the project
+    "totalWarnings": 3, // Total number of warnings in the project
     "filteredFiles": 1, // Number of files that match the --file filter
-    "filteredErrors": 1 // Number of errors in the filtered files
+    "filteredErrors": 1, // Number of errors in the filtered files
+    "filteredWarnings": 0 // Number of warnings in the filtered files
   }
 }
 ```
@@ -155,6 +161,7 @@ Field semantics (must be explicit in answers):
 - `filteredFiles`: count of files actually included by repeated `--file` filters
 - `filteredErrors`: errors in the filtered subset only
 - `totalErrors`: errors across the full project model
+- `filteredWarnings`: warnings in the filtered subset only; `--max-warnings` limits this count
 
 Example edge case: if you pass 3 files but one is `likec4.config.json`, `filteredFiles` may be `2` because config JSON is not a `.c4`/`.likec4` source file for DSL validation.
 
@@ -241,6 +248,43 @@ For strict repair prompts about deployment views, the safe answer is **local `st
 
 Mini-reminder: in deployment views, treat `include ... with {}` and `global style ...` as unsupported repair patterns. Use a local `style ... {}` rule inside the deployment view instead.
 
+### Element links in Markdown (`[[fqn]]`)
+
+```likec4
+model {
+  cloud = system 'Cloud' {
+    ui = container 'Web UI'
+    api = container 'API' {
+      description '''
+        Called by [[cloud.ui]] and [[cloud.ui|the frontend]].
+        See [[view:index]] for context.
+        Literal brackets: \\[[not a link]]
+
+        | Caller                | Protocol |
+        | --------------------- | -------- |
+        | [[cloud.ui\\|Web UI]] | HTTPS    |
+      '''
+    }
+  }
+}
+```
+
+- `[[cloud.ui]]` — element link, rendered with the element title
+- `[[cloud.ui|UI]]` — element link with custom label `UI`
+- `[[view:index]]` — view link, rendered with the view title
+- `\\[[` — literal `[[`, not a link
+- `[[cloud.ui\\|UI]]` — labelled link inside a Markdown table cell
+
+Truth card:
+
+- Only in Markdown values (`'''…'''` / `"""…"""`): `description`, `summary`, `notes`, `title`, `technology`, metadata values. Plain `'…'` / `"…"` strings, inline code and fenced code blocks are not scanned.
+- Target is an **absolute FQN** in the **current project**: no short names, no `this`, no imported elements. `view:` is the only namespace; any other `prefix:` is reserved.
+- Escaping follows DSL strings (`\\` → `\` before Markdown sees it): literal `[[` is `\\[[`; inside tables write `\\|`, a bare `|` splits the cell.
+- Missing element/view or unknown `prefix:` → **warning**, not error. `likec4 validate` lists it under `warnings` but stays `valid: true` unless `--max-warnings` is given (`--max-warnings 0` fails on any warning); editors show it as an LSP diagnostic.
+- Exports and MCP replace links with the title (or label); the DSL generator keeps `[[…]]`.
+
+Agent guidance: in descriptions prefer `[[fqn]]` over retyping an element's name (title stays in sync, readers can click it); link only FQNs that exist in the model; use `\\|` in tables.
+
 ## LikeC4 Project Configuration
 
 Config file (`likec4.config.json`, `.likec4rc`, or `likec4.config.{ts,js}`) defines a project. Its location sets the project scope (LikeC4 files belong to the project of the nearest config file in the directory hierarchy).
@@ -384,12 +428,13 @@ Return-arrow precision:
 
 ## Anti-Patterns to Avoid in Strict Prompts
 
-| Anti-pattern                                                       | Why it fails                                   | Correct behavior                                          |
-| ------------------------------------------------------------------ | ---------------------------------------------- | --------------------------------------------------------- |
-| Substituting command families (`check`/`build`) for `validate`     | Breaks exact command contract                  | Keep `likec4 validate`                                    |
-| Inventing/guessing flags                                           | Creates non-portable invalid commands          | Use canonical documented flags only                       |
-| Multiple alternative snippets for one strict ask                   | Reduces precision; fails strict-output grading | Output one final answer unless alternatives are requested |
-| Extending typed relationship without kind/title in ambiguous graph | Can target wrong relationship                  | Match with source + target + kind (+ title when needed)   |
+| Anti-pattern                                                       | Why it fails                                                                  | Correct behavior                                          |
+| ------------------------------------------------------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------------- |
+| Substituting command families (`check`/`build`) for `validate`     | Breaks exact command contract                                                 | Keep `likec4 validate`                                    |
+| Inventing/guessing flags                                           | Creates non-portable invalid commands                                         | Use canonical documented flags only                       |
+| Multiple alternative snippets for one strict ask                   | Reduces precision; fails strict-output grading                                | Output one final answer unless alternatives are requested |
+| Extending typed relationship without kind/title in ambiguous graph | Can target wrong relationship                                                 | Match with source + target + kind (+ title when needed)   |
+| Short or guessed FQN in `[[…]]`, e.g. `[[api]]`                    | Broken link is only a warning; validate passes unless `--max-warnings` is set | Use an existing full FQN: `[[cloud.backend.api]]`         |
 
 ## Common Mistakes & Debugging
 
@@ -409,20 +454,21 @@ When a model errors or an eval answer seems wrong, load `references/troubleshoot
 
 Load a reference file when the task involves the corresponding topic. Claude reads SKILL.md first; these files are loaded on demand only when needed.
 
-| File                                         | Purpose — load when...                                                                                                          |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `references/specification.md`                | Writing/editing `specification { }` blocks, defining element/deploymentNode/relationship/tag/color kinds                        |
-| `references/model.md`                        | Writing/editing `model { }` blocks, element hierarchy, relationships, `extend` patterns, property names                         |
-| `references/deployment.md`                   | Writing/editing `deployment { }` blocks, `instanceOf`, named instances, multi-environment topology, deployment metadata filters |
-| `references/style-tokens-colors.md`          | Applying colors, shapes, icons, or relationship line styles; need exact token names                                             |
-| `references/views.md`                        | Writing views, include/exclude rules, style rules in views, groups, autoLayout, global predicates                               |
-| `references/predicates.md`                   | Complex `where` conditions, metadata filters, `with` overrides, global predicate groups, reusable predicates                    |
-| `references/include-predicates-wildcards.md` | Wildcard confusion suspected (`*` vs `_` vs `**`); need exact scoped-view semantics                                             |
+| File                                         | Purpose — load when...                                                                                                                    |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `references/specification.md`                | Writing/editing `specification { }` blocks, defining element/deploymentNode/relationship/tag/color kinds                                  |
+| `references/model.md`                        | Writing/editing `model { }` blocks, element hierarchy, relationships, `extend` patterns, property names, `[[fqn]]` links                  |
+| `references/deployment.md`                   | Writing/editing `deployment { }` blocks, `instanceOf`, named instances, multi-environment topology, deployment metadata filters           |
+| `references/style-tokens-colors.md`          | Applying colors, shapes, icons, or relationship line styles; need exact token names                                                       |
+| `references/views.md`                        | Writing views, include/exclude rules, style rules in views, groups, autoLayout, global predicates                                         |
+| `references/predicates.md`                   | Complex `where` conditions, metadata filters, `with` overrides, global predicate groups, reusable predicates                              |
+| `references/include-predicates-wildcards.md` | Wildcard confusion suspected (`*` vs `_` vs `**`); need exact scoped-view semantics                                                       |
 | `references/dynamic-views.md`                | Writing dynamic views: steps, return arrows, chained steps, flow-control blocks (`parallel`/`opt`/`loop`/`alt`/`try`), `variant sequence` |
-| `references/identifier-validity.md`          | Identifier vs FQN confusion; "dots in names" errors; understanding FQN construction                                             |
-| `references/relationships-bidirectional.md`  | Bidirectional relationship syntax and `<->` view predicate patterns                                                             |
-| `references/bridge-leanix-drawio.md`         | LeanIX bridge · `drawio --profile leanix` · round-trip · mapping · MCP vs bridge · sync/artifacts/managed cells                 |
-| `references/cli.md`                          | Full CLI reference: serve, build, export, codegen, mcp, format; flag disambiguation                                             |
-| `references/configuration.md`                | Project config options, multi-project setup, include/exclude paths, generators                                                  |
-| `references/examples.md`                     | Compact real-world examples: extend, groups, globals, dynamic views, deployment, rank                                           |
-| `references/troubleshooting.md`              | Errors, unexpected output, eval failures — 6 error tables, 5-step debug workflow, 7 best practices                              |
+| `references/identifier-validity.md`          | Identifier vs FQN confusion; "dots in names" errors; understanding FQN construction                                                       |
+| `references/relationships-bidirectional.md`  | Bidirectional relationship syntax and `<->` view predicate patterns                                                                       |
+| `references/diffs.md`                        | Planned model changes (`diff` blocks), applying or discarding them, safe delete of elements                                               |
+| `references/bridge-leanix-drawio.md`         | LeanIX bridge · `drawio --profile leanix` · round-trip · mapping · MCP vs bridge · sync/artifacts/managed cells                           |
+| `references/cli.md`                          | Full CLI reference: serve, build, export, codegen, mcp, format; flag disambiguation                                                       |
+| `references/configuration.md`                | Project config options, multi-project setup, include/exclude paths, generators                                                            |
+| `references/examples.md`                     | Compact real-world examples: extend, groups, globals, dynamic views, deployment, rank                                                     |
+| `references/troubleshooting.md`              | Errors, unexpected output, eval failures — 6 error tables, 5-step debug workflow, 7 best practices                                        |

package/skills/likec4-dsl/evals/evals-public.json

@@ -197,6 +197,11 @@
       "id": 38,
       "prompt": "Start your answer with exactly `Invalid.` or `Valid.` on the first line. Is this dynamic view valid?\n```likec4\ndynamic view flow {\n  alt {\n    loop {\n      a -> b\n    }\n  }\n}\n```\nExplain in one sentence why, then give the corrected minimal snippet that keeps the `loop` but satisfies the `alt`-branch rule.",
       "files": []
+    },
+    {
+      "id": 39,
+      "prompt": "The model has `cloud.ui` (title \"Web UI\") and `cloud.api`, and a view `index`. Give me a minimal paste-ready `description` property for `cloud.api` that (1) links to `cloud.ui` in a sentence so the element title is shown, (2) links to the view `index`, and (3) has a Markdown table with one row whose first cell links to `cloud.ui` with the label `Frontend`. Snippet first, then one sentence on what happens if a linked FQN does not exist.",
+      "files": []
     }
   ]
 }

package/skills/likec4-dsl/evals/grading-spec.json

@@ -224,7 +224,7 @@
       "files": [],
       "expectations": [
         "The response identifies that `styles` is an invalid top-level statement.",
-        "The response mentions allowed top-level statements (`import`, `specification`, `model`, `deployment`, `views`, `global`).",
+        "The response mentions allowed top-level statements (`import`, `specification`, `model`, `deployment`, `views`, `global`, `diff`).",
         "The corrected file uses only allowed top-level statements.",
         "The corrected DSL demonstrates styling intent via valid constructs (e.g., `global styleGroup` and applying in `views`).",
         "The output is a minimal valid LikeC4 file, not only prose."
@@ -543,6 +543,20 @@
         "The corrected snippet is minimal and syntactically valid LikeC4 DSL."
       ],
       "grading_guidance": "This is a contrastive placement-rule eval. The exact opening verdict `Invalid.` and the alt-branch rule are the primary signals. Reject answers that call the snippet valid, or that 'fix' it by removing the `loop` or by dropping the `alt` block entirely instead of nesting the loop inside a branch. `if` is an accepted alias for `when`."
+    },
+    {
+      "id": 39,
+      "expected_output": "The response starts with a `description '''…'''` snippet that uses `[[cloud.ui]]`, `[[view:index]]` and, inside the table, `[[cloud.ui\\\\|Frontend]]`, then states that a missing target is a validation warning, not an error.",
+      "files": [],
+      "expectations": [
+        "The response starts with the snippet (snippet-first), not prose.",
+        "The `description` uses a triple-quoted Markdown string (`'''` or `\"\"\"`), not a plain `'…'` string.",
+        "The sentence link is `[[cloud.ui]]` (full FQN, no label), so the element title is rendered.",
+        "The view link is `[[view:index]]`.",
+        "The table cell link escapes the label separator as `\\\\|`: `[[cloud.ui\\\\|Frontend]]`.",
+        "The response says a link to a missing element or view produces a warning (the model still builds; `likec4 validate` does not fail on it)."
+      ],
+      "grading_guidance": "Primary signals are the triple-quoted Markdown value, `[[view:index]]`, and the `\\\\|` escape inside the table. Reject a bare `|` inside the table cell, a single `\\|`, short names such as `[[ui]]`, `this`, or a Markdown `[text](url)` link instead of `[[…]]`. Do not require the `Frontend` label outside the table. Claiming that a broken link is a validation error is wrong."
     }
   ],
   "default_execution_checks": [

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

@@ -14,19 +14,22 @@ If workspace already has `likec4` as a dependency, check its version from packag
 | Task              | Correct Command                                                       |
 | ----------------- | --------------------------------------------------------------------- |
 | Validate files    | `bunx likec4 validate --json --no-layout --file <file> [project-dir]` |
+| Fail on warnings  | `bunx likec4 validate --max-warnings 0 [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`     |
+| Apply a diff      | `bunx likec4 diff apply <diff> [--dry-run] [project-dir]`             |
+| Safe delete       | `bunx likec4 safe-delete <fqn> --dry-run [project-dir]`               |
 
 ### ❌ 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` |
+| 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`)
 
@@ -48,6 +51,32 @@ Build a static website for deployment.
 bunx likec4 build -o ./dist [project-dir]
 ```
 
+Preview the build with `bunx likec4 preview -o ./dist [project-dir]`.
+
+## App config (experimental)
+
+Newer versions of the CLI read `likec4.app.config.ts` (also `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`) from the project directory or the current directory.
+Check that `likec4 build --help` lists `--app-config` before relying on it.
+
+```ts
+// likec4.app.config.ts
+import { defineAppConfig } from 'likec4/config'
+
+export default defineAppConfig({
+  title: 'My Architecture',
+  theme: 'dark', // 'light' | 'dark'
+  base: '/pages/',
+  customization: './likec4.customization.tsx', // UI overrides, see docs
+  build: { outDir: './dist' },
+  server: { port: 3000 },
+})
+```
+
+- Read by `serve`, `build`, `preview`, `export png|jpg`, `codegen react`, `codegen webcomponent`.
+- Flags win over the file. `--app-config <file>` points to another file, `--no-app-config` ignores it.
+- Paths in the file are relative to the file; unknown options are errors.
+- This is not `likec4.config.json` (the project configuration).
+
 ## `export`
 
 Export diagrams to various formats.
@@ -72,11 +101,11 @@ bunx likec4 export drawio --all-in-one -o ./diagrams [project-dir]
 
 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]`             |
+| 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]` |
+| 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`**.
 

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

@@ -6,11 +6,11 @@ LikeC4 projects are defined by a config file. The file's location determines pro
 
 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`                  |
+| Format     | File names                                                   |
+| ---------- | ------------------------------------------------------------ |
+| JSON/JSON5 | `.likec4rc`, `.likec4.config.json`, `likec4.config.json`     |
+| JavaScript | `likec4.config.js`, `likec4.config.cjs`, `likec4.config.mjs` |
+| TypeScript | `likec4.config.ts`, `likec4.config.cts`, `likec4.config.mts` |
 
 ## JSON Config Schema
 

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

@@ -0,0 +1,52 @@
+# Model diffs and safe delete
+
+A `diff` is a named, planned change of the model (for example, an RFC).
+The model does not change until the diff is applied.
+
+```likec4
+diff rfc1 'RFC-1: Payments service' {
+  description 'Replace the SOAP gateway with a Payments service'
+
+  remove {
+    shop.legacyPayments                      // element, its descendants and their relationships
+    shop.orders -> bank 'checks fraud score' // relationship: source, target, kind, title and direction must match
+  }
+
+  add {
+    extend shop {
+      payments = container 'Payments Service'
+    }
+    shop.orders -> shop.payments 'requests payments'
+    extend shop.orders {
+      #next // tags, links and metadata for an existing element
+    }
+  }
+}
+```
+
+## Rules
+
+- `remove` lists elements and relationships that exist in the model. Use full FQNs.
+- `add` has the syntax of a `model` block: elements, relationships, `extend` of elements.
+- A diff cannot extend relationships, cannot remove elements added by a diff, and cannot add an element that exists.
+- Diffs that change the same elements or relationships, or use what another diff adds, overlap:
+  both get a warning, and `diff apply` needs `--accept-overlaps` after the owners of the diffs agreed.
+- Diffs with the same name in several files are merged.
+- Views can reference elements added by a diff: the model "as is" ignores these references.
+
+## Apply, discard, safe delete
+
+```sh
+bunx likec4 diff list [project-dir]
+bunx likec4 diff apply rfc1 --dry-run [project-dir]  # print the changes of each file
+bunx likec4 diff apply rfc1 [project-dir]            # merge `add` into the model, remove `remove` entries, delete the diff
+bunx likec4 diff apply rfc1 --accept-overlaps [project-dir]  # only after the owners of overlapping diffs agreed
+bunx likec4 diff discard rfc1 [project-dir]          # delete the diff, the model does not change
+bunx likec4 safe-delete shop.legacyPayments --dry-run [project-dir]
+bunx likec4 safe-delete shop.legacyPayments --orphans --scoped-views --dynamic-steps [project-dir]
+```
+
+If `likec4 diff --help` fails, the installed version predates model diffs.
+`apply` and `safe-delete` never edit other diffs: they report the diffs they break (exit code 1).
+`apply` keeps only the model changes: the title, description and comments of the diff are deleted with it.
+Comments inside the braces of an added element move with the element. Put lasting notes in an element `description`.

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

@@ -143,7 +143,7 @@ dynamic view checkout {
     api -> notifications "send confirmation"
   }
 
-  payments <- api "payment result" {
+  api <- payments "payment result" {
     navigateTo payment-detail        // link to another view
   }
 
@@ -262,7 +262,7 @@ views {
     exclude * -> * where target.metadata.zone is "restricted"
 
     // Wildcard with expansion
-    include cloud._                  // direct children only
+    include cloud._                  // direct children that have relationships with the accumulated result
     include cloud.**                 // all descendants
   }
 }

package/skills/likec4-dsl/references/identifier-validity.md

@@ -12,24 +12,24 @@ identifier = /^[a-zA-Z_][a-zA-Z0-9_-]*$/
 
 ## Valid examples
 
-| Valid | Why |
-|---|---|
-| `payment-api` | hyphens allowed |
-| `paymentAPI` | camelCase allowed |
-| `payment_service` | underscores allowed |
-| `service1` | digits allowed (not at start) |
-| `_internal` | underscore at start allowed |
-| `PaymentService` | PascalCase allowed |
+| Valid             | Why                           |
+| ----------------- | ----------------------------- |
+| `payment-api`     | hyphens allowed               |
+| `paymentAPI`      | camelCase allowed             |
+| `payment_service` | underscores allowed           |
+| `service1`        | digits allowed (not at start) |
+| `_internal`       | underscore at start allowed   |
+| `PaymentService`  | PascalCase allowed            |
 
 ## Invalid examples
 
-| Invalid | Why | Correct form |
-|---|---|---|
+| Invalid       | Why                                               | Correct form                  |
+| ------------- | ------------------------------------------------- | ----------------------------- |
 | `payment.api` | **dots are FQN separators**, not identifier chars | `payment-api` or `paymentApi` |
-| `payment api` | spaces not allowed | `payment-api` |
-| `1payment` | cannot start with digit | `payment1` |
-| `payment-` | cannot end with hyphen | `payment` |
-| `payment@api` | special chars not allowed | `payment-api` |
+| `payment api` | spaces not allowed                                | `payment-api`                 |
+| `1payment`    | cannot start with digit                           | `payment1`                    |
+| `payment-`    | cannot end with hyphen                            | `payment`                     |
+| `payment@api` | special chars not allowed                         | `payment-api`                 |
 
 ## Critical: dots vs. hyphens
 
@@ -43,23 +43,23 @@ model {
 }
 ```
 
-**Correct identifier:** `payment-api` (with hyphen)  
+**Correct identifier:** `payment-api` (with hyphen)\
 **Incorrect identifier:** `payment.api` (dots are FQN syntax, not part of the name)
 
 ## Use in different contexts
 
-| Context | Rule | Example |
-|---|---|---|
-| **Element name** | Must be valid identifier | `service name = api "payment api"` ✓ |
-| **Tag name** | Must be valid identifier | `tag critical` ✓, `tag #critical` ✗ |
-| **Relationship kind** | Must be valid identifier | `-[async]->` ✓, `-[async-queue]->` ✓ |
-| **Kind name** | Must be valid identifier | `element service`, `deploymentNode vm` ✓ |
-| **Metadata key** | Must be valid identifier | `metadata { api_version "1.0" }` ✓ |
-| **Color name** | Must be valid identifier (or hex) | `color primary`, `color custom-blue` ✓ |
+| Context               | Rule                              | Example                                  |
+| --------------------- | --------------------------------- | ---------------------------------------- |
+| **Element name**      | Must be valid identifier          | `service name = api "payment api"` ✓     |
+| **Tag name**          | Must be valid identifier          | `tag critical` ✓, `tag #critical` ✗      |
+| **Relationship kind** | Must be valid identifier          | `-[async]->` ✓, `-[async-queue]->` ✓     |
+| **Kind name**         | Must be valid identifier          | `element service`, `deploymentNode vm` ✓ |
+| **Metadata key**      | Must be valid identifier          | `metadata { api_version "1.0" }` ✓       |
+| **Color name**        | Must be valid identifier (or hex) | `color primary`, `color custom-blue` ✓   |
 
 ## When referencing by FQN
 
-Once defined, elements are referenced using their fully qualified names (FQNs), which *do* use dots:
+Once defined, elements are referenced using their fully qualified names (FQNs), which _do_ use dots:
 
 ```likec4
 model {
@@ -81,10 +81,10 @@ deployment {
 
 ## Summary
 
-| Check | Valid | Invalid |
-|---|---|---|
-| Identifier rule | `[a-zA-Z_][a-zA-Z0-9_-]*` | Contains dots, spaces, or special chars |
-| Hyphens allowed? | **Yes** in identifiers | Not dots |
-| Dots allowed? | **Only in FQNs** (for scope separation) | Never in a single identifier name |
-| `payment-api` | ✓ identifier | — |
-| `payment.api` | ✗ identifier, but valid as FQN if `payment` and `api` are nested parents/children | — |
+| Check            | Valid                                                                             | Invalid                                 |
+| ---------------- | --------------------------------------------------------------------------------- | --------------------------------------- |
+| Identifier rule  | `[a-zA-Z_][a-zA-Z0-9_-]*`                                                         | Contains dots, spaces, or special chars |
+| Hyphens allowed? | **Yes** in identifiers                                                            | Not dots                                |
+| Dots allowed?    | **Only in FQNs** (for scope separation)                                           | Never in a single identifier name       |
+| `payment-api`    | ✓ identifier                                                                      | —                                       |
+| `payment.api`    | ✗ identifier, but valid as FQN if `payment` and `api` are nested parents/children | —                                       |

package/skills/likec4-dsl/references/include-predicates-wildcards.md

@@ -63,6 +63,7 @@ views {
 ```
 
 **Key facts:**
+
 - `include *` in a scoped view = the scoped parent + **direct children only**
 - Grandchildren inside `*` context are **not** included (you'd need `include cloud.backend.**` or explicit FQN inclusion)
 - Relationship predicates like `->` and `<->` can further expand what neighbors appear
@@ -125,7 +126,7 @@ views {
 }
 ```
 
-This **does not change the base set of elements**; it only **includes relationships** that end in the visible elements. Neighbors of the scope that have incoming edges *do* appear because they are needed to render those edges visually.
+This **does not change the base set of elements**; it only **includes relationships** that end in the visible elements. Neighbors of the scope that have incoming edges _do_ appear because they are needed to render those edges visually.
 
 ## Wildcard `**` vs. explicit include
 
@@ -158,22 +159,22 @@ views {
 
 ## Common mistakes
 
-| Wrong | Right | Why |
-|---|---|---|
-| Bare `include **` or `exclude _` | `include cloud.**`, `exclude * where tag is #deprecated` | `**` and `_` are suffixes on an element reference, not standalone wildcards |
-| `include cloud.**` expecting only immediate children | `include cloud.*` | `**` is recursive; use `*` for one level |
-| Forgetting to add relationship filters in scoped view | `include *` + `include -> parent` | Relationships may not auto-render without explicit inclusion |
-| Assuming `include *` includes grandchildren | Use `include cloud.**` instead | `*` is immediate children only |
+| Wrong                                                 | Right                                                    | Why                                                                         |
+| ----------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Bare `include **` or `exclude _`                      | `include cloud.**`, `exclude * where tag is #deprecated` | `**` and `_` are suffixes on an element reference, not standalone wildcards |
+| `include cloud.**` expecting only immediate children  | `include cloud.*`                                        | `**` is recursive; use `*` for one level                                    |
+| Forgetting to add relationship filters in scoped view | `include *` + `include -> parent`                        | Relationships may not auto-render without explicit inclusion                |
+| Assuming `include *` includes grandchildren           | Use `include cloud.**` instead                           | `*` is immediate children only                                              |
 
 ## Summary table
 
-| Form | Matches | Scope context |
-|---|---|---|
-| `*` | Direct children + sibling relationships | One level down |
-| `parent._` | `parent` + direct children that have relationships with visible elements | One level down |
-| `parent.**` | All descendants recursively | Any depth |
-| `include -> element` | Inbound relationships to element | Shows external sources |
-| `include element ->` | Outbound relationships from element | Shows targets |
-| `include a <-> b` | Relationships between `a` and `b` in either direction | Shows symmetric dependencies |
+| Form                 | Matches                                                                  | Scope context                |
+| -------------------- | ------------------------------------------------------------------------ | ---------------------------- |
+| `*`                  | Direct children + sibling relationships                                  | One level down               |
+| `parent._`           | `parent` + direct children that have relationships with visible elements | One level down               |
+| `parent.**`          | All descendants recursively                                              | Any depth                    |
+| `include -> element` | Inbound relationships to element                                         | Shows external sources       |
+| `include element ->` | Outbound relationships from element                                      | Shows targets                |
+| `include a <-> b`    | Relationships between `a` and `b` in either direction                    | Shows symmetric dependencies |
 
 **In scoped views:** `include *` establishes a base set of the scope parent + immediate children. Relationship predicates like `->` and `<->` can bring in neighboring elements needed to render those relationships.

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

@@ -111,22 +111,53 @@ model {
 
 ## Element Properties
 
-| Property        | Values                                                                                   |
-| --------------- | ---------------------------------------------------------------------------------------- |
-| **title**       | String, single line                                                                      |
-| **description** | String, prefer Markdown. If > 150 chars, also add `summary`.                             |
-| **summary**     | String, max 150 characters                                                               |
-| **technology**  | String, no multi-line                                                                    |
-| **style**       | `style { ... }` — see `references/style-tokens-colors.md`                                |
-| **icon**        | Shortcut for `style { icon ... }`, takes precedence over the style block                 |
-| **metadata**    | `metadata { KEY VALUE }` — key is identifier format; value is string or array of strings |
-| **link**        | `link URL "Optional title"` — repeatable; URL can be relative to the document            |
-| **navigateTo**  | ID of a dynamic view to navigate to on click                                             |
+| Property        | Values                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------ |
+| **title**       | String, single line                                                                        |
+| **description** | String, prefer Markdown; link other elements with `[[fqn]]`. If > 150 chars, add `summary` |
+| **summary**     | String, max 150 characters                                                                 |
+| **technology**  | String, no multi-line                                                                      |
+| **style**       | `style { ... }` — see `references/style-tokens-colors.md`                                  |
+| **icon**        | Shortcut for `style { icon ... }`, takes precedence over the style block                   |
+| **metadata**    | `metadata { KEY VALUE }` — key is identifier format; value is string or array of strings   |
+| **link**        | `link URL "Optional title"` — repeatable; URL can be relative to the document              |
+
+Elements have no `navigateTo` property. To set where a click on an element navigates, override it in a view: `include api with { navigateTo detail }`.
 
 ## Relationship Properties
 
 `title`, `description`, `technology`, `metadata`, `style`, `link`, `navigateTo`
 
+## Element Links in Markdown
+
+Markdown values (`'''…'''` / `"""…"""`) can link to elements and views of the current project:
+
+```likec4
+model {
+  cloud = system 'Cloud' {
+    ui = container 'Web UI'
+    api = container 'API' {
+      summary '''
+        Serves [[cloud.ui]]
+      '''
+    }
+    ui -> api 'calls' {
+      description '''
+        Requests go to [[cloud.api|the API]], see [[view:index]].
+        Not a link: \\[[cloud.api]] and `[[cloud.api]]`
+      '''
+    }
+  }
+}
+```
+
+- `[[fqn]]` renders the element title, `[[fqn|Label]]` a custom label, `[[view:id]]` the view title. In the diagram, links open the element details or navigate to the view.
+- Works in every Markdown value: element, deployment, relationship and view `description`, `summary`, `title`, `technology`, `notes`, metadata values. Plain `'…'` strings and code (inline or fenced) are not scanned.
+- FQN is absolute and resolved in the current project only: `[[cloud.backend.api]]`, never `[[api]]` or `[[this]]`. Imported elements are not supported.
+- Escaping follows DSL strings: literal `[[` is `\\[[`; in a Markdown table cell write the separator as `\\|`, e.g. `[[cloud.api\\|API]]`.
+- Unknown element, unknown view, or unknown `prefix:` is a **warning**: the model still builds and `likec4 validate` stays valid unless `--max-warnings` is given. In the editor, `[[` triggers completion and Go to Definition jumps to the target.
+- Prefer `[[fqn]]` over repeating element names in descriptions; link only elements that exist.
+
 ## Extend Patterns
 
 ```likec4